Home

z64project

When dumping a rom z64rom will create z64project in the same directory where you have your z64rom application.

# Project Settings
z_baserom       = "oot-debug.z64"
z_buildrom      = "build" # Name used for the rom that is built by z64rom.
z_vanilla       = ".vanilla" # Name of the vanilla item folders

# Wii VC
vc_basewad      = "NULL"
vc_dolphin      = "NULL" # Path to documents folder, not the app folder.

# Mips64 Flag
gcc_base_flags  = "-c -G 0 -O1 -std=gnu99 -march=vr4300 -mabi=32 -mips3 -mno-explicit-relocs -mno-memcpy -mno-check-zero-division -fno-common -Wall -Wno-builtin-declaration-mismatch -Isrc/lib_user -Iinclude/z64hdr -Iinclude/z64hdr/include"
gcc_actor_flags = ""
gcc_code_flags  = "-mno-gpopt -fomit-frame-pointer"
gcc_kaleido_flags = ""
gcc_state_flags = ""
ld_base_flags   = "-Linclude/z64hdr/oot_mq_debug/ -Linclude/z64hdr/common/ -Linclude/"
ld_code_flags   = "-T z64hdr.ld -T z_lib_user.ld -T z_object_user.ld --emit-relocs"
ld_scene_flags  = "-T z64hdr_actor.ld --emit-relocs"
ld_ulib_flags   = "-T ulib_linker.ld -T z_object_user.ld --emit-relocs"

Project Settings

From these variables, z_baserom and z_vanilla are the ones that you should not touch. Vanilla folders gets set while dumping to .vanilla, or into a custom name, if you provide the vanilla argument.

Wii VC

Wii VC variables are optional and z64rom isn't bundled with gzinject. If you're planning to utilize Wii VC build, copy gzinject application into your tools folder. vc_dolphin path is optiona. It's only there to delete folders Wii/title/00010001/ and Wii/title/00000001/ so that Dolphin wouldn't load the contents from those when playing the wad.

Mips64 Flag

• gcc_base_flags, applied to everything
• gcc_actor_flags, applied to actors and effects
• gcc_code_flags, applied to ib_code and lib_user
• gcc_kaleido_flags, applied to system/kaleido
• gcc_state_flags, applied to system/state
• ld_base_flags, applied to everything
• ld_code_flags, applied to everything except lib_user
• ld_scene_flags, applied to Fast64 scenes
• ld_ulib_flags, applied to lib_user only

Vanilla & Mod Directories

Vanilla directories, for example rom/actor/.vanilla/, is a method of doing non-destructive changes to your rom, so that you can always fall back to the vanilla assets whenever is needed. This also is a way to have Git friendly project repositories, where the vanilla assets do not have to be shared by teammates.

To remove a file from the rom you have to remove the vanilla file. But if these files need to be recovered, redump your baserome.

Mod directories, aka non-vanilla, are the directories that take place one level lower than vanilla directories. For example the vanilla of actors is rom/actor/.vanilla/* and mod of actors is rom/actor/*. z64rom prioritizes writing files from mod directory, if there exists a folder/file with a same name or index.

Paths that are categorized as Name Directories are case sensitive and require specific naming.

Index Directories

Path: rom/actor/
Type: Folder

Path: rom/effect/
Type: Folder

Path: rom/object/
Type: Folder

Path: rom/scene/
Type: Folder

Path: rom/sound/sequence/
Type: Folder

Path: rom/sound/soundfont/
Type: Folder

Path: rom/system/animation/
Type: File

Path: rom/system/kaleido/
Type: Folder

Path: rom/system/skybox/
Type: Folder

Path: rom/system/state/
Type: File

Name Directories

Path: rom/sound/sample/
Type: Folder

Path: rom/sound/sfx/
Type: Folder

Path: rom/system/static/
Type: File

Make.cfg

make.cfg is a config file that can be utilized to provide GCC compile flags and set dependencies for your source files. z64rom Make only compares the *.c files against the *.o output files but it can't know what other dependencies there should be that require recompiling. make.cfg itself will also work as a dependency for making. So if it's touched or saved, it will trigger a compiling process.

Here's an example from src/system/kaleido/0x01-Player/make.cfg

gcc_flags = "-Wno-maybe-uninitialized"
dependencies = [ "playas_adult.h", "playas_child.h", "Player.h" ]

These rules affect all the *.c files that are located in src/system/kaleido/0x01-Player/*, but this does not affect the subdirectories.

It's also possible to provide specific gcc_flags and dependencies for a specific file by specifying a section named after the files basename.

gcc_flags = "-Wno-maybe-uninitialized"
dependencies = [ "playas_adult.h", "playas_child.h", "Player.h" ]
[Player]
gcc_flags = "-O3"

In this case Player.c will have -O3 as an additional gcc flag

Build Info

For developement builds z64rom will provide an opportunity to display info about current build on the boot title. To use this you will need to have build_info.txt in your project root directory. It's recommended to have only 3 lines of information.

Example:

My Project - branch: main
[c57805b]
My Commit Message

Custom DMA Entries

You can have files of your choice injected into the rom gDmaDataTable indecies 0x20 - 0x100 ( 32 - 256 ). Create file dma.toml in your project root directory.

Example:

[0x20]
	file = "src/font/Candara.font_static"
	compress = true
[0x21]
	file = "src/font/Candara.width_table"
	compress = true

DMA Requests in z64rom

Due to the way that z64rom handles the DMA table and movement of data within the rom, rather than use the RomStart for DMA requests, these entries should be replaced with the correct indices.

// Vanilla
void Font_LoadMessageBoxIcon(Font* font, u16 icon) {
    DmaMgr_SendRequest1(
        font->iconBuf,
        (u32)&_message_staticSegmentRomStart[4 * MESSAGE_STATIC_TEX_SIZE + icon * FONT_CHAR_TEX_SIZE],
        FONT_CHAR_TEX_SIZE, 
        "../z_kanfont.c", 
        100
    );
}

// z64rom Replacement
#include <uLib.h>  // MUST BE INCLUDED
/*
   z64ram = 0x8006EEBC
   z64rom = 0xAE605C
*/
void Font_LoadMessageBoxIcon(Font* font, u16 icon) {
    DmaMgr_SendRequest1(
        font->iconBuf,
        gDmaDataTable[18].vromStart + 4 * 0x1000 + icon * FONT_CHAR_TEX_SIZE,
        FONT_CHAR_TEX_SIZE,
        "",
        0
    );
}