monthly

GitHub C Trending

The latest build: 2024-06-16Source of data: GitHubTrendingRSS

Decompilation of The Legend of Zelda: Majora's Mask


Legend of Zelda: Majora's Mask (US) 1.0

Build StatusDecompilation ProgressContributorsDiscord Channel

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

This is a WIP decompilation of The Legend of Zelda: Majora's Mask. 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, and will not, produce a PC port. For frequently asked questions, you can visit our website, and for more information you can get in touch with the team on our Discord server.

The only version currently supported is N64 US, but we intend to eventually support every retail version of the original game (i.e. not versions of MM3D, which is a totally different game).

It currently builds the following ROM and compressed ROM:

  • mm-n64-us.z64 md5: f46493eaa0628827dbd6ad3ecd8d65d6
  • mm-n64-us-compressed.z64 md5: 2a0a8acb61538235bc1094d297fb6556

This repo does not include any assets or assembly code necessary for compiling the ROM. A prior copy of the game is required to extract the required assets.

Please refer to the following for more information:

Installation

Windows

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

MacOS

Preparation is covered in a separate document.

Docker

Preparation is covered in Building Docker.

Linux (Native or under WSL / VM)

1. Install build dependencies

The build process has the following package requirements:

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

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

sudo apt updatesudo apt install make git build-essential binutils-mips-linux-gnu python3 python3-pip python3-venv libpng-dev

2. Clone the repository

Create your own fork of the repository at https://github.com/zeldaret/mm. Then clone your fork where you wish to have the project, with the command:

git clone https://github.com/<YOUR_USERNAME>/mm.git

This will copy the GitHub repository contents into a new folder in the current directory called mm. Change into this directory before doing anything else:

cd mm

3. Prepare a base ROM

Place a copy of the US ROM inside the baseroms/n64-us/ folder.

Rename the file to baserom.z64, baserom.n64 or baserom.v64, depending on the original extension.

4. Make and Build the ROM

To start the extraction/build process, run the following command:

make init

The extraction/build process:

  1. Prepares build environment:
    • Creates a Python virtual environment
    • Downloads necessary tools from pip
    • Compiles tools for the build process
  2. Extracts ROM contents:
    • Decompresses the ROM
    • Extracts individual files
    • Extracts archive files
  3. Extracts assets:
    • Extracts assets based on the XML files found in assets/xml
  4. Disassembles code:
    • Disassembles code-containing files
    • Disassembles data (data, rodata, and bss)
  5. Builds the ROM:
    • Compiles the code and assets into a new ROM
    • Generates a compressed version of the ROM

If all goes well, the new ROM should be built at build/n64-us/mm-n64-us.z64, a compressed version generated at build/n64-us/mm-n64-us-compressed.z64, and the following text printed:

build/n64-us/mm-n64-us.z64: OK

and

build/n64-us/mm-n64-us-compressed.z64: OK

If you instead see the following:

build/n64-us/mm-n64-us.z64: FAILEDmd5sum: WARNING: 1 computed checksum did NOT match

or

build/n64-us/mm-n64-us-compressed.z64: FAILEDmd5sum: WARNING: 1 computed checksum did NOT match

This means that something is wrong with the ROM's contents. Either the baserom files are incorrect due to a bad ROM, or some of the code is not matching.

Running make init will also make the ./expected directory and copy all of the files there, which will be useful when running the diff script. The diff script is useful in decompiling functions and can be run with this command: ./tools/asm-differ/diff.py -wmo3 <insert_function_here>

Note: to speed up the build, you can pass -jN to make setup and make, where N is the number of threads to use in the build, e.g. make -j4. The generally-accepted wisdom is to use the number of virtual cores your computer has, which is the output of nproc (which should be installed as part of coreutils). 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 -jN). (-j also exists, which uses unlimited jobs, but is generally slower.)

Contributing

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

Please note that is is our strict policy that Anyone who wishes to contribute to the OOT or MM projects must not have accessed leaked source code at any point in time for Nintendo 64 SDK, iQue player SDK, libultra, Ocarina of Time, Majora's Mask, Animal Crossing/Animal Forest, or any other game that shares the same game engine or significant portions of code to a Zelda 64 game or any other console similar to the Nintendo 64.

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 or ZeldaRET's other decompilation projects.

