Decompilation of The Legend of Zelda: Ocarina of Time


The Legend of Zelda: Ocarina of Time

Build Status Decompilation Progress Contributors Discord Channel


This repository is a work in progress, and while it can be used to make certain changes, it's still
constantly evolving. If you use it for modding purposes in its current state, please be aware that
the codebase can drastically change at any time. Also note that some parts of the ROM may not be
'shiftable' yet, so modifying them could be difficult at this point.

This is a WIP decompilation of The Legend of Zelda: Ocarina of Time. The purpose of the project is to recreate a source code base for the game from scratch, using information found inside the game along with static and/or dynamic analysis. It is not producing a PC port. For more information you can get in touch with the team on our Discord server.

The only build currently supported is Master Quest (Debug), but other versions are planned to be supported.

It builds the following ROM:

  • zelda_ocarina_mq_dbg.z64 md5: f0b7f35375f9cc8ca1b2d59d78e35405

Note: This repository does not include any of the assets necessary to build the ROM. A prior copy of the game is required to extract the needed assets.





For Windows 10, install WSL and a distribution by following this Windows Subsystem for Linux Installation Guide. We recommend using Debian or Ubuntu 18.04 Linux distributions.

For older versions of Windows, install a Linux VM or refer to either Cygwin or Docker instructions.


For macOS, use homebrew to install the following dependencies:

  • coreutils
  • make
  • python3
  • md5sha1sum
  • libpng

You can install them with the following commands:

brew update
brew install coreutils make python3 md5sha1sum libpng

You'll also need to build and install mips-linux-binutils.

Going forward in this guide, please use gmake whenever you encounter a make command. The make that comes with MacOS behaves differently than GNU make and is incompatible with this project.

You should now be able to continue from step 2 of the Linux instructions.

Linux (Native or under WSL / VM)

1. Install build dependencies

The build process has the following package requirements:

  • git
  • build-essential
  • binutils-mips-linux-gnu
  • python3
  • libpng-dev

Under Debian / Ubuntu (which we recommend using), you can install them with the following commands:

sudo apt-get update
sudo apt-get install git build-essential binutils-mips-linux-gnu python3 libpng-dev

2. Clone the repository

Clone where you wish to have the project, with a command such as:

git clone

3. Prepare a base ROM

Copy over your copy of the Master Quest (Debug) ROM inside the root of this new project directory. Rename the file to "baserom_original.z64", "baserom_original.n64" or "baserom_original.v64", depending on the original extension.

4. Setup the ROM and build process

Setup and extract everything from your ROM with the following command:

make setup

This will generate a new ROM called "baserom.z64" that will have the overdump removed and the header patched. It will also extract the individual assets from the ROM.

5. Build the ROM

Run make to build the ROM. Make sure your path to the project is not too long, otherwise this process may error.


If all goes well, a new ROM called "zelda_ocarina_mq_debug.z64" should be built and the following text should be printed:

zelda_ocarina_mq_dbg.z64: OK

If you instead see the following:

zelda_ocarina_mq_dbg.z64: FAILED
md5sum: WARNING: 1 computed checksum did NOT match

This means that the built ROM isn't the same as the base one, so something went wrong or some part of the code doesn't match.

NOTE: to speed up the build, you can either:

  • pass -jN to make setup and make, where N is the number of threads to use in the build. The generally-accepted wisdom is to use the number of virtual cores your computer has.
  • pass -j to make setup and make, to use as many threads as possible, but beware that this can use too much memory on lower-end systems.

Both of these have the disadvantage that the ordering of the terminal output is scrambled, so for debugging it is best to stick to one thread (i.e. not pass -j or -jN).


If you want to use Cygwin, you will need to:

Once mips-linux-binutils is installed you will need to install the following packages using Cygwin's installer:

  • libiconv
  • dos2unix
  • python3
  • libpng-devel

Then you can continue from step step 2 of the Linux instructions.

Note that, before building anything, you will need to run the following commands to fix line endings:



1. Setup requirements

To use Docker, you'll need either Docker Desktop or Docker Toolbox installed and setup based on your system.

You'll also need to prepare a local version of the project with a copied base ROM (see steps 2 and 3 of the Linux instructions).

2. Create the docker image

