View source for Dreamcast Image Builder/Creating Mods

Dreamcast Image Builder comes with several built-in mods, and it also supports custom made mods.

You can create new mods by clicking the <code>+</code> button to the bottom right of the mod list. User created mods are placed in the <code>mods</code> folder in the same location as <code>DreamcastImageBuilder.exe</code>. Each mod is placed in a subfolder within the <code>mods</code> folder.

When you create a new mod, you can import a DCP file created by [https://github.com/DerekPascarella/UniversalDreamcastPatcher Universal Dreamcast Patcher] by clicking the <code>Import...</code> button. The contents of the DCP file will be added to the mod structure.

The sections below describe the information contained in mods. Some of this data is filled in automatically when you create mods using the <code>+</code> button in the UI.

== Creating <code>mod.ini</code> ==
The main information is stored in the <code>mod.ini</code> file. It has the following sections. Quotation marks are not used.

=== Main Mod Information ===
Here is an example <code>mod.ini</code>:<pre>
Name=Mod name (used in the UI and for mod sorting/selection)
Author=Mod developer
Version=Mod version
GameVersions=Comma-separated list of game IDs compatible with this mod
Discs=1,2
Description=Mod description (used in the UI; you can use \n for line breaks
DeleteFiles=delete.bin,folder\delete2.bin
</pre>Use the <code>Discs</code> field to specify a comma-separated list of compatible discs in mods for multi-disc games (no spaces before or after the commas). For example, if your mod is meant to work with Shenmue Disc 3 (but not discs 1 or 2), write <code>Discs=3</code>. If the <code>Discs</code> field is not specified, the mod will be compatible with any disc ID.

The <code>DeleteFiles</code> field is used to specify which files to exclude from the modified image. For example, if you want to delete the file in <code>GD Root\SONICADV\ADV00.PRS</code>, write <code>DeleteFies=SONICADV\ADV00.PRS</code>. You can delete multiple files and folders by using a comma-separated list (no spaces before or after the commas).

The <code>GameVersions</code> field is required for game compatibility check. Usually it's a single game ID. A mod compatible with multiple versions of the game can be set up like this:<pre>
Name=Debug Mode
Author=woofmute
Version=1.0
Description=Enables the Debug menu
GameVersions=MK-5119250V1.00320011004,HDR-0178 V1.00320011004
</pre>In the above example, <code>MK-5119250V1.00320011004</code> is the European version of Rez, and <code>HDR-0178  V1.00320011004</code> is the Japanese version.

=== Patch Data ===
The <code>mod.ini</code> file can also contain patches for specific files. Each file can have multiple patches. The patches are stored in the following format:
 <pre>[Filename]
; Patch Description (optional)
Address,Type,Count=Value
; Patch 2 Description (optional)
Address,Type,Count=Value</pre>
'''Filename''' is the name of the file to patch, such as <code>1ST_READ.BIN</code>.

* Note that the filename must be in square brackets (so that it becomes a section in the INI file). The section indicates the beginning of the patch list for the specified filename.
* If the file is not at the root of the GD drive, use relative paths to specify its location. For example, if the file <code>STG01.PRS</code> is located in the <code>SONICADV</code> folder, the filename will be <code>SONICADV\STG01.PRS</code>.
* If the filename has the PRS extension, it will be extracted, patches will be applied to decompressed data and the edited file will be repacked back to PRS.

'''Patch Description''' is for better readability. It will be output to the log when the patch is applied.

* Patch description must begin with <code>;</code>.
* Patch description must be inside the INI section (the line after the filename in square brackets) and before the patch line.
* If there are multiple patch descriptions, only the first will be displayed for the whole patch.

'''Address''' is the offset in the file where the patch will be written. It's a hexadecimal value in Big Endian format, such as <code>168E6C</code> for offset <code>0x168E6C</code>.

* If <code>Address</code> is preceded by <code>;</code>, the patch will not be applied.

'''Type''' specifies the kind of value to be written. The following patch types can be used. Patch type names are case insensitive.

<code>HexBytes</code> or <code>hb</code>: a sequence of bytes in hexadecimal format in the order that they will be written.

<code>HexBytesBigEndian</code>, <code>hexbytesbe</code>, <code>hbbe</code> or <code>be</code>: a sequence of bytes in hexadecimal format written in the reversed order.

<code>Sint8</code>, <code>si8</code> or <code>s8</code>: Signed 8-bit integer (decimal).

<code>Uint8</code>, <code>ui8</code> or <code>u8</code>: Unsigned 8-bit integer (decimal).

<code>Sint16</code>, <code>si16</code> or <code>s16</code>: Signed 16-bit integer (decimal).

<code>Uint16</code>, <code>ui16</code> or <code>u16</code>: Unsigned 16-bit integer (decimal).

<code>Sint32</code>, <code>si32</code> or <code>s32</code>: Signed 32-bit integer (decimal).

<code>Uint32</code>, <code>ui32</code> or <code>u32</code>: Unsigned 32-bit integer (decimal).

<code>Float32</code>, <code>float</code> or <code>f32</code>: A 32-bit floating point value.

<code>String</code> or <code>str</code>: An ASCII string.

<code>StringNullTerminated</code> or <code>stringnull</code> or <code>strnull</code>: A null-terminated ASCII string.

<code>File</code>: A sequence of bytes read from an external file.

<code>FileI</code>: A sequence of bytes read from an external file (insert bytes instead of overwriting).

<code>Pointer</code> or <code>p</code>: Scans the file for pointers to the address specified in <code>Address</code> and replaces them with pointers to the address specified in <code>Value</code>.

* The default <code>Type</code> is <code>HexBytes</code>. If you only need to write a sequence of bytes once, you don't need to specify the patch <code>Type</code> and <code>Count</code>. However, you do need to specify <code>Type</code> if you are writing data more than once.

'''Count''' is the number of times to repeat the writing operation. For example, specifying <code>Count</code> of <code>3</code> for a <code>HexBytes</code> value <code>FF</code> will make the program write <code>FF FF FF</code>, and specifying <code>Count</code> of <code>2</code> for a <code>String</code> value of <code>TEXT</code> will make the program write <code>TEXTTEXT</code> (<code>54 45 58 54 54 45 58 54</code>).

* For the <code>StringNullTerminated</code> patch, repeated writing will also write the null terminator. For example, writing a null-terminated <code>TEXT</code> string twice will result in the following bytes: <code>54 45 58 54 00 54 45 58 54 00</code>
* If <code>Count</code> is <code>0</code>, the patch will not be applied.
* For the <code>Pointer</code> patch, <code>Count</code> is not applicable and will be ignored if specified.
* The default value for <code>Count</code> is <code>1</code>. If you need to write data only once, you do not have to specify it.

'''Value''' is the value or the sequence of bytes to be written.

* For <code>HexBytes</code> and <code>HexBytesBigEndian</code> patches, <code>Value</code> can be any number of hexadecimal values represented in ASCII. For example, <code>A1 B2 C3 D4</code> will write bytes <code>0xA1</code>, <code>0xB2</code>, <code>0xC3</code> and <code>0xD4</code>. The same value for the Big Endian variation of the patch will write <code>0xD4</code>, <code>0xC3</code>, <code>0xB2</code> and <code>0xA1</code>.
* For integer patches, <code>Value</code> is an integer in the decimal format, such as <code>-100</code> or <code>255</code>.
* For the <code>Float</code> patch, <code>Value</code> is a floating point number such as <code>3.45</code>.
* For the <code>String</code> and <code>StringNullTerminated</code> patches, <code>Value</code> is an ASCII string, such as <code>SEGA</code> (without quotes).
* For the <code>File</code> patch, <code>Value</code> is the location of the data file, such as <code>hack\data.bin</code>. The file will be loaded from the mod folder. Relative paths can be used.
* For the <code>Pointer</code> patch, <code>Value</code> is the replacement pointer value in the Big Endian format, such as <code>8C5C1CD2</code> (for <code>0x8C5C1CD2</code>).

==== Examples ====
<pre>[SONICADV\SHOOTING.PRS]
; Write an unsigned 1-byte integer value of 128 (0x80) once at address 0x5556C.
5556C,u8,1=100</pre>
Result: <code>SONICADV\SHOOTING.PRS: 0x5556C -> 80</code>.
 <pre>[1ST_READ.BIN]
; Write a signed 1-byte integer value of -1 (0xFF) twice at address 0x5556D.
5556D,s8,2=-1</pre>
Result: <code>1ST_READ.BIN: 0x5556D -> FF FF</code>.
 <pre>[1ST_READ.BIN]
; Write a float value of 1556.0 (0x44C28000) once at address 0xC53F0.
C53F0,float,1=1556.0</pre>
Result: <code>1ST_READ.BIN: 0xC53F0 -> 00 80 2C 44</code>
 <pre>[1ST_READ.BIN]
; Write the data from `mod folder\sheep\model.bin` once to offset 0x166284
166284,file,1=sheep\model.bin</pre>
Result: <code>1ST_READ.BIN: 0x166284 -> (contents of model.bin)</code>
 <pre>[1ST_READ.BIN]
; Write the null-terminated "SEGA" ASCII string twice at 0x1000.
1000,stringnull,2=SEGA</pre>
Result: <code>1ST_READ.BIN: 0x1000 -> 53 45 47 41 00 53 45 47 41 00</code>

==== Additional Examples and Tips ====
* <code>HexBytes</code> is the default patch format, and you can omit <code>Type</code> and <code>Count</code> if you only need to write a sequence of bytes once. Example:

 <pre>[SONICADV\MOVIE.BIN]
; Write 09 00 to 0x2A4 and 0x28D
02A4=09 00
028D=09 00</pre>Result: <code>SONICADV\MOVIE.BIN: 02A4 -> 09 00; 028D -> 09 00</code>
* The default value for <code>Count</code> is 1. If you don't need to write data more than once, you can omit <code>Count</code>:

 <pre>[1ST_READ.BIN]
; Write the "SEGA" ASCII string at 0x1000.
1000,string=SEGA</pre>Result: <code>1ST_READ.BIN: 0x1000 -> 53 45 47 41</code><pre>[1ST_READ.BIN]
; Write the value 0x8C0112B4 to offset 0x168E6C
168E6C,be=8C 01 12 B4</pre>
Result: <code>1ST_READ.BIN: 168E6C -> B4 12 01 8C</code>

* You can combine multiple patch types in a single line. The data will be written once in a sequential order. The <code>Pointer</code> patch type is not supported in this mode.

 <pre>[1ST_READ.BIN]
; Chao Race start position for Sonic (replaces MR Garden)
15F4CC,Uint16/Uint16/float/float/float/Uint16=40/0/-170/60/-25/32517</pre>
Result:
 <pre>1ST_READ.BIN:
15F4CC -> 28 00
15F4CE -> 00 00
15F4D0 -> 00 00 2A C3
15F4D4 -> 00 00 70 42
15F4D8 -> 00 00 C8 C1
15F4DC -> 05 7F</pre>

== File Replacement ==
Mods can replace files in two ways:

* Files in the <code>include</code> folder (+ files in its subfolders) are copied to GD root without preserving folder hierarchy.
* Files and folders in the <code>gdroot</code> folder are copied with folder hierarchy.

Examples:

If your mod has a file <code>include\textures\text1.pvr</code>, it will be copied to <code>GD Root\text1.pvr</code>.

If your mod has a file <code>gdroot\textures\text2.pvr</code>, it will be copied to <code>GD Root\textures\text2.pvr</code>.

In addition, the following changes are supported:

* You can replace <code>IP.BIN</code> by putting your own version of it in the mod's folder, although it is not recommended. Note that even if you add your own <code>IP.BIN</code>, the program may apply additional changes to it such as binhack, region patch etc.
* Files with the <code>.xdelta</code> extension will be applied as xdelta patches (see below).

Example: If your mod has a file <code>gdroot\1ST_READ.BIN.xdelta</code>, it will be applied as a diff file to <code>GD Root\1ST_READ.BIN</code>.

'''NOTE! The program makes a list of xdelta patches in all mods and applies them to original files first, before mods are applied. You cannot apply more than one xdelta patch to a single file.'''

== Additional Fields in <code>mod.ini</code> ==

=== RequiredCodes ===
The <code>RequiredCodes</code> field specifies a comma-separated list of cheat codes that are required for the mod to function. These codes will be auto-enabled during build process if this mod is enabled.

Example:<pre>
Name=Widescreen test
RequiredCodes=Widescreen culling fix
</pre>

=== ReplacePointers ===
The <code>ReplacePointers</code> field in the main section lists files where pointer replacements will be made. Example:
 <pre>Name=Pattern Test
Description=Test pattern replacement
ReplacePointers=AL_GARDEN01.PRS</pre>
For each file listed in <code>ReplacePointers</code>, a pointer replacement list will be loaded from an INI file based on the original filename with the .INI extension (<code>AL_GARDEN01.PRS.INI</code> for the example above). If it is missing, the file <code>pattern.ini</code> will be loaded instead. This can be useful for patching the same pointers across multiple files.

* If the file's extension is PRS, the program will decompress it, apply pointer replacements to decompressed data and recompress it back to PRS.

Pointer replacement lists are text files in the following format. Each line specifies a pointer replacement.

<code>Pointer name,Original address,Replacement address</code>

'''Pointer name''' is meant to provide the patch's description for better readability.

* If the pointer name starts with <code>;</code>, the patch will not be applied.

'''Original address''' is the pointer value that will be replaced.

'''Replacement address''' is the value that will be written as a replacement.

Example:
 <pre>njpushmatrix,8C5A65B8,8C5BED18
njtranslatev,8C5A7140,8C5BF8A0
;DrawObject,8C030592,8C5FDEB2</pre>The <code>njpushmatrix</code> replacement will search for pointers to <code>0x8C5A65B8</code> and replace them with pointers to <code>0x8C5BED18</code>.

The <code>njtranslatev</code> replacement will search for pointers to <code>0x8C5A7140</code> and replace them with pointers to <code>0x8C5BF8A0</code>.
The <code>DrawObject</code> pointer replacement will not be applied.

== Adding Submods ==
Each mod can have one or more "submods". A submod has the same capabilities as a regular mod, but it doesn't appear on the main list of mods. Submods are only applied when the parent mod is enabled, and the submod is also enabled in the parent mod's configuration.

To add submods, use the <code>Submods</code> field in the main section of the <code>mod.ini</code> file.

<code>Submods</code> is a comma-separated list of relative paths to submods' INI files. Submods must be placed in separate subfolders within the parent mod's folder. '''Submod INI files can have any name except <code>mod.ini</code>.'''

<code>DefaultSubmods</code> is a comma-separated list of submod names (matching the <code>Name</code> field in the submod's INI file) that are active by default. If this key is missing in the INI file, all submods will be enabled by default.

'''mod.ini'''
 <pre>Name=Test Parent Mod
Description=This mod demonstrates usage of submods.
GameVersions=610-7029  V1.00019981016
Submods=submod1\submod1.ini,submod2\submod2.ini
DefaultSubmods=Submod 1, Submod 2</pre>
In the case of the example above, the file structure of the mod should be as follows.

The <code>submod1</code> folder contains <code>submod1.ini</code> and the <code>submod2</code> folder contains <code>submod2.ini</code>.
[[File:Dreamcast Image Builder Creating Mods 1760357338406.png|none|thumb|Mod structure]]
'''submod1\submod1.ini'''<pre>
Name=Submod 1
Description=This is the first submod.
GameVersions=610-7029 V1.00019981016
</pre>'''submod2\submod2.ini'''<pre>
Name=Submod 2
Description=This is the second submod.
GameVersions=610-7029 V1.00019981016
</pre>The player can enable or disable submods using the <code>...</code> button that appears to the right of the mod list when a mod with submods is highlighted.
{| class="wikitable"
![[File:Dreamcast Image Builder Creating Mods 1760357374806.png|none|thumb|Configure button]]
![[File:Dreamcast Image Builder Creating Mods 1760357396338.png|none|thumb|Submod configuration]]
|}