====== GEMUS Guide ====== ===== Quick Start ===== Skipping all the info on why/what/how, this is the quickest way to get your games running in an emulator: - **1**. Click Manage Emulators from the GEMUS menu in the main GameBase window. **2**. Click the New Emulator button (the first button in the toolbar). **3**. Enter a name for your emulator, select it's executable file, tick the Use short (8.3) filenames checkbox, un-tick the filetypes box and enter the filetypes of the games your emulator supports (e.g. T64;D64;PRG;CRT), and accept the default GEMUS script* 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. **4**. Go into Paths (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). **5**. 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. **6**. 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 GEMUS ===== **GEMUS** (**G**ameBase **EMU**lator **S**cript) is a complete emulator and game manager. With it you can manage single or multiple emulators per GameBase database. 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. ===== How GEMUS Works ===== 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. 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 (usually) skip the archive-unpacking procedure and go on to choose the appropriate emulator. If no match is found, GEMUS will then check if the game file needs unpacking (e.g. zipped games). Supported archive file types are listed below. The unpacking 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 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, or the 'emu=xxx' key=value pair pointed to a specific 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. **4. Optionally Repack the game file** When GEMUS has finished running the game and has waited for the emulator to finish, it will (according to your database's preferences) optionally Repack the game if it was previously unpacked. Repacking will only take place if the following conditions are met: - * You have turned on game repacking in GB's Options. * The game was an archive that was unpacked. * Any of the files (in the final/used unpacked folder) CRC-checksums changed during play (or additional files are found). * The main archive, and any contained sub-archives, were only of the following types: .7z .zip .gz .gzip .tgz .bz2 .bzip2 .tbz2 .tbz .tar **Note: GEMUS logs all activity when unpacking/running/repacking a game in the file Gemus.log, which will be saved to your GameBase folder.** ===== Supported Archive File Types ===== The following compressed archives are currently supported by GEMUS: - .7Z, .ZIP, .GZ, .GZIP, .TGZ, .BZ2, .BZIP2, .TBZ2, .TBZ, .TAR, .LZMA, .RAR, .CAB, .ARJ, .Z, .TAZ, .ISO, .LHA, .LZH For the above supported archive formats, GameBase requires that 7-Zip's 7z.exe and 7z.dll (min version 4.65) be placed in your GameBase installation folder, or somewhere in your path. Version 4.65 should be included with the full GameBase distribution, located in your GameBase install folder. GEMUS can Repack the following archive types: - .7Z .ZIP .GZ .GZIP .TGZ .BZ2 .BZIP2 .TBZ2 .TBZ .TAR ===== How GEMUS Extracts Archive Files ===== GEMUS is able to support archives within archives, letting you configure, for each game, which file within the archive you'd like to run. Let's say, for example, that you have the archive **games.zip**, which contains the following: - games.zip --> game1.zip --> runme.exe --> game2.7z --> somefile.foo --> bin\runme.bat Now lets assume you have 2 games in your database: **Game 1** and **Game 2**. GEMUS can be setup so that both of these games can use the same **games.zip** archive... Game 1 --> Game File: games.zip --> Runnable File: game1.zip:runme.exe Game 2 --> Game File: games.zip --> Runnable File: game2.7z:bin\runme.bat If the archive file contains only 1 "runnable" file (i.e. matching the emulator's configured file-types) then GEMUS will auto-select it. Where there is a conflict (multiple runnable files or sub-archives within the main archive) then GEMUS will ask you to choose which one to use (and will remember it from then on). You can change the selected runnable file from GameBase's Game File Selector window. When unpacking archives, GEMUS will extract the archive in Passes. Each pass will extract the archive's contents into a new folder. The unpacking will continue until either the required emulator compatible game file (runnable file) is found or no more extraction passes can occur. If and when the runnable file is found, GEMUS continues to run it in the chosen emulator. **E.g. (using the games.zip archive above)...** - Runnable file for "Game 2" is game2.7z:bin\runme.bat - Unpack games.zip to c:\GBGame\0\ - Found game2.7z - Unpack game2.7z to c:\GBGame\1\ - Found bin\runme.bat - GEMUS runs c:\GBGame\1\bin\runme.bat in the specified emulator **Note**: GEMUS will *always* look at the "runnable" file within archives when running games. So if you have set the emulator compatible filetypes to include .ZIP, and the game file is games.zip, it won't just run that: it'll still see that there is a runnable file set that points to a file within the archive (which may or may not be another zip file). ===== GEMUS Script Basics ===== ==== A simple script explained ==== 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: - ; 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 [[.:gemus_script_reference:environment_variables|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**. [[.:gemus_script_reference:functions:home|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**. [[.:gemus_script_reference:comparison_fields|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_script_reference:functions:home|GEMUS functions]], or embedded If/ElseIf/Else/End If structures. condition is any comparison expression that can be evaluated in accordance to the [[.:gemus_script_reference:comparison_fields|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() ==== The script's Associated Files ==== Certain functions in a GEMUS script make use of files. These functions can either use a file number as a parameter to point to a file you have previously specified in the Emulator Properties window, or they can use one of the [[.:gemus_script_reference:environment_variables|GEMUS Environment variables]] to specify a file path. There are 2 types of file that you should set. The first is the actual Emulator executable. This is used by the [[.:gemus_script_reference:functions:run_emulator|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 [[.:gemus_script_reference:functions:run_program|Run_Program]], [[.:gemus_script_reference:functions:set_cfg_value|Set_CFG_Value]], [[.:gemus_script_reference:functions:set_cfg_item|Set_CFG_Item]] and [[.:gemus_script_reference:functions:set_ini_value|Set_INI_Value]]. You can simply set the file in the Associated Files box and use the file's number in the script, or you can specify a textual path by using any of the [[.:gemus_script_reference:environment_variables|environment variables]].\\ \\ For example, the first parameter to each of the following function calls points to an //associated file//: Run_Program(%emupath%\setjoystick.exe||||NOWAIT) Run_Program(2||%gamepath%\cover.jpg||WAIT) ==== Environment Variables ==== When a script is executed, GEMUS 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.\\ \\ [[.:gemus_script_reference:environment_variables|Environment Variables Reference]] ==== Key=Value Pairs ==== Key=Value pairs give you the flexibility of specifying arbitrary variables that can be used in your GEMUS scripts. By pressing F2 in GameBase (when a game is selected) you can enter key=value pairs specifically for that game, along with managing sets of keys=value pairs (kvsets). e.g. mem=512 You can include all [[.:gemus_script_reference:environment_variables|GEMUS environment variables]] in the values, but not the keys. There are 2 special keys: * **emu=...** - This tells GEMUS to always attempt to run the game using the emulator specified in the value (the name of the emulator as it is listed in Emulators.ini, or in GameBase's Emulator properties window). \\ \\ * **kvset=...** - This is a custom key=value set. This will get replaced with a pre-defined list of key=value pairs (see below). key=value pairs in the kvset will be attributed to every game. You do not need to specify kvset=; it is applied implicitly. You setup custom kvsets that can be attributed to specific games by using the key=value pair kvset=[name of set]. This provides a convenient way to group related key=value pairs and avoids unnecessary data duplication. When a GEMUS script is run, the kvset always get applied first, then any custom kvsets (you can have more than one kvset linked per game), then finally the game's specific pairs. The more specific key=value pairs override the less specific ones (e.g. per-game pairs override kvset pairs, which override the global ones). You cannot have a key=value pair in a kvset link to another kvset. Some people have found it convenient to write GEMUS scripts where the script behaviour can be tweaked for each game almost solely with key=value pairs/sets, using the following technique: If %key_speed% CONTAINS(*) Add_CLP( -speed=%speed_value%) Else Add_CLP( -speed=100) Endif ==== 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 [[.:gemus_script_reference:functions:add_clp|Add_CLP]] and [[.:gemus_script_reference:functions:run_program|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 [[.:gemus_script_reference:functions:add_clp|Add_CLP]] and [[.:gemus_script_reference:functions:run_program|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.**