From inside your local project, run the following command:

docker build . -t oot

3. Start the container

To start the container, you can mount your local filesystem into the docker container and run an interactive bash session.

docker run -it --rm --mount type=bind,source="$(pwd)",destination=/oot oot /bin/bash

4. Setup and Build the ROM

Once inside the container, you can follow steps 4 and 5 of the Linux instructions to setup and build the ROM, or run any other command you need.


All contributions are welcome. This is a group effort, and even small contributions can make a difference. Some tasks also don't require much knowledge to get started.

Most discussions happen on our Discord Server, where you are welcome to ask if you need help getting started, or if you have any questions regarding this project and other decompilation projects.

  • Make Jenkins check if a PR will add new warnings

    Make Jenkins check if a PR will add new warnings

    Adds two new stages to Jenkins. The first one is used to check warnings produced by "make setup", while the second one checks the warnings produced by make. This way we will always know if the amount of warnings increment.

    It is done by redirecting stderr of each command to a file, and then compare the lines amount to the current line count (stored in a file in tools/warning_count/).

    If by any reason we need to increment the accepted amount of warnings in the repo, then we can just edit the corresponding warnings file in tools/warning_count/. The script tools/warnings_count/ can do this automatically.

    To test the amount of warnings locally, you can use the script tools/warnings_count/ to create the new warnings files and compare them with the tools/warnings_count/ python script.

    opened by AngheloAlf 22
  • Document code_8006BA00 (Audio Sound Sources)

    Document code_8006BA00 (Audio Sound Sources)

    This documents a small audio file that is separate to the rest of audio. This file handles SoundSources that generate sound effects as an actor moves from one position to another. This is a small file and was already well documented, but there were a couple of small unnamed functions and small changes to be made:

    File Name: code_8006BA00.c -> audio_sound_source.c

    • I wasn't sure whether to use the audio_ prefix or to use the z_ prefix as in z_sound_sources.c since it is separate from the rest of audio, but still deals with audio.
    • I was also considering the name audio_source.c to keep it more abbreviated
    • audio_sfx_source is another option since sound is a generic word and there are many types of sounds that can be generated in audio, and this specifically creates a source for sound effects

    func_8006BA00 -> AudioSource_Init and func_8006BA30 -> AudioSource_Update

    • Both of these are clearly the init and update functions respectively
    • The interesting point is the abbreviation AudioSource_. This ties into the name of the file, alternatives are AudioSoundSource_, Audio_, SoundSource_, AudioSfxSource_...

    Audio_PlaySoundAtPosition -> AudioSource_CreateSoundSource

    • This is the interface with actors that generates and creates a sound source. While it is basically playing a sound at a particular position, there are other functions in code_800EC960.c that would be better to have this name. For example, see this function linked here that will likely be called Audio_PlaySfxByPosAndId or some alternative very close to Audio_PlaySoundAtPosition
    • Alternatives considered were AudioSource_Create, AudioSource_CreateSfxSource

    Move the struct definition of SoundSources from z64.h -> z64audio.h

    • Again, whether this should be moved depends on how closely this file should be associated with audio instead of being treated as it's own independent file.

    Let me know your thoughts on these name, the alternatives to names, or other names I haven't come up with

    opened by engineer124 18
  • `GameInfo` -> `RegEditor`

    `GameInfo` -> `RegEditor`

    Follow-up to #1290 Also name some regs-related functions with the Regs_ "system name"

    The names may benefit discussions, comments are welcome

    Needs contributor approval 
    opened by Dragorn421 17
  • Name scenes (scene enum, entrance enum, various identifiers)

    Name scenes (scene enum, entrance enum, various identifiers)

    Name scenes. Doesn't change file names (e.g. in the spec or assets), only enums and such

    • ~~In include/tables/scene_table.h, comment a name that would be eventually used for the enum and possibly the file (for example DEKU_TREE, MARKET_ENTRANCE_DAY, DEATH_MOUNTAIN_TRAIL)~~
    • ~~In each map's xml, comment a prefix to use for the assets symbols (for example gDekuTree, gMarketEntranceDay, gDMT)~~

    ~~The goal is to formally agree on names for the maps instead of introducing bits at a time at other occasions, like naming random symbols in maps or just writing a sentence in plain English about a particular map's behavior.~~

    ~~I didn't name all scenes because I'm not sure what some should be named. They could be filled in later or by another PR, if we go with commenting names at all~~

    Needs contributor approval Needs lead approval 
    opened by Dragorn421 14
  • Implement define tables for objects, actors and effect soft sprites

    Implement define tables for objects, actors and effect soft sprites

    This follows a discussion we had in discord some time ago and introduces common tables in include/tables/, which are used to define enums and anything related in one place, with the same pattern used in sm64 decomp for levels and courses. The basic idea is to include the table where needed with defines configured to generate what we need for each entry in the table (see the new stuff in z64actor.h for example).

    For now I only implemented it for objects, actors and effects ss, but eventually I think it could be used for other things like scenes and entrances. Items are also a possible candidate which could allow us to unify the item enum with lists like gItemIcons, gItemSlots and sItemActionParams. Get Items could also be a good candidate if we want to unify the GI enum and its table in z_player.c, same thing for the GID enum and its table in z_draw.c.

    I also moved the linker symbol and init vars externs to where they are needed instead of having them in segment_symbols.h and initvars.h, but this is just to simplify things and improve performance and it's not strictly needed.

    Note: The new tables are .h files and I put them in include/tables because this made the most sense to me, but they could technically be any type and in src/ or a dedicated folder if we preferred.

    opened by Roman971 14
  • Native MacOS build support

    Native MacOS build support

    The time of MacOS support is upon us.

    I had to make some changes to the Makefile to support the weird diferences in some tools. I also updated the readme to add some Mac setup help and remove the docker-sync stuff.

    The spec comment move was necessary due to the empty line left after removing that comment causing some issues in the spec parser.

    opened by ethteck 14
  • Rename `vt.h` to `terminal.h`

    Rename `vt.h` to `terminal.h`

    The special character sequences allowing the game (and modern software) to print stuff to the console with colors, are called ANSI escape codes (from Wikipedia, introduced in the 1970s)

    Still from Wikipedia, in 1978 the VT100 terminal (picture below by Jason Scott) was introduced, it supported ANSI codes and its massive popularity popularized ANSI codes.

    DEC VT100 terminal, picture by Jason Scott

    Fast forward to early 2020, a bunch of cool people continue to work on the decompilation of Ocarina of Time 64.

    @Random06457 wants to introduce color codes, since OoT mq debug uses those in osSyncPrintf calls that originally went to the IS64 / IS-viewer (not sure what the actual name is), a development peripheral for the N64 to look at logs printed by the game.

    @MNGoldenEagle suggests VT, from the name of similar products as the VT100 mentioned above.

    (source: screenshot shared by Random, zeldaret discord, #oot-decomp, 02/02/2022 (nice date), )

    And probably since everything in that file at the time was VT_-prefixed the file was simply named vt.h.

    Happy end!

    ... or so everyone thought

    It lasted until @Thar0 decided in #1144 to add BEL, the ASCII BEL character which, when printed, makes a sound play. (for example on windows/in wsl, it makes the commonly heard "windows can't do that" sound)

    vt.h is a good home for BEL, as that file was dedicated to defines for stuff going to a terminal anyway (basically used by osSyncPrintfs)

    But it meant that vt.h had now grown bigger than the ANSI escape codes the VT100 and such were among the first to implement, and it was inevitable some dude would come over and decide the name had to evolve by now.

    I hope all the defines find their new terminal.h home cozy

    vt.h -> terminal.h since

    • it also has the BEL character define which is ASCII and not an ANSI escape code which VT refers to
    • ~~arguably "VT" refers more to the "brand" than standing for "Video Terminal" (which is more of a outdated term anyway imo)~~

    ~~Also VT_ -> TE_ as in "TErminal", for similar reasons~~

    VT = Virtual Terminal now

    Needs contributor approval Needs lead approval 
    opened by Dragorn421 13
  • z_demo documentation

    z_demo documentation

    documents z_demo.c and related commands. Paves the way for documentation of the cutscene actors (which should probably all be documented at once since they are all very similar)

    Some notes:

    • There are many changes needed zap-side after this is merged to use the updated macros and enums.
    • The descriptions of the command macros themselves could probably use some work.
    • The names I gave to things in the cutscene actors are not meant to be taken as fact, only a suggestion. They can be improved when the cutscene actors get documented. What I aimed for is consistency among the names, so they can all be easily found and replaced when needed.
    Needs contributor approval 
    opened by fig02 12
  • Camera Flags

    Camera Flags

    This introduces names and defines for the following camera flags:

    interfaceFlags behaviorFlags stateFlags viewFlags

    And does the small docs for the functions setting and unsetting these flags.

    I'm still debating whether to make interfaceFlags a more "compact" macro i.e. CAM_FLAGS(false, CAM_SHRINKWINVAL_MEDIUM, 0xF, PARA1_FLG_10 | PARA1_FLG_8 | PARA1_FLG_2) for example. Maybe modders can shine insight as to what's easier to work with.

    Also, because it contains function-unique flags, maybe funcFlags instead of just interfaceFlags

    behaviorFlags is also another flag name I'm not quite sure of.

    Also, for setting and unsetting flags, I wasn't sure about plurality i.e. Camera_SetStateFlags vs Camera_SetStateFlag

    Needs discussion Needs lead approval 
    opened by engineer124 12
  • Improve names of files run through the asm processor

    Improve names of files run through the asm processor

    Files now have names resembling their actual names. Example: Instead of /tmp/preprocessedypvrmuch.c files now have names like /tmp/z_play.cvfbopkja.c

    opened by louist103 12
  • Add `` ~~and ``~~; and a few improvements to ``

    Add `` ~~and ``~~; and a few improvements to ``

    • Changes in
      • Will check if ZAPD crashed/failed, stop the extraction and exit with a non-zero exit value (so make will know if something went wrong with this step).
      • Will extract only from XMLs that has been updated since the last extraction, instead of extracting all of them every time.
      • Add a -f/--force flag to force the extraction of every XML (No last-update checks will be performed). -s will always force.
    • Add
    • ~~Add and do a few changes~~
      • ~~--loners flag to include functions that are not called or call any other overlay function.~~
      • ~~Can parse enum and macro values used as actionFunc indexes for array-based actors.~~
      • ~~-s/--style to select a color style for the output image. The styles are files stored in tools/graphovl_styles/. The default is solarized_dark.~~
    opened by AngheloAlf 11
  • Some build system cleanup

    Some build system cleanup

    • Rework how the Makefile lists
      • folders (zapd destination folders under assets, source folders, ...)
      • and files (png, jpg, .s, .c ...)
    • Move text extraction from to running the msgdis script.
      • To extract text without make setup: python3 tools/ --text-out assets/text/message_data.h --staff-text-out assets/text/message_data_staff.h (can easily be found in the makefile too)
    • Remove unused tool makeromfs
    • Remove elf2rom: replaced with
      • objcopy,
      • padding script tools/
      • and tools/n64checksum_6105 for the rom header checksum (from )

    These are mostly changes I've wanted to do for a long time, but really have a reason to make now with the topics of assets system and licensing

    Needs contributor approval Needs lead approval 
    opened by Dragorn421 0
  • Placeholder names for skelanime moveflags

    Placeholder names for skelanime moveflags

    Partly companion to #1437

    • Add "missing" defines for SkelAnime.moveFlags flags, all of them only relevant/effect-bearing in player.
    • Animation system callbacks: name diffScaleY/moveDiffScaleY
    • Add FLAG_FUNC_80832F54_8 (which suprisingly is unused unless I missed something), FLAG_FUNC_80832F54_9
    • Try to name them but it's too FeelsUnkMan, only add "related to" comments

    I wish I could have named them, but still PRing this as it's not trivial to travel from/to the flags in hex to/from where they're used, so it should be useful

    The same flags in CDi's docs: One outstanding difference is (this PR) ANIM_FLAG_PLAYER_SETMOVE vs (CDi) PLAYER_ANIMMOVEFLAGS_KEEP_ANIM_Y_TRANSLATION I think CDi named it based on (?) but I think the other use is a lot more important: :shrug:

    Needs contributor approval Needs lead approval 
    opened by Dragorn421 0
  • Split z64.h: move various things, state, sram, gfx, jpeg, prerender, speedmeter

    Split z64.h: move various things, state, sram, gfx, jpeg, prerender, speedmeter

    • Rename z64transition.h -> z64transition_instances.h
    • Create z64transition.h
    • Create gfx.h, jpeg.h, prerender.h, speedmeter.h, z64sram.h, z64state.h
    • Move RomFile struct and macros to z64dma.h (?)
    • Move CutsceneContext to z64cutscene.h
    • Move InterfaceContext and DoAction enum/macros to z64interface.h
    • Move ObjectContext to z64object.h
    • Move FlagSetEntry, SpeedMeterTimeEntry, ucode_disas structs, to their only use locations in .c files
    • Remove unused HorseStruct

    gfx.h is kind of a grab bag of """gfx""" stuff. I expect stuff inside it to find a better home eventually, at least it's still better than z64.h

    ~z64play.h will be split up further eventually :tm:~ this initially had a new z64play.h housing PlayState and a bunch of stuff but I reverted it so it's still in z64.h

    I also plan to move functions from functions.h to the adequate headers, at a later time. It's annoying enough to review this kind of PR (do tell if these changes are too large and I should make smaller PRs)

    Needs contributor approval Needs lead approval 
    opened by Dragorn421 1
  • Cleanup?: Use gotos in z_play for large else blocks

    Cleanup?: Use gotos in z_play for large else blocks

    (comment applies to initial commit 8311212e729ed9132e940243b28a149f217927c8, I have since reduced the extent of the changes)

    This has the advantage of removing two indentation levels on large chunks of code in Play_Update and Play_Draw. Also IMHO it's actually easier to read with gotos, since the typical code path does not follow gotos. I'm also pretty sure the original code did have gotos, not that I think that has as much value as the previous points. One required goto present in master is I think a huge hint of this.

    I actually think every R_HREG_MODE check uses a goto to skip the relevant block of code, but didn't do so in the PR since it's okay-ish without doing that and I don't think it'd be super popular.

    Note the diff looks very bad. I suggest just looking at the files directly (look for goto usage) Also note I moved the roomDrawFlags temp to another scope

    This is very open to discussion on if we should (not) do less/more of this. Note I don't think this is applicable anywhere else besides Play_Update and Play_Draw, so it's I think not opening Pandora's box to consider this.

    Them: I like bad boys Devs: I use gotos in C where I could have easily done differently (e.g. split Play_Update and Play_Draw into smaller functions :pensive:)

    Needs contributor approval Needs lead approval 
    opened by Dragorn421 1
Zelda Reverse Engineering Team
Zelda Reverse Engineering Team
Real time monaural source separation base on fully convolutional neural network operates on Time-frequency domain.

Real time monaural source separation base on fully convolutional neural network operates on Time-frequency domain.

James Fung 111 Jan 9, 2023
Time Series Quick Simulator - able to perform time series analysis and to setup validation experiments.

tsqsim Time Series Quick Simulator - able to perform time series analysis and to setup validation experiments. With its somewhat limited plotting capa

null 5 Dec 4, 2022
Anomaly Detection on Dynamic (time-evolving) Graphs in Real-time and Streaming manner

Anomaly Detection on Dynamic (time-evolving) Graphs in Real-time and Streaming manner. Detecting intrusions (DoS and DDoS attacks), frauds, fake rating anomalies.

Stream-AD 696 Dec 18, 2022
🐸 Coqui STT is an open source Speech-to-Text toolkit which can run in real time on devices ranging from a Raspberry Pi 4 to high power GPU servers

Coqui STT ( ?? STT) is an open-source deep-learning toolkit for training and deploying speech-to-text models. ?? STT is battle tested in both producti 1.7k Jan 2, 2023
OpenPose: Real-time multi-person keypoint detection library for body, face, hands, and foot estimation

Build Type Linux MacOS Windows Build Status OpenPose has represented the first real-time multi-person system to jointly detect human body, hand, facia

null 25.6k Dec 29, 2022
⚡️Real-time portrait segmentation

ncnn-portrait-segmentation ⚡️ Real-time portrait segmentation This project provides real-time human segmentation based on CPU. Requirements ncnn openc

Youngsoo Lee 39 Dec 21, 2022
NCNN+Int8+YOLOv4 quantitative modeling and real-time inference

NCNN+Int8+YOLOv4 quantitative modeling and real-time inference

pengtougu 20 Dec 6, 2022
Python and C++ implementation of "MarkerPose: Robust real-time planar target tracking for accurate stereo pose estimation". Accepted at LXCV Workshop @ CVPR 2021.

MarkerPose: Robust Real-time Planar Target Tracking for Accurate Stereo Pose Estimation This is a PyTorch and LibTorch implementation of MarkerPose: a

Jhacson Meza 47 Nov 18, 2022
C++20 compile time compressed string tables

Squeeze - C++20 Compile time string compression Experiments in building complex compile time executed code using constexpr functions to generate a com

Ashley Roll 43 Dec 7, 2022
DeepRTS is a high-performance Real-TIme strategy game for Reinforcement Learning research written in C++

DeepRTS is a high-performance Real-TIme strategy game for Reinforcement Learning research. It is written in C++ for performance, but provides an python interface to better interface with machine-learning toolkits. Deep RTS can process the game with over 6 000 000 steps per second and 2 000 000 steps when rendering graphics. In comparison to other solutions, such as StarCraft, this is over 15 000% faster simulation time running on Intel i7-8700k with Nvidia RTX 2080 TI.

Centre for Artificial Intelligence Research (CAIR) 156 Dec 19, 2022
A real-time LiDAR SLAM package that integrates FLOAM and ScanContext.

SC-FLOAM What is SC-FLOAM? A real-time LiDAR SLAM package that integrates FLOAM and ScanContext. FLOAM for odometry (i.e., consecutive motion estimati

Jinlai Zhang 16 Jan 8, 2023
A real-time LiDAR SLAM package that integrates TLOAM and ScanContext.

SC-TLOAM What is SC-TLOAM? A real-time LiDAR SLAM package that integrates TLOAM and ScanContext. TLOAM for odometry. ScanContext for coarse global loc

Jinlai Zhang 3 Sep 17, 2021
[CVPR 2021] NormalFusion: Real-Time Acquisition of Surface Normals for High-Resolution RGB-D Scanning

NormalFusion: Real-Time Acquisition of Surface Normals for High-Resolution RGB-D Scanning Project Page | Paper | Supplemental material #1 | Supplement

KAIST VCLAB 50 Jan 2, 2023
Real-time LiDAR SLAM: Scan Context (18 IROS) + LeGO-LOAM (18 IROS)

SC-LeGO-LOAM NEWS (Nov, 2020) A Scan Context integration for LIO-SAM, named SC-LIO-SAM (link), is also released. Real-time LiDAR SLAM: Scan Context (1

Giseop Kim 11 Jul 15, 2022
ORB-SLAM3 is the first real-time SLAM library able to perform Visual, Visual-Inertial and Multi-Map SLAM with monocular, stereo and RGB-D cameras, using pin-hole and fisheye lens models.

Just to test for my research, and I add coordinate transformation to evaluate the ORB_SLAM3. Only applied in research, and respect the authors' all work.

B.X.W 5 Jul 11, 2022
Real-time object detection with YOLOv5 and TensorRT

YOLOv5-TensorRT The goal of this library is to provide an accessible and robust method for performing efficient, real-time inference with YOLOv5 using

Noah van der Meer 43 Dec 27, 2022
Real-time Skeletonization for Sketch-based Modeling (SMI:2021)

Real-time Skeletonization for Sketch-based Modeling (SMI:2021) Demo We provide an executable software under directory "demo_exe/". Tested Environment

null 247 Dec 21, 2022
Real-Time Neural 3D Hand Pose Estimation from an Event Stream [ICCV 2021]

EventHands: Real-Time Neural 3D Hand Pose Estimation from an Event Stream Project Page Index -- how to train the model from scratch EVAL_REAL

null 23 Nov 7, 2022
Port of the 2020 support library to Raspberry Pi for the VL53L3CX Time-of-Flight ranging sensor with advanced multi-object detection

Port of ST VL53L3CX (2020) driver library to Raspberry Pi This is a port of the support library to Raspberry Pi for the VL53L3CX Time-of-Flight rangin

Niall Douglas 4 Jul 27, 2022