GameCube Tooling

← Gotcha Force

Tools

Dolphin Emulator

Dolphin allows for the extraction of GameCube ISO files. It can be used in debug mode for stepping through PowerPC instructions, setting breakpoints, memory inspection/dumping, and more.

Dolphin Memory Engine

Dolphin Memory Engine utilizes Dolphin dumps (in debug mode: add -d when running Dolphin) to assign names to fixed memory addresses during execution. This enables sharing reverse engineering work on the game's memory.

Documentation on symbol generation: Symbols

Python Support for Dolphin Emulator

Python support for AI/CPU scripting. The API allows reading and writing to memory, among other capabilities.

gcmtool.py (Virtual World RE)

gcmtool.py allows manipulation of GameCube files (GCM ISO format). It can extract all game files, as well as files related to GCM format operations. Its primary feature is patching the FST and the boot.bin file with a new boot.DOL file, a new apploader.img, and added, deleted, or modified game files. It aligns all file offsets according to a specified value, with a default alignment of 4. DVD files are also optimally positioned to minimize the GCM ISO size.

Open-source & MIT license.

afstool.py (Virtual World RE)

Python3 script for unpacking/packing/rebuilding the AFS file format. Reconstruction of the Table of Contents (TOC) and Filename Directory (FD) is possible with control over all possible format parameters.

User Manual

Unpack source_afs.afs into the new default folder source_afs. If optional_dest_folder is specified, unpack into optional_dest_folder. If the AFS has an FD, it will use the OS modification date (mtime) to store the file's date.

afstool.py --unpack source_afs.afs optional_dest_folder

Pack source_folder into the new default folder source_folder.afs. If optional_dest_file.afs is specified, pack into optional_dest_file.afs. If the AFS has an FD, it will use the OS modification date (mtime) to update the file's date in the AFS. The maximum size of each file is determined by the next offset in the AFS (file or system file). Without an FD, there are no restrictions on the size of the last file in the AFS. The names in the FD remain unchanged by this command.

afstool.py --pack source_folder optional_dest_file.afs

Rebuilds the file system of an unpacked AFS folder using the afs_rebuild.conf and afs_rebuild.csv files. See below for more information on afs_rebuild.conf.

afstool.py --rebuild source_folder

Displays statistics of the AFS or the unpacked folder of the AFS. Provides information about the header, TOC, FD, the entire memory mapping sorted by offsets (files and system files), information about the address space, and grouped duplicate file names.

afstool.py --stats path

Extracted Files Structure

The root folder contains all files from the AFS.

The sys folder contains all system files of the AFS and files generated by the program for various AFS manipulations:

   tableofcontent.bin - TOC system file: This file can be directly edited and is managed by the --pack command.
   filenamedirectory.bin - FD system file: This file is created only if there is an FD in the AFS.
   filename_resolver.csv - Created when multiple files have the same name in the FD.
   afs_rebuild.conf - Modify this file to rebuild the AFS.
   afs_rebuild.csv - Modify this file while taking into account the configurations from afs_rebuild.conf to reconstruct the AFS.

filename_resolver.csv

The --pack command does not change the names in the FD. This file is used in the packing process to automatically detect renamed files in the root folder and keep their initial index in the TOC (and FD). This file is generated automatically when:

• The FD is present and contains duplicates in the names; extracted files are then renamed "filename (N).ext" with N: Integer,
• The FD is absent, and files are named by their index, for example: "00000000" for the very first file.

Each line in the CSV contains an "index/unpacked_filename" pair. This CSV can be used to rename files, for example: "0/my_new_filename.ext".

afs_rebuild.conf

Each offset or index is written in hexadecimal with the prefix 0x: 0xabcdef. The value auto will be used where possible.

[Default] section

AFS_MAGIC : 0x41465300 or 0x41465320

files_rebuild_strategy : auto, index, offset, or mixed

files_rebuild_strategy is used to organize files (indexes, offsets, packed filenames if the FD is present) in the AFS. The rebuild strategy uses the automatically generated afs_rebuild.csv file during unpacking. If the root folder's file is absent from afs_rebuild.csv, all values will be generated automatically. Four strategies are available:

   auto : Automatically rebuild all indexes and offsets of specified files (uses packed_filename to specify the filename in the FD if present). Indexes and offsets in the afs_rebuild.csv file will be ignored.
   index : Keeps the indexes of specified files (uses packed_filename if the FD is present). Offsets will be ignored.
   offset : Keeps the offsets of specified files (uses packed_filename if the FD is present). Indexes will be ignored.
   mixed : Keeps both indexes and offsets of specified files (uses packed_filename if the FD is present).

