prevnext   » SZS: Wiimms SZS Toolset » Guides » Add sections to main.dol

Add sections to main.dol


1.   Introduction

Since years, wstrt supports the adding of CTGP sections if using option --add-ctcode. But the current CTCODE doesn't include the Lap & Speed Modifier to manipulate the number of laps and the basic speed. But there are cheat codes available. And so Leseratte and I devolped an extension to add cheat codes.

The first plan was that the user adds a simple GCT file (encoded cheat code). But while developing it seemed to be better if the user can also add a code handler of his choice. With release of v1.43, GCT and GCH files are supported.

The advantage of an integrated cheat code section is that all users use the same cheat codes and don't need to enable their own Gecko code handlers.

2.   GCT file

Option --add-section also accepts GCT files (Gecko cheat code files). There are many tools including USB loaders, that can create GCT files. If you want to add more than 1 GCT file, use the option multiple times, once for each file.

Overall, 935 code lines are possible. But if moving the Gecko code handler and the codes to another memory location, more than 100000 code lines are possible. See section »Moving Gecko Codes« for details.

2.1   How it works

As first step, the code lines of all GCT files are concatenated. At the final step, a section containing an internal copy of codehandleronly and the concatenated cheat codes is created. This section is inserted as TEXT section into the DOL file at address 0x80001800. If you want another code handler, use a GCH file instead (see next section).

If the section is too large or will conflict to any other DOL section, a warning is printed and the new section is dropped. If option --force is set, the section is not dropped, but you may get an invalid DOL file.

If option --verbose (short -v) is set, wstrt tells about the modifications. If set twice, a memory map of the new GCT section is printed too.

2.2   Example

# wstrt patch main.dol --add-sect a.gct --add-sect b.gct --add-sect c.gct -vv

PATCH main.dol
- Create section T2 [80001800..80002a50], file offset 0x2a36a0, size 0x1250
- Patch addr 801bab20 (off 001b5dc0) from 4e800020 to 4be46d88

   Memory map of code handler & 3 GCT files:
	   unused :  off(beg) ..  off(end) :      size : part
		  :  80001800 ..  800022a8 :       aa8 : Code Handler
		  :  800022a8 ..  800022b0 :         8 : GCT magic
		  :  800022b0 ..  80002398 :        e8 :   29 lines of 1. GCT file
		  :  80002398 ..  80002970 :       5d8 :  187 lines of 2. GCT file
		  :  80002970 ..  80002a48 :        d8 :   27 lines of 3. GCT file
		  :  80002a48 ..  80002a50 :         8 : GCT terminator
	     15a0 :  80003ff0 ..  80003ff0 :         0 : -- max possible --

* Save patched file to: DOL:main.dol

3.   GCH file

A GCH (Gecko Code Handler) consists of 3 parts:

3.1   File Header

The file header is a simple block with 4 members of each 4 bytes. The coding of the 3 numeric values is big endian:

name offset type description
magic 0x00 4 bytes The string "G\4CH" (Hex: 47 04 43 48)
start 0x04 u32 The start address of the section, usually 0x80001800.
size 0x08 u32 The size of the code handler. The total size of the section can be larger.
vbi entry 0x0c u32 NULL or the section address for the VBI interrupt.

3.2   Cheat Code Handler

The Gecko Code Handler. Since years, all loaders use 1 of 3 variants of the same public code handler: If not using the USB-Gecko, codehandleronly.bin is the best choice.

In the download part you can find the file code-handler-section.bin. It is prefixed by a header and can be used as as base for own GCH files (see below).

3.3   GCT (Cheat Code)

Any valid GCT file can be used. For example, USB-Loaders create GCT files.

3.4   How to create a GCH file

Creating a own GCH file is easy if using the prepared code file:
  1. In the sections download part you find the file code-handler-section.bin. Load it!
  2. Create a GCT file with your cheat code.
  3. Concatenate code-handler-section.bin and your GCT file for example with:
    Linux:   cat code-handler-section.bin my.gct >my.gch
    Windows: copy/b code-handler-section.bin + my.gct my.gch
  4. Use the wstrt PATCH command with option --add-section:
    wstrt PATCH main.dol --add-section my.gch

4.   WCH file

WCH is another file format accepted by option --add-section. The file format will be explained later.

In the sections download part you find some ready to use files:

4.1   Item-Cheats

For testing tracks, it is good to use item cheats. I have developed an universal item cheat that allows to use any item with Wiimote+Nunchuck and with GameCube-Controller:

Item-Cheats for Wiimote+Nunchuk Item-Cheats for GameCube-Controller

5.   Moving Gecko Codes

Normally, the gecko codehandler and the gecko codes are placed in the memory range of 0x80001800–0x80002fff. The space of 6 KB can be to small to hold all needed code lines.

Option --gct-move adds a new text section to main.dol. This new section overlays the BSS section and is run at the very beginning. It changes the memory managment of the game and makes the heap smaller. Then it moves the gecko code lines to the new space. With this method more than 100000 gecko code lines are possible.

Options --gct-addr and --gct-space are tuning options, but the later one is only needed for testing.

6.   Related options

6.1   --add-lecode

Add newest LE-CODE starter from 2023-12 to main.dol.

Command reference

wstrt patch.

6.2   --add-ctcode

If source is an original main.dol file of MKWii, then append 2 sections (usually T2 and D8) with CT-CODE. The CTCODE is inserted after sections defined by --add-section and then only, if there are no address collisions. If --ct-dir is used, then files named rmc[ejp]/boot_code.bin and boot_code.bin for T2, and rmc[ejp]/boot_data.bin and boot_data.bin for D8 are searched.

Command reference

wstrt patch.

6.3   --add-section file

Each option call adds the filename to an internal list. Each file must be of type GCT, GCT-TXT, GCH or WCH. All GCT files together are combined with an internal code handler to one section (like a GCH file). GCH and WCH define sections and patches. The defined sections are added and VBI hooks are optionally initialized. Use option --force to allow overlapped sections. Use option --verbose up to 2 times for a log. If parameter FILE contains at least one wildcard (e.g. "*.GCT"), then FILE is used as search pattern and all found files are added. Quote FILE for this purpose. If a single file is not found and the filename (not path) contains at least 1 '@' character, then all '@' characters of it are replaced by the region code (one of P,E,J,K) for a second try. The intention of this option is to add a Gecko Code Handler and cheat codes to a main.dol for automatic execution.

Command reference

wstrt patch.

6.4   --gct-move [=mode]

If a section is of type gecko code handler + cheat code, then make the heap smaller and move the cheat codes before the FST section. Parameter MODE is optional. If set, OFF disables and ON enables this feature. For mode AUTO (default) this feature is enabled, if the cheat codes are too large (end>0x80003000) or for internal conflicts.

Command reference

wstrt patch.

6.5   --gct-addr address

If --gct-move is active, a text section is created to manage the code handler. This section is only needed at start and is placed by default at address 0x802c0000 (part of BSS, good address for all 4 regions). This option changes the start address of the section. If address is 0 or invalid, then unused BSS space is searched.

Command reference

wstrt patch.

6.6   --gct-space size

Define the minimal space for the code part of --gct-move. This value is ignored, if it is smaller than the size of the cheat codes. This debug option was only implemented to test the memory allocation by --gct-move with large blocks.

Command reference

wstrt patch.