Modding

When running the game, you can specify a mod directory to load replacement resources from. In addition, that directory can contain a file called modconfig.txt, which allows you to change the properties of stages and some other things.

Resources

The port currently will load replacements for the following types of resources. MODDIR is used as a stand-in for your mod directory name.

Asset files

Path: MODDIR/files/
File name: same as original file, including subdirectories and extension (or lack thereof), e.g. bgdata/bg_mp5.seg, Ump_setupmp5Z

Files embedded into the ROM used for storing models, stage setups and data, language banks, speech MP3s and some other stuff.

The replacement file has to be in the same format as it is in the ROM, including compression.
If you rip a file from a ROM using PerfectGold's file manager, it is likely that you will have to recompress it, which can be done using rarezip, e.g.:
tools/rarezip MODDIR/files/LameE.lang > MODDIR/files/LameE
However, some files, such as the *.seg files in bgdata, are not compressed (or at least not entirely) and you don't need to recompress them.

Textures

Path: MODDIR/textures/
File name: xxxx.bin, where xxxx is the 4-digit hex number of the texture in the texture list, e.g. 061a.bin

Individual textures.

Currently you can only replace the contents of individual textures without changing their size.
The hex number mentioned above is called "Preset" in PerfectGold's Image Tools.
You can also export the texture from there: right click on it and select Export Raw Binary.

Animations

Path: MODDIR/animations/
File name: xxxx.bin and xxxx.txt, where xxxx is the 4-digit hex number of the animation table entry, e.g. 00d2.bin and 00d2.txt.

Animation data of individual animations and their animation table entries.

Replacements consist of 2 files for each animation:

Animation data: same format as the animation data files in the src/assets/ntsc-final/animations/ directory in the decomp.
Animation config: text descriptor file that replaces the animation's animation table entry. These have similar fields and function to the individual entries in src/assets/ntsc-final/animations.json file in the decomp.

This means that to replace e.g. animation 00d2, you have to have both MODDIR/animations/00d2.bin and MODDIR/animations/00d2.txt.
See below for a description of the animation config format.

Sequences

Path: MODDIR/sequences/
File name: xxxx.bin, where xxxx is the 4-digit hex number of the sequence, e.g. 0009.bin for the main Defection track

Individual music tracks (sequences).

You can find the sequence number in PerfectGold under Game Configuration -> Sound/Music.
You can also export the sequence from there in the correct format using the Export to PD format button.

Whole ROM segments

Path: MODDIR/segs/
File name: name of ROM segment as specified in romdata.c with no extension, e.g. fonthandelgothicsm

This allows you to replace fonts and sample/sfx banks, among other things.

The contents are the raw segment data, as if you just copied it out from the ROM using a hex editor.
You can use PerfectGold to export the sample/sfx banks in the correct format. Look for Export Ctl/Tbl under Game Configuration -> Sound/Music.
The Sfx Bank files have to be renamed to sfxctl and sfxtbl, the Instrument Bank files have to be renamed to seqctl and seqtbl.

Config files

Text files are currently used to specify stage properties in modconfig.txt and to specify animation metadata for replacement animations.
They generally consist of blocks containing key-value pairs like this:

block_name block_arguments {
  some_field 1
  some_other_field "string"
}

where block and key names are strings without spaces and values (arguments) are integers, floats or strings.
Integer values can be either in decimal (123) or in hexadecimal (0x01fd).
String values can be quoted in case you want to include spaces in them, e.g. somekey "what the fuck".
Key-value pairs can also appear outside of any blocks.
Single line comments are supported using the # character as the marker.

Animation configs

These are text files containing metadata for replacement animations.
They consist of the following fields:

Name and arguments	Argument types	Possible values	Description
`numframes N`	`N`: `uint16`	`N`: 0 .. 65535	Number of keyframes in animation. `numframes` in `animations.json`.
`bytesperframe N`	`N`: `uint16`	`N`: 0 .. 65535	Length of data for one keyframe in bytes. `bytesperframe` in `animations.json`.
`headerlen N`	`N`: `uint16`	`N`: 0 .. 65535	Length of animation data header. `unk08` in `animations.json`.
`framelen N`	`N`: `uint8`	`N`: 0 .. 255	Same as `bytesperframe`? `unk0a` in `animations.json`. Often (always?) `0x0c`.
`flags N`	`N`: `uint8`	`N`: 0 .. 255	Flags. Sum of all the `flag*` fields for this entry in `animations.json`.

Example file 00d2.txt for animation 00d2:

numframes 1249
bytesperframe 12
headerlen 37
framelen 12
# flag01 is false, flag02 is true, flag04 is false, flag08 is false, so flags = 0 + 2 + 0 + 0 = 2
flags 0x02

Mod configs

These are text files containing global settings for the mod, such as various stage properties.
Mod configs are placed in a file called modconfig.txt in the root of the mod directory and consist of the following blocks.

