Modboy Game Configs are added to the Modboy Game Configs Script category and then included via the Master Config script. Modboy Game Config scripts must be in YAML format. For more information on YAML, check out this Wikipedia entry.

1. Config Layout

Each Modboy Game Config has 3 blocks:

Constants
Setup
FileRules

Example:

Constants:
 ...
Setup:
 ...
FileRules:
 ...

2. Constants

The Constants block is used by the Modboy client in dialog messages.

Constants:
 "{...}": "..."

Example:

Constants:
 "{GAME_NAME}": "Counter-Strike: Global Offensive"

3. Setup

The Setup block instructs the client on the steps that must be taken before mod installation occurs. This involves finding and changing to the game's root directory.

Setup:
- Command: ...
  Parameters:
   ...
  ErrorMessage: "..."

3.1. Command Types

3.1.1. Prompt

Show a prompt. The result of the prompt will be stored in a variable.

Parameters:

Type: Supports values Dir, File or String. When Type Dir or FIle, a File/Directory Browser will appear, allowing the user to navigate to the file or directory to choose it. When Type String, a Text Input will appear.
AliasName: The name of the variable that will be saved.
DisplayName: The prompt message.
DefaultPaths: Only applicable to Type Dir and File. A list of path hints to check for before prompting. If one is found no prompt appears and the command is skipped.

Example:

- Command: Prompt
  Parameters:
   Type: Dir
   AliasName: "{COUNTER_STRIKE_SOURCE_PATH}"
   DisplayName: "Where is your {GAME_NAME} folder?"
   DefaultPaths:
   - Program Files (x86)/Steam/steamapps/common/Counter-Strike Source/cstrike
   - Program Files/Steam/steamapps/common/Counter-Strike Source/cstrike
  ErrorMessage: "The {GAME_NAME} folder you specified is invalid"

3.1.2. CheckExists

Check that a file exists. This is used to ensure the root game directory was correctly chosen by the user during the Prompt command. It is recommended to check for a common game file that should always be present in game's root directory.

Parameters:

Path: The file to check for.

Example:

- Command: CheckExists
  Parameters:
   Path: "{COUNTER_STRIKE_SOURCE_PATH}/cstrike_pak_000.vpk"
  ErrorMessage: "The {GAME_NAME} folder you specified is invalid"

This example CheckExists command checks for cstrike_pak_000.vpk, an essential file that should always be present in Counter-Strike: Source's root game directory.

3.1.3. ChangeDir

Change to a directory. This command is typically the last Setup command before installation occurs.

Parameters:

Path: The directory to change to.

Example:

- Command: ChangeDir
  Parameters:
   Path: "{COUNTER_STRIKE_SOURCE_PATH}"
  ErrorMessage: "Access was denied to your {GAME_NAME} folder"

4. FileRules

The FileRules block contains file copying rules for a game's mods. Rules are organized into mod types (Maps, Skins, etc). If a game config has no rules for a specific mod type, Modboy will not try to install the mod. Often times file copying rules for one mod type can be duplicated to other mod types, though not in all cases.

4.1. Rule Types

4.1.1. DenyExtension

Skips a file based on its extension.

Example:

 - DenyExtension: "/^jpg$/i"

Skips all jpg image files in the downloaded mod archive.

4.1.2. DenyFile

Skips a file based on its filename and extension.

Example:

 - DenyFile: "/^thumbs\\.db/i"

Skips the notorious thumbs.db file often found in downloaded mod archives (an unneeded Windows cache file).

4.1.3. AcceptFilePath

Accepts a file based on its path and copies it to the destination specified in DestinationFile.

Example:

 - AcceptFilePath: "/scripts\/soundscapes_.+\\.txt$/i"
   DestinationFile: "{MATCHED_FILE_PATH}"

4.1.4. AcceptExtension

Accept a file based on its extension and copies it to the destination specified in DestinationFile.

Example:

 - AcceptExtension: "/^(rom|ut2|unr)$/i"
   DestinationFile: "Maps/{ARCHIVE_FILE_NAME}/{FILE}"

In this example, the regular expression matches either rom, ut2 or unr file extensions, and moves the matches file to Maps/{ARCHIVE_FILE_NAME}/{FILE}

4.2. Magic Variables

The DestinationFile parameter, which indicates where to move a matched file, has several magic variables available to it:

{MATCHED_FILE_PATH}: The full relative path of the matched file within its archive.
{ARCHIVE_FILE_NAME}: The name of the original archive (excluding its extension). For example, if the archive file was myarchive.zip, {ARCHIVE_FILE_NAME} will be myarchive.
{FILE}: The matched file.

5. Putting it all Together

Below is a simplified config example.

# This is a comment in YAML
Constants: # Set some constants used in the setup process.
 "{GREETING}": "Hello gamer!"
 "{GAME_NAME}": "Counter-Strike"
Setup:
- Command: Prompt # Show a prompt in the Modboy client.
  Parameters:
   Type: Dir
   AliasName: "{PATH_TO_GAME_FOLDER}" # This variable will get filled.
   # Below will print as "Hello gamer! Where is your Counter-Strike folder?"
   DisplayName: "{GREETING} Where is your {GAME_NAME} folder?"
   DefaultPaths:
   # The paths below are checked before the prompt appears. 
   # If one is found, the prompt is skipped and {PATH_TO_GAME_FOLDER} 
   # is set to the first present path.
   - Program Files (x86)/Steam/steamapps/common/Counter-Strike
   - Program Files/Steam/steamapps/common/Counter-Strike
  ErrorMessage: "The {GAME_NAME} folder you specified is invalid"
- Command: CheckExists # After the Prompt command, let's ensure the correct directory was chosen.
  Parameters:
   # Below we check that essential_game_file.exe exists. 
   # If it doesn't, the chosen game directory is incorrect.
   Path: "{PATH_TO_GAME_FOLDER}/essential_game_file.exe"
  ErrorMessage: "The {GAME_NAME} folder you specified is invalid"
- Command: ChangeDir
  Parameters:
   Path: "{PATH_TO_GAME_FOLDER}"
  ErrorMessage: "Access was denied to your {GAME_NAME} folder"
FileRules:
 Maps: # the rules below will only work with Maps
 # Skip over any JPG images found in the archive. 
 # They aren't needed by the mod.
 - DenyExtension: "/^jpg$/i"
 # It is a very good idea to skip .exe files found in the archive.
 # Mods don't usually need them and they could be malicious.
 - DenyExtension: "/^exe$/i"
 # Skip over text files commonly found in mod archives.
 - DenyFile: "/^read ?me.+/i"
 - DenyFile: "/^changelog/i"
 # Try to match files already in the correct structure.
 # Here we are matching BSP and sound files.
 - AcceptFilePath: "/maps\\/.+\\.bsp$/i"
   DestinationFile: "{MATCHED_FILE_PATH}"
 - AcceptFilePath: "/sound\\/.+\\.(wav|mp3)$/i"
   DestinationFile: "{MATCHED_FILE_PATH}"
 # For any files left over or maps with no directory structure,
 # let's guess where to put them.
 - AcceptExtension: "/^bsp$/i"
   DestinationFile: "maps/{FILE}"
 - AcceptExtension: "/^(wav|mp3)$/i"
   DestinationFile: "sound/{FILE}"