From ZeldaHacking Wiki
Jump to: navigation, search

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.

Build requirements

  • Git
  • 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 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 You may want to copy 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/ <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 (gfx/).

The 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

Similar to ZOLE, LynnaLab can edit levels through the disassembly's files, although you're mostly on your own if you go down this path.

Symbol files

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.

Naming conventions

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.