1. Config Layout
Each Modboy Game Config has 3 blocks:- Constants
- Setup
- FileRules
Example:
Constants: ... Setup: ... FileRules: ...
2. Constants
TheConstants
block is used by the Modboy client in dialog messages.Constants: "{...}": "..."
Example:
Constants: "{GAME_NAME}": "Counter-Strike: Global Offensive"
3. Setup
TheSetup
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 toType
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 thePrompt
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 lastSetup
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
TheFileRules
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 inDestinationFile
.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 inDestinationFile
.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
TheDestinationFile
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}"
Happy Modboy coding! If you have any questions ask below or PM tom!