Oracles-disasm

Oracles-disasm
Author(s)	Stewmat
Links Source

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. It uses wla-dx as its assembler.

Available on github.

For setup instructions, see Setting up oracles-disasm.

Uses

Level editing with LynnaLab

LynnaLab can edit levels through the disassembly's files.

Assembly hacking

The disassembly code is well-documented for the most part, making it well suited for doing complicated assembly hacks. In addition, data structures which LynnaLab doesn't understand can be modified by hand.

Symbol files

BGB debugger showing Seasons with debugging symbols

Whenever a ROM is built from oracles-disasm, a corresponding ".sym" file is created along with it. This file contains addresses for all of the labels in the disassembly, and most variables.

This is extremely useful for debugging. As you can see in the image to the right, function names are visible in bgb's debugger when it detects a .sym file for the loaded ROM.

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. You can make a copy of this file to debug non-disassembly roms as well.

The hack-base branch

There are two main branches, the "master" branch and the "hack-base" branch. "master" is designed to build vanilla Ages and Seasons ROM files, while "hack-base" has certain changes designed to make hacking easier. LynnaLab can edit both, but is mainly designed for hack-base.

In the "master" branch, precompressed assets (text, graphics, large rooms) are used. This makes it impossible to modify these assets. While this setting can be changed on the master branch, using hack-base is recommended for this and other reasons.

Hack-base branch changes (both games)

• Precompressed assets are NOT used, meaning everything is modifiable.
• Tileset changes
  • Tilesets are expanded and stored uncompressed. Each tileset has its own fully unique graphics file (they do not share any graphics unlike in the "master" branch). As a result the ROM is expanded to 2 megabytes.
  • Tileset "layout groups" are fully ignored. Normally this tells the game which room file to load for the room (ie. room0XYY.bin, where X is the layout group and Y is the room number). However it's extremely confusing to have this tied to the tileset, and mostly unnecessary, which is why this was disabled.
• Ages items are available in Seasons, and vice-versa.
• Large rooms are stored uncompressed, because the original compression algorithm is weird.
• The "ENABLE_BUGFIXES" compilation flag is set, which fixes a few bugs in the original game's code.

Changes (ages)

• Disabled the function "setPastCliffPalettesToRed", which only exists because certain tileset data between past and present tilesets is reused; this function modifies cliff colors. But since tilesets were expanded as explained earlier, this function is no longer necessary.
• The "Maku Path" dungeon existed twice. This is still the case, but now the two dungeons reference distinct data, allowing them to be modified independently of each other.

Changes (seasons)

• The AGES_ENGINE define is enabled, which enables certain Ages engine features in Seasons:
  • Ages-style dungeon staircase warps now work in Seasons. This means that you can use staircases in dungeons without explicitly defining any warp data.
  • You can use add "Item Drop" objects which normally don't work in Seasons. (You'll notice that the game normally uses an "enemy" object for item drops. This is also fine; the result is the same.)

Known issues with hack-base

• Seasons
  • Samasa desert animations are broken during screen transitions. Caused by tileset gfx being fully reloaded instead of only partially.
  • Tileset graphics in subrosia market/beach area show corruption when transitioning between screens
• Both games
  • Some breakage related to the removal of "unique gfx headers":
    • Seasons: Gnarled root dungeon entrance always appears opened even when it's closed.
    • Palettes don't load properly in a small handful of places, including the Seasons maku tree branches (while ascending) and green bushes for the d8 miniboss. The latter is easily fixed using the "load gfx after screen transition" checkbox.

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.

See objects for more information.