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.
Their general format is:

# this is a comment; the whole line will be skipped

block_with_no_args {
  some_string_key abcd "abcd"
  some_int_key 123
  some_complex_key 0x0f 2 3 abc
}

block_with_args 123 {
  some_key_with_no_value
}

some_key_outside_of_a_block "argument"

where block and key names are alphanumeric 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".

Animation configs

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

Name	Type	Range	Description
numframes	uint16	0-65535	Number of keyframes in animation. numframes in animations.json.
bytesperframe	uint16	0-65535	Length of data for one keyframe in bytes. bytesperframe in animations.json.
headerlen	uint16	0-65535	Length of animation data header. unk08 in animations.json.
framelen	uint8	0-255	Same as bytesperframe? unk0a in animations.json. Often (always?) 0x0c.
flags	uint8	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