For more information on getting started, see our Contributing Guide, Style Guide and our Code Review Guidelines to see what code quality guidelines we follow.

Cross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.


Build StatusCoverity Scan Build StatusCrowdin

RetroArch

RetroArch is the reference frontend for the libretro API. Popular examples of implementations for this API includes video game system emulators and game engines as well as more generalized 3D programs. These programs are instantiated as dynamic libraries. We refer to these as "libretro cores".

XMB menu driver

rgui menu driver

glui menu driver

ozone menu driver

libretro

libretro is an API that exposes generic audio/video/input callbacks. A frontend for libretro (such as RetroArch) handles video output, audio output, input and application lifecycle. A libretro core written in portable C or C++ can run seamlessly on many platforms with very little to no porting effort.

While RetroArch is the reference frontend for libretro, several other projects have used the libretro interface to include support for emulators and/or game engines. libretro is completely open and free for anyone to use.

libretro API header

Binaries

Latest binaries are currently hosted on the buildbot.

Support

To reach developers, either make an issue here on GitHub, make a thread on the forum, chat on discord, or visit our IRC channel: #retroarch @ irc.freenode.org. You could create a post in Reddit with Technical Support flair.

Documentation

See our Documentation Center. On Unix, man-pages are provided. More developer-centric stuff is found here.

Related projects

Philosophy

RetroArch attempts to be small and lean while still having all the useful core features expected from an emulator. It is designed to be very portable and features a gamepad-centric and touchscreen UI. It also has a full-featured command-line interface.

In some areas, RetroArch goes beyond and emphasizes on not-so-common technical features such as multi-pass shader support, real-time rewind (Braid-style), video recording (using FFmpeg), run-ahead input latency removal, etc.

RetroArch also emphasizes being easy to integrate into various launcher frontends.

Platforms

RetroArch has been ported to the following platforms:

  • Android (2.x to most recent version)
  • Apple iOS
  • Apple macOS (PPC, x86-32 and x86-64)
  • Apple tvOS
  • Blackberry
  • DOS
  • Emscripten (WebAssembly and JavaScript)
  • FreeBSD
  • Haiku
  • Linux
  • Original Microsoft Xbox
  • Microsoft Xbox 360 (Libxenon/XeXDK)
  • Microsoft Xbox One
  • Microsoft Xbox Series S/X
  • Miyoo
  • NetBSD
  • Nintendo NES/SNES Classic Edition
  • Nintendo GameCube
  • Nintendo Wii
  • Nintendo Switch
  • Nintendo Wii U
  • Nintendo 3DS/2DS
  • OpenBSD
  • OpenDingux
  • PlayStation2
  • PlayStation3
  • PlayStation4
  • PlayStation Portable
  • PlayStation Vita
  • Raspberry Pi
  • ReactOS
  • RetroFW
  • RS90
  • SerenityOS
  • Solaris
  • Windows NT 3.5
  • Windows 95
  • Windows 98
  • Windows 2000
  • Windows XP
  • Windows Millennium
  • Windows Vista
  • Windows 7
  • Windows 8
  • Windows 10
  • Windows 11

Dependencies (PC)

There are no true hard dependencies per se.

On Windows, RetroArch can run with only Win32 as dependency.

On Linux, there are no true dependencies. For optimal usage, the following dependencies come as recommended:

  • GL headers / Vulkan headers
  • X11 headers and libs, or EGL/KMS/GBM

OSX port of RetroArch requires latest versions of XCode to build.

RetroArch can utilize these libraries if enabled:

  • nvidia-cg-toolkit
  • libfreetype2 (TTF font rendering on screen)

RetroArch needs at least one of these audio driver libraries:

  • ALSA
  • OSS
  • RoarAudio
  • RSound
  • OpenAL
  • JACK
  • SDL
  • PulseAudio
  • XAudio2 (Win32, Xbox 360)
  • DirectSound (Win32, Xbox 1)
  • CoreAudio (OSX, iOS)

To run properly, RetroArch requires a libretro implementation present; however, as it's typically loaded dynamically, it's not required at build time.