filename_directory : True if the FD is present, False otherwise. If the value is True, the [FilenameDirectory] section must be present.

[FilenameDirectory] section

toc_offset_of_fd_offset : The offset in the TOC of the FD offset is at the end of the TOC. In some AFS, there is padding at the end of the offset/length series. The value auto will be used where possible.

fd_offset : The FD is at the end of the AFS. The value auto will be used where possible.

fd_last_attribute_type : The type of the last 4 bytes of each FD entry. Four values are possible:

   length : Use the file size.
   offset-length : Use the "offset/length/offset/length..." series.
   0xabcdef : Use a hexadecimal constant.
   unknown : The value is unknown. The Null value will be used.

afs_rebuild.csv

afs_rebuild.csv contains entries describing how to pack files from the root folder into the AFS. Each offset or index value is stored in hexadecimal with the prefix 0x: 0xabcdef. The value auto will be used for indexes and offsets where possible. Offsets must be aligned to the value 0x800 (2048). One line per selected file is added with constraints for packing using the format: "unpacked_filename/index/offset/packed_filename", for example: "dummy (5).bin/0x12/0x80000/dummy.bin". You can use the value auto, for example: "dummy (5).bin/auto/auto/dummy.bin". For each empty block, only an offset/length pair with values aligned to 0x800 will be added, for example: "0x80000/0x5000".

When configuring the rebuild, all lines containing files with no constraints from the afs_rebuild.csv file will be removed. Then, the auto value will be added to offsets and indexes with no constraints. During the rebuild, the filename_resolver.csv file is automatically deleted. Changes to file names will be preserved by adding entries with unpacked_filename and index (and packed_filename if the FD is present) in this file.

Open-source & MIT license.

doltool.py

Python 3 script for manipulating the DOL file format. It also provides detailed statistics on the DOL and its composition, and can patch a DOL using an Action Replay Codes file.

Open-source & MIT license.

AFSPacker

AFSPacker is user-friendly and functional. This software allows for extraction and patching of files in the AFS format.

• AFSPacker considers the last 4 bytes of FD entries as unknown. These bytes are sometimes used to describe the size of packed files.
• It is not possible to specify the offset of the FD in the TOC. This offset can be placed directly after the TOC or after padding following the TOC. This can be important if the main executable handles files with a hardcoded file offset relative to the start of the AFS.
• Dates are not retained during extraction, resulting in data loss with each repack.

Open-source & MIT license.

AFS Explorer

AFS Explorer should be avoided in projects where afstool.py can be used. The terms of use are restrictive, and command-line functionality is absent. The source code does not appear to be accessible, which is another limiting factor.

GameCube Iso Tools

A tool for manipulating GameCube ISOs. It allows extraction of the ISO into a GCReEx or DiscEx format folder. It can also repack into an ISO format.
Note: The repacked ISO is automatically "compressed" on Windows. The destination folder must be created in advance.

Commands:

gcit.exe iso.iso -f gcreex -d extract -q
gcit.exe extract\Game_folder -f fulliso -d repack.iso -q

Dolphin Emulator may return an error for repack.iso: "repack.iso is not a valid GCM/ISO file, or is not a GC/Wii ISO." In GCReEx format, it is noticed that the padding at the end of the apploader is different from that generated by Dolphin Emulator. Additionally, many files extracted with gcit.exe have padding added to the end compared to the actual size indicated in the DVD's fst.bin.

Wiimms ISO Tool

wit allows manipulation of GameCube ISOs. On Windows, wit can be used without installation by using the bin/wit.exe file.

Extraction of files from an ISO (in fst format): wit extract mkw.iso --dest=mkw/

Please note that repacking into the ISO via the copy command does not seem to produce the same ISO (over 4 GB file). It needs to be investigated if there are options to reproduce the correct ISO.

https://github.com/Wiimm/wiimms-iso-tools

Open-source & GPL v2+ license.

GC Rebuilder 1.1

Please note that this project is no longer developed, and the size of the main executable is incorrect.

Source code: https://github.com/bsv798/gcrebuilder

The command-line interface is present, but no specific documentation is provided.

GeckoLoader

Gecko Loader allows patching a DOL using a list of Action Replay Codes or GeckoCodes. The software also allows hooking functions (VI, etc.).

For example, there may be a .bss patch with PowerPC bytecode and values to patch. The EntryPoint is changed to reach this new code, and after loading into memory, the code modifies the values in memory.

This is considered a bad practice because .bss contains uninitialized variables (int a;). Normally, they should be Null / 0. Additionally, for write-only codes, it is preferable to patch the .text or .data sections of the DOL directly when possible.

Open-source & GPL v3 license.