Oracles-disasm is the repository name for the Oracle of Ages & Seasons disassembly, based on the US region ROMs. It is capable of re-assembling into Ages and Seasons ROMs.
To set up the assembler quickly, see Setting up oracles-disasm.
- Python 2
- A recent build of wla-dx
- Standard Unix building tools (Bash, Make)
- Windows users will probably need to use Cygwin.
Oracles-disasm can be built in 2 modes: precompressed (vanilla) or modifiable. By default, it builds in precompressed mode to produce an exact copy of the original US ROM. However, you cannot edit most compressed files (such as most graphics) in this mode.
To change this, run the swapbuild.sh script in the root of the repository. This script will detect the build mode based on a Makefile variable, and change it. It will also rearrange the build directiories (build/, build_v/, and build_e/) in order to avoid building from scratch after switching between build modes multiple times.
The Makefile may refuse to build if it notices that the current "build/" directory is configured for the other mode. To fix this, run fixbuild.sh. You may want to copy fixbuild.sh to .git/hooks/post-checkout to automatically fix this error after switching between branches, for example.
You can check your current build mode by checking for either the "use_precompressed" or "no_use_precompressed" file in the "build/" directory.
Oracles-disasm is hands down the easiest way to make asm hacks, if you know what you're doing.
Copying compressed graphics and text to ZOLE roms
Using oracles-disasm is the only (easy) way to edit compressed graphics. You can use this in conjunction with ZOLE for things like titlescreen editing.
Start by making sure that you've set it up in modifiable mode. Then, run
tools/misc/insertDataIntoRom.sh <filename>, where <filename> is the location of your ZOLE rom (not rom.gbc). This will copy all compressed graphics (
gfx_compressible/) and text (
text/text.txt) into the given rom. It won't touch uncompressed graphics (
insertDataIntoRom.sh script corrupts room layouts, but this doesn't matter for ZOLE roms because ZOLE patches the game to read room layouts from elsewhere (uncompressed).
Level editing with LynnaLab
Whenever a ROM is build from oracles-disasm, a corresponding ".sym" file is created along with it. This file contains addresses for all of the labels in the disassembly (but not most variables, yet). You can make a copy of this file to debug non-disassembly roms as well.
As long as the filename matches that of the ROM that is opened, the BGB and NO$GMB emulators can read this file to give you debugging symbols; for example, when modifying code in bgb, you can type something like
call showText, and that will be understood.
There are a few rules which oracles-disasm tries to abide by.
Functions dealing with objects are generally named as follows:
|Function name prefix||Behaviour|
|object||Expects an object to be passed through register 'd', and either the 'hActiveObjectType' variable or the 'e' register for the object's type.|
|item||Expects an "item" type object to be passed through register 'd' (an object in memory dx00-dx3f).|
|interaction||Expects an "interaction" type object to be passed through register 'd' (an object in memory dx40-dx7f).|
|enemy||Expects an "enemy" type object to be passed through register 'd' (an object in memory dx80-dxbf).|
|part||Expects a "part" type object to be passed through register 'd' (an object in memory dxc0-dxff).|
To "pass an object through register 'd'" means to set 'd' to the high byte of the object's address. For instance, if the object is an "enemy" stored at $d080-$d0bf, 'd' would be set to $d0. The function will infer the lower byte of the address by either assuming it's an enemy, reading from the 'hActiveObjectType' variable, or checking the 'e' register.