Dependencies (Console ports, mobile)

Console ports have their own dependencies, but generally do not require anything other than what the respective SDKs provide.

Requirements

OpenGL1

Your videocard needs to at least support the OpenGL 1.1 spec.

Shaders: N/A

Menu driver support: MaterialUI, XMB, Ozone and RGUI should all work correctly. XMB won't have shader pipeline effects because of the aforementioned lack of shader support.

OpenGL2

Your videocard needs to at least support the OpenGL 2.1 spec.

Shaders: You can choose between either NVIDIA Cg shaders (deprecated, requires separate runtime to be installed on your system), or GLSL shaders.

Menu driver support: MaterialUI, XMB, Ozone and RGUI should all work correctly.

OpenGL3

Your videocard needs to at least support the OpenGL 3.2 core feature spec.

Shaders: You will be able to use modern Slang shaders with this driver.

Menu driver support: MaterialUI, XMB, Ozone and RGUI should all work correctly.

Direct3D 11

Your videocard needs to at least support the Direct3D11 11.0 spec. The card also needs to support at least the Shader Model 4.0.

Shaders: You will be able to use modern Slang shaders with this driver.

Menu driver support: MaterialUI, XMB, Ozone and RGUI should all work correctly.

Vulkan

Your videocard needs to at least support the Vulkan 1.0 spec.

Shaders: You will be able to use modern Slang shaders with this driver.

Menu driver support: MaterialUI, XMB, Ozone and RGUI should all work correctly.

Configuring

The default configuration is defined in config.def.h. It is not recommended to change this unless you know what you're doing. These can later be tweaked by using a config file. A sample configuration file is installed to /etc/retroarch.cfg. This is the system-wide config file.

RetroArch will on startup create a config file in $XDG\_CONFIG\_HOME/retroarch/retroarch.cfg if it does not exist. Users only need to configure a certain option if the desired value deviates from the value defined in config.def.h.

To configure joypads, use the built-in menu or manually configure them in retroarch.cfg.

Compiling and installing

Instructions for compiling and installing RetroArch can be found in the Libretro/RetroArch Documentation Center.

CRT 15Khz Resolution Switching

CRT SwitchRes will turn on, on the fly. However, you will need to restart RetroArch to disable it. With CRT SwitchRes enable RetroArch will start in 2560 x 480 @ 60.

If you are running Windows, before enabling the CRT SwitchRes options please make sure you have installed CRTEmudriver and installed some modelines. The minimum modelines for all games to switch correctly are:

  • 2560 x 192 @ 60.000000
  • 2560 x 200 @ 60.000000
  • 2560 x 240 @ 60.000000
  • 2560 x 224 @ 60.000000
  • 2560 x 237 @ 60.000000
  • 2560 x 256 @ 50.000000
  • 2560 x 254 @ 55.000000
  • 2560 x 448 @ 60.000000
  • 2560 x 480 @ 60.000000

Install these modelines replacing 2560 with your desired super resolution. The above resolutions are NTSC only so if you would be playing any PAL content please add PAL modelines:

  • 2560 x 192 @ 50.000000
  • 2560 x 200 @ 50.000000
  • 2560 x 240 @ 50.000000
  • 2560 x 224 @ 50.000000
  • 2560 x 288 @ 50.000000
  • 2560 x 237 @ 50.000000
  • 2560 x 254 @ 55.000000
  • 2560 x 448 @ 50.000000
  • 2560 x 480 @ 50.000000

Some games will require higher PAL resolutions which should also be installed:

  • 2560 x 512 @ 50.000000
  • 2560 x 576 @ 50.000000

Ideally install all these modelines and everything will work great.

Super Resolutions

The default super resolution is 2560. It is displayed just under the CRT switch option, which can be found in video settings. This can be changed within the retroarch.cfg. The only compatible resolutions are 1920, 2560 and 3840. Any other resolutions will be ignored and native switching will be activated.

Native Resolutions