`stage NUMBER`

Contains configuration for a specific stage. NUMBER is the stage ID as described in stagetable.txt.
Any file value can be either the name of an asset file or its number in the file table. Note that asset file names in the file table currently cannot be redefined by the user, so this is more for convenience right now.
If any of the optional fields aren't specified, the game will use the defaults for the stage as defined in the ROM.
Can contain the following fields and blocks:

Name and arguments	Argument types	Possible values	Description
`bgfile F`	`F`: `file`	file ID or name	This stage's background file. Optional.
`tilesfile F`	`F`: `file`	file ID or name	This stage's tiles file. Optional.
`padsfile F`	`F`: `file`	file ID or name	This stage's pads file. Optional.
`setupfile F`	`F`: `file`	file ID or name	This stage's setup file. Optional.
`mpsetupfile F`	`F`: `file`	file ID or name	This stage's multiplayer setup file. Optional.
`alarm N`	`N`: `uint16`	any valid sound ID	ID of the alarm sound for this stage. Optional.
`allocation S`	`S`: `string`	allocation string	Optional. See this file.
`extragunmem N`	`N`: `uint16`	0 .. 65535	Extra bytes of gunmem. Corresponds to `Gun Adjust` in PerfectGold. Optional.
`music { }`	`block`	see below	Music settings for this stage. Optional.
`weather { }`	`block`	see below	Weather settings for this stage. Optional.

`weather`

Sub-block of the stage block. Contains the weather settings for that stage. Block itself and all fields within are optional.
Can contain the following fields and blocks:

Name and arguments	Argument types	Possible values	Description
`cutscene_only`	`flag`		If this key is present, weather will only show up in cutscenes.
`constant_wind A X Z`	`A`, `X`, `Z`: `float`	`A`: -2pi .. +2pi	Always force wind angle `A`, speed vector `(X, 0, Z)`.
`windspeed F`	`F`: `float`	`F`: -1024 .. 1024	Set wind speed to `F`.
`ymin F`	`F`: `float`	`F`: -65536 .. 65535	Low Y bound for the weather bounding box. No weather below this plane.
`ymax F`	`F`: `float`	`F`: -65536 .. 65535	High Y bound for the weather bounding box. No weather above this plane.
`zmax F`	`F`: `float`	`F`: -65536 .. 65535	High Z bound for the weather bounding box. No weather beyond this plane.
`include_rooms { }`	`block`	see below	List of rooms where weather is present. Mutually exclusive w/ key below.
`exclude_rooms { }`	`block`	see below	List of rooms where weather is not present. Mutually exclusive w/ above.

include_rooms and exclude_rooms are special blocks that contain a list of room numbers separated by whitespace.
If include_rooms is present, weather will only be present in rooms specified. If exclude_rooms is present, weather will be present everywhere except rooms specified.
If the list begins with the special keyword clear, it will be completely overwritten, otherwise rooms from the list will be added on top of the defaults. E.g.:

include_rooms {
  clear
  0x02 0x03 0x04
}

`music`

Sub-block of the stage block. Contains the music settings for that stage. Block itself and all fields within are optional.
Can contain the following fields and blocks:

Name and arguments	Argument types	Possible values	Description
`primarytrack N`	`N`: `uint16`	any valid sequence ID	Primary background music sequence.
`ambienttrack N`	`N`: `uint16`	any valid sequence ID	Ambient sounds sequence.
`xtrack N`	`N`: `uint16`	any valid sequence ID	Extra music sequence.

Example `modconfig.txt`

# Replace Chicago (0x1d) files with Carpark files, change music, alarm sound and weatherproof room set
stage 0x1d {
  bgfile "bgdata/bg_mp5.seg"
  tilesfile "bgdata/bg_mp5_tilesZ"
  padsfile "bgdata/bg_mp5_padsZ"
  setupfile "Ump_setupmp5Z"
  alarm 0x00a3
  music {
    primarytrack 0x3e
    xtrack 0x13
  }
  weather {
    exclude_rooms {
      clear
      0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09
    }
  }
}

Example mod

This is the custom stage G5 Car Park repackaged for use with the port.
This should give you a decent example of how to construct a mod folder.
Unzip into the game folder and run using pd.exe --moddir g5_carpark.
g5_carpark.zip

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Modding

Resources

Asset files

Textures

Animations

Sequences

Whole ROM segments

Config files

Animation configs

Mod configs

`stage NUMBER`

`weather`

`music`

Example `modconfig.txt`

Example mod

Clone this wiki locally

Modding

Resources

Asset files

Textures

Animations

Sequences

Whole ROM segments

Config files

Animation configs

Mod configs

stage NUMBER

weather

music

Example modconfig.txt

Example mod

Clone this wiki locally

`stage NUMBER`

`weather`

`music`

Example `modconfig.txt`