. . . . . . . . .. . . . . . . . . . . . . . . . . The C64 Banner Exchange
GameBase Documentation
(c) 1997-2002 James Burrows
Please note this is still in beta stage and is subject to change.
GEMUS (Gamebase EMUlator Script) Guide
Quick Start Guide
Skipping all the info on why/what/how, this is the quickest way to get your games running in an emulator: -
1. Click Supported Emulator File Types from the GEMUS menu in the main GameBase window.
2. Enter all the file types your emulator supports, seperated by the ; character. For MAME, simply enter zip here.
3. Click Manage Emulators from the GEMUS menu in the main GameBase window.
4. Click the New Emulator button (the first button in the toolbar).
5. Enter a name for your emulator, select it's executable file, tick the Use short (8.3) filenames checkbox and accept the default GEMUS script* and filetypes by clicking OK. Give your script a filename when prompted and click Save. Now click OK until you are back to the main GameBase window.
6. Go into Options (from the Tools menu in the main GameBase window) and add the path where your games/roms are stored. (Note: GameBase doesn't support rom directories (i.e. single games having their own rom directories) so you'll have to zip your roms if you want GameBase to support them).
7. Press CTRL+INS to add a game, pick one of your Game Files/Roms, then click ok. Give the game a name and any other details until it appears added in the game list.
8. Select the game and click the Play Game button!
* This quick start should work for 90% of emulators. If it doesn't, you'll have to check the emulators command line parameters and config settings and then amend the GEMUS script accordingly.
What is a GEMUS?
Emulators on the PC are forever changing. New versions are released with different command line parameters and configuration settings, even entirely new emulators are released from time to time. This makes it very difficult for emulator frontends to continue to fully support these emulators without constantly releasing newer versions as the emulator scene changes.
GameBase tackles this problem of ever-changing emulators by introducing a simple yet effective scripting language which will allow the continued support of existing emulators and new emulators with minimum fuss and maximum flexibility. The advantage of having a scripting language to run emulators also means that you can easily and quickly tailor the scripts to run the emulators exactly the way you want to.
GEMUS (Gamebase
EMUlator Script) is a complete emulator and game manager. With
it you can manage single or multiple emulators per emulation system. The main
idea behind the GEMUS system is to be able to force an emulator to run in a
specific way, depending on the type of game being run, and what information
is available for that game. For example, this makes it possible to easily set
an emulator's joystick control settings or drive loading mode depending on what
fields are set in the GameBase database for that game.
Understanding GEMUS
Each database that you create or use with GameBase has it's own unique GEMUS setup. This means you can setup a single emulator for each database, or a group of emulators for each database. For example, you could have a MAME database that has one single emulator (MAME), and you can have a C64 database that has various emulators (CCS64, VICE, C64S etc). You can even have a database that holds multi-system games, for example a console database, where you might have emulators setup for SNES, PS1, SATURN, MEGADRIVE etc). GEMUS works best, however, when you have a seperate database for each emulation system (one for C64, one for MAME, one for SNES etc), but this is not a requirement, only a recommendation.
GEMUS has 3 main phases when running games: -
1. Obtain the correct Game File
GEMUS internally stores a global list of supported game file types for the emulators it manages. This is a list of filename extensions that correspond directly to the types of files that the emulators support.
You can specify the file types for this list by selecting Supported Emulator File Types from the GEMUS menu in the main GameBase window. Note that this list should contain *ALL* the filetypes for *ALL* the emulators you want GEMUS to manage in your chosen GameBase database.
When running a game, GEMUS will first check if the game file type matches any of those in the list of supported types. If it finds a match, then GEMUS will skip the archive-extraction procedure and go on to choose the appropriate emulator.
If no match is found, GEMUS will then check if the game file needs extracting (e.g. zipped games). Supported compressed file types are listed here.
The extraction routine will recursively extract the game until a file with an emulator supported file type is found. If no such file is found, GEMUS will abort running the game.
Note: If more than one supported game file is found within the compressed archive, GEMUS will check if any of them have been previously selected to use for the current game. If no match is found, GEMUS will prompt you to pick from the available files.
2. Choose Appropriate Emulator to use
Once GEMUS has the correct game file to run, it will decide whether it needs to choose the most appropriate emulator or not.
If a specific emulator was already chosen (e.g. you right-clicked the 'Play Game' button in the main GameBase window and manually selected an emulator), then GEMUS will use that emulator and will skip the selection process.
If a specific emulator was NOT chosen (e.g. you left-clicked the 'Play Game' button in the main GameBase window), then GEMUS will search through the list of available emulators (in your specified order) until it finds the first one that supports the game's file type. If no emulator supports the game's file type, GEMUS will abort running the game.
3. Execute a GEMUS script to run the game
When GEMUS gets to this stage, it knows it has a valid emulator-supported game file, and it knows which emulator to run it with. GEMUS will now process the script you specified for the chosen emulator, which in turn will run the game.
The simplest script, which works with most emulators (i.e. when the game file is used as a command-line parameter of the emulator), is: -
Add_CLP(%gamepathfile%)
Run_Emulator()
This script adds the game file to the emulator's command line parameters, then runs the emulator.
For a full GEMUS script language guide, including functions to edit config and ini files, click here.
Supported Compressed Game File Types
The following compressed archives are currently supported by GEMUS: -
.ZIP, .LHA, .LZH, .LNX (C64) and Zipcoded (C64 filepacked/diskpacked).
.ZIP support is handled internally by GEMUS.
.LHA/.LZH support requires that LHA for DOS ((C) by Haruyasu Yoshizaki, 1988-1992) be placed in your GameBase installation folder or somewhere in your path. Note: GEMUS needs LHA.EXE v2.14 or newer in order to be able to extract files properly.
.LNX (C64 file format) support requires that STARLYNX for DOS ((c) Joe Forster/STA) be placed in your GameBase installation folder or somewhere in your path. Note: GEMUS needs STARLYNX.EXE v0.81 or newer in order to be able to extract files properly.
Filepacked (A!, B!, C!, D!) and diskpacked (1!, 2!, 3!, 4!) zipcode (C64 file format) support requires that STARZIP for DOS ((c) Joe Forster/STA) be placed in your GameBase installation folder or somewhere in your path. These archives are only supported if contained within a single file compressed archive like LHA and ZIP). Note: GEMUS needs STARZIP.EXE v0.81 or newer in order to be able to extract files properly.
How GEMUS Extracts Compressed Game Files
Due to the many different types of archived game files out there on the web, GEMUS employs a recursive extraction routine in order to support as many of these archives as possible. For example, this makes it possible to support archives such as a zipped, then lha'd, then zipped game file (even though this example would be pointless! ;-).
When extracting compressed games, GEMUS will first copy the archive to the GBGame folder (usually at the root of your GameBase installation drive). It will then attempt to extract the archive in Passes. Each pass will extract the archive's contents into a new subfolder. The extraction will continue until either the required emulator compatible game file is found or no more extraction passes can occur. If and when the compatible game file is found, it is copied to the ReZip folder inside the GBGame folder and GEMUS continues to run it in the chosen emulator.
E.g.
Archive = c:\c64\games\game.lha
1. Copy c:\c64\games\game.lha
to c:\GBGame\
2. Extract game.lha (using lha.exe) to c:\GBGame\P1\
3. Found game.zip
4. Extract game.zip to c:\GBGame\P1\P2\
5. Found game.lha
6. Extract game.lha (using lha.exe) to c:\GBGame\P1\P2\P3\
7. Found diskpacked zipcoded archive (1!game.z64, 2!game.z64,
3!game.z64, 4!game.z64)
8. Extract diskpacked zipcoded archive (using starzip.exe) to c:\GBGame\P1\P2\P3\P4\
9. Found game.d64 (emulator compatible file found!)
10. Copy c:\GBGame\P1\P2\P3\P4\game.d64 to c:\GBGame\ReZip\
11. GEMUS runs c:\GBGame\ReZip\game.d64 in the specified emulator.
Game File Database Fields used by GEMUS
In each GameBase database, 3 game fields are reserved specifically for GEMUS: -
1. [Filename]
The actual subfolder\filename of the game file linked to the game (within your
game paths).
2. [FilenameIndex]
For D64's and T64's (C64 game-files) this contains the image index inside the
file of the PRG to run in the specified emulator. For other file types this
should be 0.
3. [FileToRun]
If the game file set in the [Filename] field is a compressed archive and contains
more than one supported native emulator file, this will be set to the filename
(without path) to run within the archive.
You can use many of the GameBase database fields in GEMUS scripts. Check the GEMUS Script Guide for more info.
GEMUS Script Basics
| A simple script explained |
| The structure of a GEMUS script |
| The script's Associated Files |
| Environment Variables |
| Using Short and Long Filenames |
One of the best ways to understand any scripting language is to walkthrough an example, line by line. So let's start with an example of a very simple GEMUS script that will run a game in an imaginary emulator that only supports D64 game files: -
The Script:
; A simple script for an imaginary emulator! If GameType CONTAINS(D64) Add_CLP(-autorun %gamepathfile%) Run_Emulator() Else Show_Message(The game is not supported by this emulator!) End If
Line by line explanation:
; A simple script for an imaginary
emulator!
This line is a comment
and is ignored by the script engine.
If GameType CONTAINS(D64)
This is a comparison line that tests if the game being run by the script is
a D64 (a C64 game file type). If the game file is a D64 then the following lines
will be executed until the corresponding Else
statement is encountered.
Add_CLP(-autorun %gamepathfile%)
This line is only
processed if the game's filetype is a D64. It will add the text (enclosed within
the parentheses) to the emulator's command line parameters. The text %gamepathfile%
is known as an environment variable. In this case
it will be replaced in the command line with the game's path and file. So the
total command line parameters might be "-autorun c:\games\a\arkanoid.d64".
Run_Emulator()
This line invokes
the emulator, which is executed with the command line parameters that were added
in the previous line!
Else
This line tells the script to execute the following statement(s) if the preceding
If statement evaluated to false
(in this case, the script would start here if the game's filetype was not a
D64).
Show_Message(The game is not
supported by this emulator!)
If the game is not
a D64, this line is executed and will display a message telling you the game
type is unsupported!
End If
This line signifies the end
of the conditional If/Else test
and because there are no more lines the script will terminate!
The structure of a GEMUS script
A GEMUS script is a series of commands or statements that are executed sequentially until the end of the script is reached. The script is made up from a series of lines each containing a single command or statement. Each script line is trimmed of whitespace before being processed (leading and trailing spaces or tabs are removed). Script lines can be broken down into one of four types:
1. Functions
These are the lines in the script that actually do stuff, like run the emulator
or write to a config file. For a list of functions click
here.
2. Comparison
statements
These lines determine the flow of the script. You can test if certain game options
are set with these lines. Comparison statements generally evaluate an expression
and process any following lines depending on the outcome of the expression.
See the If/ElseIf/Else/End If structure.
3. Comments
Any line commencing with the ;
character is a comment. These lines are ignored by the script engine.
4. Blank lines
These are ignored by the script engine.
The If/ElseIf/Else/End If block structure:
This structure controls flow through the script and determines which functions are executed. The basic structure is as follows: -
If condition [statements] [ElseIf condition [statements] ...] [Else [statements]] End If
[statements]
are any number of script lines that are valid GEMUS functions,
or embedded If/ElseIf/Else/End
If structures.
condition is any
comparison expression that can be evaluated in accordance to the Comparison
Fields rules.
The If and End If statements are compulsory for starting and ending the structure. The Else and ElseIf clauses are both optional. You can have as many ElseIf clauses as you want in an If block, but none can appear after an Else clause. If statements can be nested; that is, contained within one another.
When executing an If, condition is tested. If condition is True, the statements following it are executed. If condition is False, each ElseIf condition (if any) is evaluated in turn. When a True condition is found, the statements immediately following the associated ElseIf are executed. If none of the ElseIf conditions are True (or if there are no ElseIf clauses), the statements following Else are executed. After executing the statements following If, ElseIf or Else, script execution continues with the statement following the End If.
Example:
Add_CLP(-game %gamefile%)
If Control = JoyPort1 Add_CLP( -joy1 PCJoy1) ElseIf Control = JoyPort2 If NumPlayers > 1 Add_CLP( -joy2 PCJoy1 -joy1 PCJoy2) Else Add_CLP( -joy2 PCJoy1) End If ElseIf Control = Mouse Add_CLP( -mouse) Else Add_CLP( -nojoy) End If Run_Emulator()
A GEMUS script is pretty much useless without files to operate on. If the script does not know what the emulator executable file is, or what it's config file is, it won't be able to change any settings or run the emulator!
Certain functions in a GEMUS script make use of these files. These functions use a file number as a parameter to point to a file you have previously specified in the Emulator Properties window. There are 2 types of file that you should set. The first is the actual Emulator executable. This is used by the Run_Emulator function, which will fail if you have not specified this file. The other type of file you can specify is an Associated File. These are files that can be used in the functions Run_Program, Set_CFG_Value and Set_INI_Value. You simply set the file in the Associated Files box, and use the file's number in the script!
The filenames of the associated files themselves could have been used in the script, but this would not have made the scripts very portable across systems as different people store their files in different places. For this reason, file numbers were used to identify the files instead. This way, to create a script that someone else can use, all you have to do is include comments in the script telling people which files to match with the file numbers used in the script!
When a script is executed, Gamebase64 will internally set a list of variables that may be needed for running the chosen game in the selected emulator. These variables are such things as the game filename, the game path, and the image name or index within the game file. When you write a script, you can include these variables in parameters to certain functions. All GEMUS environment variables start and end with the % character, for example %gamefile%, %imageindex%. During execution of a script, these variables will be replaced by their actual values in the function parameters before each function is executed. See Using Short and Long Filenames for related information.
Using Short and Long Filenames
All script environment variables that correspond to a filepath or filename will be replaced in the script depending on the setting of the Use Short Filenames checkbox in the Emulator Properties window.
If this value is
checked, path and filename variables will be replaced with their short (8.3)
DOS filename equivalents when the script is executed.
For example:
c:\progra~1\gameba~1\games\imposs~1.d64
If this value is
not checked, path and filename variables will be replaced with their long filename
equivalents.
For example:
c:\program files\gamebase64\games\impossible mission.d64
When using the
Add_CLP and Run_Program functions
to add text to the emulator's or the program's command line parameters, any
long filename variables are surrounded in double quotes ("") only
if they contain a space character.
For example:
"c:\program files\gamebase64\games\impossible mission.d64"
has quotes around it whereas c:\games\impossible_mission.d64
has no quotes around it.
Quotes are only added when using the Add_CLP and Run_Program
functions. Quotes are not added for any other function.
Note: When using emulators or programs that run in MSDOS mode, you should always use short filenames.
Script Comparison Fields Reference
| Names and descriptions |
| Operators |
| FIELD NAME | OPERATORS | DESCRIPTION |
| GameType | CONTAINS | This
field signifies the type of game being run by the script. It directly correlates
to the game's filename extension (without the preceding "." character).
Possible values for this field might be D64, TAP etc.. Example: If GameType CONTAINS(D64||TAP) |
| Control | =, != | This
field signifies the primary control method of the game being run by the
script. This field will contain one of the following values: JoyPort1,
JoyPort2, Keyboard, PaddlePort1, PaddlePort2,
Mouse, LightPen, KoalaPad or LightGun. Example: ElseIf Control = JoyPort2 |
| NumPlayers | =, !=, <, > | This
field signifies the number of players that the game being run by the script
supports. This will typically be a number larger than 0. Example: If NumPlayers > 1 |
| PalNTSC | =, != | This
field signifies the whether the game being run by the script is Pal or NTSC
compliant. This field will contain one of the following values: PAL,
NTSC or BOTH. Example: ElseIf PalNTSC = NTSC |
| GameComment | CONTAINS | This
field signifies the "Game Comment" database field of the game
being run by the script. Example: If GameComment CONTAINS(*password is:*) |
| VersionComment | CONTAINS | This
field signifies the "Version Comment" database field of the game
being run by the script. Example: ElseIf VersionComment CONTAINS(*load manually*) |
| ImageName | CONTAINS | This
field contains the same value as the %imagename% script
environment variable. Example: ElseIf ImageName CONTAINS(*) (not: If %imagename% CONTAINS(*)). Note: you cannot use the %imagename% variable as a comparison field name, nor can you use the ImageName field name as an environment variable. Be careful not to confuse the two - field names are for comparisons only, whilst environment variables are for replacing text in function parameters only. |
|
NumFiles |
=, !=, <, > | This
field signifies the number of game files selected for the game being run
by the script. It contains the same value as the %numfiles% script
environment variable. Note: you cannot use the %numfiles% variable
as a comparison field name, nor can you use the NumFiles field name
as an environment variable. Be careful not to confuse the two - field names
are for comparisons only, whilst environment variables are for replacing
text in function parameters only. Example: If NumFiles = 2 (not: If %numfiles% = 2) |
| QUESTION(text) | = | This
field is really a comparison function. It will display a message window
asking the question text to the user, who must respond by either
clicking a YES or NO button to answer the question. Example: If QUESTION(Do you want to run in NTSC mode?) = YES |
| Key_keyname | CONTAINS | The
Key_keyname fields give you lots of flexibility in GEMUS. In the
Notes field (details tab 4 in the main GameBase window) for each game, you
can optionally put in key=value pairs. These pairs can really be
anything you like, for instance memory=512 or fullscreen=yes.
By creating these pairs, you can test for virtually any game-specific setting
or option within a GEMUS comparison statement. To specify the field, just
put the prefix "Key_" before the name of the key you want
to test. Example: If Key_memory CONTAINS(512) See also the %keyname_value% environment variable. |
Script Comparison Fields Reference | Top
Script Comparison Fields Reference | Top
Script Environment Variables Reference
| %gamefilepath% | The full path and filename of the game being run. For example: c:\games\s\sanxion.d64 |
| %gamefile% | The filename (without the path) of the game being run. For example: sanxion.d64 |
| %gamepath% | The path (without the filename) of the game being run. For example: c:\games\s |
| %gamefilenoext% | The filename (without the path or filename extension) of the game being run. For example: sanxion |
| %imageindex% | For D64 and T64 files (C64 file types), this will be set to the zero-based index of the game to run within the file. For all other game filetypes, this is always set to 0. For example: 0, 1, 2, 3, etc.. |
| %imagename% | Also see %c64imagename% (below). For D64 and T64 files (C64 file types), this will be set to the C64 image name that corresponds to the selected image index contained in %imageindex%. For a T64 file with no selectable image, it will be set to empty. For all other game filetypes this variable will be empty. For example: SANXION++, MONTY ON THE RUN etc.. |
| %c64imagename% | This differs to %imagename% (above) in that it converts the characters contained in it into C64 format (changing upper case to lower case). This variable was implemented to enable C64 emulators such as VICE to autoload images. For D64 and T64 files, this will be set to the C64 image name that corresponds to the selected image index contained in %imageindex%. For a T64 file with no selectable image, it will be set to empty. For all other game filetypes this variable will be empty. For example: SANXION++, MONTY ON THE RUN etc.. |
|
%gamefilepath(x)% |
Extra Game Files. If the game specified by the %game...% variables above has more than one game file (e.g. is a multi-disk game) then these variables will point to these extra game files. (x) is the index number (1 based, not zero-based) of the game file in question: %game...(1)% being the first extra game file, %game...(2)% being the second extra game file etc.. until there are no more game files. The number of extra game files is determined by the following rules: - If the initial gamefile ends in a number, then extra gamefiles will be counted based on the incrementing last number. For example, if the initial %gamefile% is "REALMS0.D64" then %gamefile(1)% will be "REALMS1.D64", %gamefile(2)% will be "REALMS2.D64" etc. until no more game files can be found. If the initial gamefile ends in a letter, then extra gamefiles will be counted based on the incrementing last letter. For example, if the initial %gamefile% is "SUMGAMES1A.D64" then %gamefile(1)% will be "SUMGAMES1B.D64", %gamefile(2)% will be "SUMGAMES1C.D64" etc. until no more game files can be found. |
| %numfiles% | The total number of game files as defined in the rules for the %game...(x)% variables above. This number reflects ALL the game files for the game being run, not just the extra ones described above. |
| %crlf% | The Carriage Return and Line Feed character pair. This can be used in the Show_Message function to start a new line of text. |
| %crlfx2% | The Carriage Return and Line Feed character pair multiplied by 2! This can be used in the Show_Message function to insert a blank line in the text. |
| %tab% | The Tab character. This can be used in the Show_Message function. |
| %commandline% | The current contents of the emulator's command line. This can be used in the Show_Message function to help bug-test your own custom scripts. |
| %keyname_value% | See the Key_Keyname comparison fields. To use the value of any of the keys you specified in the Notes field for a game, simply substitute keyname for the name of the key in the key=value pair. For example, if you have a key=value pair: fullscreen=yes, then the environment variable that contains the text "yes" would be %fullscreen_value%. |
Script Function Reference
| Add_CLP |
| Run_Emulator |
| Run_GameFile |
| Run_Program |
| Set_CFG_Value |
| Set_INI_Value |
| Show_Message |
| Edit_CLP |
| Clear_CLP |
The Add_CLP Function
Adds text to the emulator's command line parameters.
Syntax:
Add_CLP(text)
Parameters:
| text | Required. The text to add to the emulator's command line. Any script environment variables found in text will be replaced by their actual values when the script is executed. |
Examples:
1 Add_CLP(%gamefile%,%imageindex%) 2. Add_CLP( -autotype "LOAD")
Note the " " (space) at the start of the second example's parameters. This is needed when continuing the command line across multiple Add_CLP calls, as exacty whatever is enclosed within the parentheses is directly appended to the command line. If you called both examples above one after the other, without including the space character in the second example, the resulting command line would be: -
%gamefile%,%imageindex%-autotype
"LOAD"
instead of:
%gamefile%,%imageindex% -autotype
"LOAD"
Remarks:
You can call this function multiple times, each one adding more text to the emulators' command line parameters. If the script is set to use long filenames, any replaced environment variables that correspond to a filepath or filename will be surrounded by double quotes ("") only if they contain a space character.
Script
Function Reference | Top
The Run_Emulator Function
Runs the C64 emulator with any command line parameters that have previously been set using the Add_CLP function.
Syntax:
Run_Emulator([DOSCLOSE])
Parameters:
| DOSCLOSE | Optional. If the literal string DOSCLOSE is supplied as a function parameter and the script's emulator runs in MSDOS mode, the DOS command window will be automatically closed when the emulator closes. You should only supply this parameter if the script's emulator runs in MSDOS mode. |
Examples:
1 Run_Emulator() 2. Run_Emulator(DOSCLOSE)
Remarks:
On some systems, emulators that run in MSDOS mode only allow a command string to be a certain length. If you find that the emulator will not execute, try reducing the length of the command line parameters. A common reason for this is because you have added the game's path to the command line parameters and the path is too long or has too many subfolders. Try moving your game path nearer to the root of it's current drive and ensure that you have selected to use short 8.3 filenames.
Script Function Reference | Top
The Run_GameFile Function
Similar to the Run_Emulator function, except this will run the game file as an executable, not the emulator (any command line parameters that have previously been set using the Add_CLP function will be applied to this function). This function was implemented primarily for single game emulators that do not need an emulator to run them - they are the emulator!
Syntax:
Run_GameFile([DOSCLOSE])
Parameters:
| DOSCLOSE | Optional. If the literal string DOSCLOSE is supplied as a function parameter and the game file executable runs in MSDOS mode, the DOS command window will be automatically closed when the game file executable closes. You should only supply this parameter if the script's game file executable runs in MSDOS mode. |
Examples:
1 Run_GameFile()
2. Run_GameFile(DOSCLOSE)
Remarks:
On some systems, emulators that run in MSDOS mode only allow a command string to be a certain length. If you find that the emulator will not execute, try reducing the length of the command line parameters. A common reason for this is because you have added the game's path to the command line parameters and the path is too long or has too many subfolders. Try moving your game path nearer to the root of it's current drive and ensure that you have selected to use short 8.3 filenames.
Script Function Reference | Top
The Run_Program Function
Runs a program.
Syntax:
Run_Program(filenum||clp||waitflag)
Parameters (separated by the || delimiter):
| filenum | Required. Number of the file set in the script's Associated Files list that you want to execute. If this file is not directly executable, it will be run with it's default program (e.g. if you set the file to be a text file, it will be opened in notepad). |
| clp | Required. The text to add to the command line of the program being executed. Any script environment variables found in clp will be replaced by their actual values when the script is executed. To specify no command line parameters, set this to an empty string (see example 1). If the script is set to use long filenames, any replaced environment variables that correspond to a filepath or filename will be surrounded by double quotes ("") only if they contain a space character. |
| waitflag | Required. This must be one of two literal strings: WAIT or NOWAIT. If you want the script to pause until the executed program has terminated before continuing, set this parameter to WAIT, otherwise set it to NOWAIT. |
Examples:
1 Run_Program(1||||NOWAIT) 2. Run_Program(2||%gamepath%\cover.jpg||WAIT)
Remarks:
When specifying the WAIT flag to pause until the executed program has finished, please note that this only waits on the program being run (as specified in the filenum parameter). If this program launches another program then immediately closes, the script will continue as soon as the first program has closed (the second launched program will not be waited on).
Script Function Reference | Top
The Set_CFG_Value Function
Sets a value in a config file. Some emulators use their own config file instead of an INI file to specify their settings. If the file does not contain standard INI file [sections] but contains key=value pairs then you should use this function. If the file has standard INI file [sections] you should use the Set_INI_Value function.
Syntax:
Set_CFG_Value(filenum||key||value)
Parameters (separated by the || delimiter):
| filenum | Required. Number of the file set in the script's Associated Files list that you want to set the value in. This file should point to a valid emulator's config file. |
| key | Required. The key within config file whose value you want to set. Any script environment variables found in key will be replaced by their actual values when the script is executed. |
| value | Required. The desired value of the key key in the config file that you want to set. Any script environment variables found in value will be replaced by their actual values when the script is executed. |
Examples:
1 Set_CFG_Value(1||$LOADPATH||%gamepath%) 2. Set_CFG_Value(4||$MODE||Windowed)
Remarks:
If the key cannot be found in the specified config file it will be created and set to the specified value. When the script is executed, a warning message will be displayed if the file cannot be found.
Script Function Reference | Top
The Set_INI_Value Function
Sets a value in an INI file. Some emulators use config files that are Windows INI files to set various options. If the file contains standard INI file [sections] that contain key=value pairs then you should use this function. If the file does not have standard INI file [sections] you should use the Set_CFG_Value function.
Syntax:
Set_INI_Value(filenum||section||key||value)
Parameters (separated by the || delimiter):
| filenum | Required. Number of the file set in the script's Associated Files list that you want to set the value in. This file should point to a valid windows initialisation file. |
| section | Required. The INI file section that contains the key whose value is to be set. Any script environment variables found in section will be replaced by their actual values when the script is executed. You do not need to surround section in square brackets. |
| key | Required. The key within the section section whose value you want to set. Any script environment variables found in key will be replaced by their actual values when the script is executed. |
| value | Required. The desired value of the key key in the section section that you want to set. Any script environment variables found in value will be replaced by their actual values when the script is executed. |
Examples:
1 Set_INI_Value(1||Config||LoadPath||%gamepath%) 2. Set_INI_Value(4||Control||JoystickPort||2)
Remarks:
If the key cannot be found in the specified INI file it will be created and set to the desired value. When the script is executed, a warning message will be displayed if the file cannot be found.
Script Function Reference | Top
The Show_Message Function
Displays a message to the user and waits until the user clicks an 'OK' button before continuing.
Syntax:
Show_Message(message)
Parameters:
| message | Required. The message you want to display. There is one preset message, which you can display by setting message to the string literal GAME_NOT_SUPPORTED. Any script environment variables found in message will be replaced by their actual values when the script is executed. |
Examples:
1 Show_Message(You have to load this game manually: %gamefile%) 2. Show_Message(GAME_NOT_SUPPORTED)
Remarks:
The Show_Message function can be used to help you bug-test your own custom scripts! You can use the %commandline% environment variable to see the contents of the emulator's command line at any one time.
Script Function Reference | Top
The Edit_CLP Function
Displays the current emulator command line contents for the user to edit.
Syntax:
Edit_CLP(message)
Parameters:
| message |
Required. The message you want to display. This should generally be the prompt you want to display to the user. Any script environment variables found in message will be replaced by their actual values when the script is executed. Note: This message is not for specifying a GEMUS environment variable to change, it is meant only for a user prompt (see example below). A future version of GEMUS may support a function where you can specify an environment variable to change. |
Examples:
1. Edit_CLP(Edit the command line now if you're brave enough!) 2. Edit_CLP(The memory to set for this game is %memory_value%)
Remarks:
The best place to put this function is just before you call the Run_Emulator or Run_GameFile functions.
Script Function Reference | Top
The Clear_CLP Function
Clears the contents of the emulator's command line.
Syntax:
Clear_CLP()
Parameters: None
Example:
Clear_CLP()
Remarks:
You probably won't need this much, unless you are running two emulators, one after the other, or something similar.
Script Function Reference | Top
. . . .
. . . . . . . . .. . . . . . . . . . . . . . . . .
The
C64 Banner Exchange