If native resolutions are activated you will need a whole new set of modelines:

  • 256 x 240 @ 50.006977 SNESpal

  • 256 x 448 @ 50.006977 SNESpal

  • 512 x 224 @ 50.006977 SNESpal

  • 512 x 240 @ 50.006977 SNESpal

  • 512 x 448 @ 50.006977 SNESpal

  • 256 x 240 @ 60.098812 SNESntsc

  • 256 x 448 @ 60.098812 SNESntsc

  • 512 x 240 @ 60.098812 SNESntsc

  • 512 x 224 @ 60.098812 SNESntsc

  • 512 x 448 @ 60.098812 SNESntsc

  • 256 x 192 @ 59.922745 MDntsc

  • 256 x 224 @ 59.922745 MDntsc

  • 320 x 224 @ 59.922745 MDntsc

  • 320 x 240 @ 59.922745 MDntsc

  • 320 x 448 @ 59.922745 MDntsc

  • 320 x 480 @ 59.922745 MDntsc

  • 256 x 192 @ 49.701458 MDpal

  • 256 x 224 @ 49.701458 MDpal

  • 320 x 224 @ 49.701458 MDpal

  • 320 x 240 @ 49.701458 MDpal

  • 320 x 288 @ 49.701458 MDpal

  • 320 x 448 @ 49.701458 MDpal

  • 320 x 480 @ 49.701458 MDpal

  • 320 x 576 @ 49.701458 MDpal

  • 256 x 288 @ 49.701458 MSYSpal

  • 256 x 240 @ 60.098812 NESntsc

  • 256 x 240 @ 50.006977 NESpal

  • 640 x 237 @ 60.130001 N64ntsc

  • 640 x 240 @ 60.130001 N64ntsc

  • 640 x 480 @ 60.130001 N64ntsc

  • 640 x 288 @ 50.000000 N64pal

  • 640 x 480 @ 50.000000 N64pal

  • 640 x 576 @ 50.000000 N64pal

  • 256 x 252 @ 49.759998 PSXpal

  • 320 x 252 @ 49.759998 PSXpal

  • 384 x 252 @ 49.759998 PSXpal

  • 640 x 252 @ 49.759998 PSXpal

  • 640 x 540 @ 49.759998 PSXpal

  • 384 x 240 @ 59.941002 PSXntsc

  • 256 x 480 @ 59.941002 PSXntsc

  • 352 x 240 @ 59.820000 Saturn/SGFX_NTSCp

  • 704 x 240 @ 59.820000 SaturnNTSCp

  • 352 x 480 @ 59.820000 SaturnNTSCi

  • 704 x 480 @ 59.820000 SaturnNTSCi

  • 352 x 288 @ 49.701458 SaturnPALp

  • 704 x 288 @ 49.701458 SaturnPALp

  • 352 x 576 @ 49.701458 SaturnPALi

  • 704 x 576 @ 49.701458 SaturnPALi

  • 240 x 160 @ 59.730000 GBA

  • 320 x 200 @ 60.000000 Doom

// Arcade

  • 400 x 254 @ 54.706841 MK
  • 384 x 224 @ 59.637405 CPS1

These modelines are more accurate giving exact hz. However, some games may have unwanted results. This is due to mid-scanline resolution changes on the original hardware. For the best results super resolutions are the way to go.

CRT resolution switching & MAME

Some arcade resolutions can be very different from consumer CRTs. There is resolution detection to ensure MAME games will be displayed in the closest available resolution but drawn at their native resolution within this resolution. Meaning that the MAME game will look just like the original hardware.

MAME ROMs that run in a vertical aspect like DoDonPachi need to be rotated within MAME before resolution switching and aspect correction will work. Do this before enabling CRT SwitchRes so that RetroArch will run in your desktop resolution. Once you have rotated any games that may need it turn CRT SwitchRes on.

Socials

The links below belong to our official channels. Links other than this may have been created by fans, independent members or followers. We seriously recommend using our original resources.

Espressif IoT Development Framework. Official development framework for Espressif SoCs.


Espressif IoT Development Framework

ESP-IDF is the development framework for Espressif SoCs supported on Windows, Linux and macOS.

ESP-IDF Release Support Schedule

Support Schedule

ESP-IDF Release and SoC Compatibility

