Ages-disasm

From ZeldaHacking Wiki
(Redirected from Disassembly)
Jump to: navigation, search
Ages-disasm
Author(s)Drenn
Links
Source

Ages-disasm is the repository name for the Oracle of Ages disassembly, based on the US region ROM. Unlike some disassemblies, it can be re-assembled into a new Oracle of Ages ROM.

To set up the assembler quickly, see Setting up ages-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.

Configuration

Ages-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.

Uses

Ages-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 ages-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/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 (gfx/).

The 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

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 ages-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 ages-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.