Oracle of Ages
A complete, documented disassembly of The Legend of Zelda: Oracle of Ages and Seasons for Game Boy Color.
What is Oracle of Ages?
oracles-disasm is a complete, documented disassembly of the Game Boy Color games The Legend of Zelda: Oracle of Ages and Oracle of Seasons. It provides the full source code and assets, allowing developers and hackers to rebuild the ROMs, study the game's mechanics, and create custom modifications. The project solves the problem of opaque, compiled game code by offering an open, editable foundation for the community.
ROM hackers, retro game modders, and reverse-engineering enthusiasts interested in the Zelda Oracle games or Game Boy Color development. It's also valuable for those building tools like randomizers or level editors that interact with the game's code.
Developers choose this because it's the most complete and documented disassembly available for these specific games, enabling precise modifications and integrations like the official randomizer. Its build system and asset editing tools are tailored for practical hacking workflows.
Overview
Disassembly of Oracle of Ages and Seasons
Use Cases
Best For
- Creating custom ROM hacks for Oracle of Ages or Seasons
- Studying the assembly code and mechanics of Game Boy Color Zelda games
- Building tools that interact with the game's code, like randomizers
- Editing in-game graphics and text for mods
- Learning about reverse-engineering techniques for retro consoles
- Developing level editing suites when combined with LynnaLab
Not Ideal For
- Projects targeting Japanese or European versions of Oracle of Ages/Seasons
- Hacks requiring 100% byte-perfect ROM reconstruction for verification or archival
- Commercial game development or any for-profit modifications
- Users seeking a graphical, no-command-line editing tool without technical setup
Pros & Cons
Pros
Provides fully reverse-engineered and documented source code for both Oracle games, enabling in-depth study and modification of game mechanics and logic.
Graphics and text are editable via indexed PNG files and YAML properties, with Python scripts for conversion, making modding accessible with tools like Aseprite.
Makefile-driven system supports building vanilla or editable ROMs, with scripts like swapbuild.sh to easily switch between modes for hacking.
Tested with the Oracle randomizer project and includes dedicated branches like hack-base for easier level editing with LynnaLab, fostering ecosystem collaboration.
Cons
Only US ROMs are supported; Japanese and European versions are not documented or buildable, limiting international modding efforts.
Requires specific tools like WLA-DX v10.6 and Python 3, with Windows users needing MSYS2, adding complexity to setup and maintenance.
Seasons has relatively lacking documentation compared to Ages, with many functions poorly named or marked as TODO, hindering ease of use.
Frequently Asked Questions
Related Projects
pokeredDisassembly of Pokémon Red/Blue
pokecrystalDisassembly of Pokémon Crystal
Link's Awakening DXDisassembly of Legend of Zelda: Links Awakening DX
Pokémon YellowDisassembly of Pokemon Yellow
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.