The following table shows ESP-IDF support of Espressif SoCs where alt text and alt text denote preview status and support, respectively. The preview support is usually limited in time and intended for beta versions of chips. Please use an ESP-IDF release where the desired SoC is already supported.

Chipv4.4v5.0v5.1v5.2v5.3
ESP32alt textalt textalt textalt textalt text
ESP32-S2alt textalt textalt textalt textalt text
ESP32-C3alt textalt textalt textalt textalt text
ESP32-S3alt textalt textalt textalt textalt textAnnouncement
ESP32-C2alt textalt textalt textalt textAnnouncement
ESP32-C6alt textalt textalt textAnnouncement
ESP32-H2alt textalt textalt textAnnouncement
ESP32-P4alt textAnnouncement
ESP32-C5alt textAnnouncement

There are variants of revisions for a series of chips. See Compatibility Between ESP-IDF Releases and Revisions of Espressif SoCs for the details of the compatibility between ESP-IDF and chip revisions.

Espressif SoCs released before 2016 (ESP8266 and ESP8285) are supported by RTOS SDK instead.

Developing With ESP-IDF

Setting Up ESP-IDF

See https://idf.espressif.com/ for links to detailed instructions on how to set up the ESP-IDF depending on chip you use.

Note: Each SoC series and each ESP-IDF release has its own documentation. Please see Section Versions on how to find documentation and how to checkout specific release of ESP-IDF.

Non-GitHub forks

ESP-IDF uses relative locations as its submodules URLs (.gitmodules). So they link to GitHub. If ESP-IDF is forked to a Git repository which is not on GitHub, you will need to run the script tools/set-submodules-to-github.sh after git clone.

The script sets absolute URLs for all submodules, allowing git submodule update --init --recursive to complete. If cloning ESP-IDF from GitHub, this step is not needed.

Finding a Project

As well as the esp-idf-template project mentioned in Getting Started, ESP-IDF comes with some example projects in the examples directory.

Once you've found the project you want to work with, change to its directory and you can configure and build it.

To start your own project based on an example, copy the example project directory outside of the ESP-IDF directory.

Quick Reference

See the Getting Started guide links above for a detailed setup guide. This is a quick reference for common commands when working with ESP-IDF projects:

Setup Build Environment

(See the Getting Started guide listed above for a full list of required steps with more details.)

  • Install host build dependencies mentioned in the Getting Started guide.
  • Run the install script to set up the build environment. The options include install.bat or install.ps1 for Windows, and install.sh or install.fish for Unix shells.
  • Run the export script on Windows (export.bat) or source it on Unix (source export.sh) in every shell environment before using ESP-IDF.

Configuring the Project

  • idf.py set-target <chip_name> sets the target of the project to <chip_name>. Run idf.py set-target without any arguments to see a list of supported targets.
  • idf.py menuconfig opens a text-based configuration menu where you can configure the project.

Compiling the Project

idf.py build

... will compile app, bootloader and generate a partition table based on the config.

Flashing the Project

When the build finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this automatically by running:

idf.py -p PORT flash

Replace PORT with the name of your serial port (like COM3 on Windows, /dev/ttyUSB0 on Linux, or /dev/cu.usbserial-X on MacOS. If the -p option is left out, idf.py flash will try to flash the first available serial port.

This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with idf.py menuconfig.

You don't need to run idf.py build before running idf.py flash, idf.py flash will automatically rebuild anything which needs it.

Viewing Serial Output

The idf.py monitor target uses the esp-idf-monitor tool to display serial output from Espressif SoCs. esp-idf-monitor also has a range of features to decode crash output and interact with the device. Check the documentation page for details.

Exit the monitor by typing Ctrl-].

To build, flash and monitor output in one pass, you can run:

idf.py flash monitor

Compiling & Flashing Only the App

After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table:

  • idf.py app - build just the app.
  • idf.py app-flash - flash just the app.

idf.py app-flash will automatically rebuild the app if any source files have changed.

(In normal development there's no downside to reflashing the bootloader and partition table each time, if they haven't changed.)

Erasing Flash

The idf.py flash target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run idf.py erase-flash.

This can be combined with other targets, ie idf.py -p PORT erase-flash flash will erase everything and then re-flash the new app, bootloader and partition table.

Resources