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:
- A file header of 16 bytes.
- The Gecko Code Handler itself (e.g. codehandleronly.bin with 2728 bytes).
- The GCT file
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:
- codehandler.bin
- codehandleronly.bin
- codehandlerslota.bin
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:
-
In the sections download part
you find the file
code-handler-section.bin.
Load it!
-
Create a GCT file with your cheat code.
-
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
-
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:
-
lap+speed-*.wch is the Lap & Speed Modifier for 3 regions.
-
ls+icheat-*.wch is the Lap & Speed Modifier and an universal
item cheat (see next section) for 2 regions.
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:
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.
