Build From Source

Getting started

Dependencies.

• Clean USA ALTTP ROM at the project root as zelda3.sfc or zelda3.smc. Examples below use zelda3.sfc. USA SHA256: 66871d66be19ad2c34c927d6b14cd8eb6fc3181965b6e517cb361f7316009cfb
• Git for cloning and updating.
• Python 3 with a project virtual environment using requirements.txt.
• SDL2 development files on Linux/macOS. Windows Visual Studio builds use NuGet.

Python on Windows

On Windows, check Add python.exe to PATH in the Python installer.

If you cannot find your Windows Python folder, press Win + R, enter %AppData%, then go back from Roaming to Local.

Windows

Build programs.

Visual Studio

Install the Desktop development with C++ workload. Visual Studio restores the native SDL2 NuGet packages.

Visual Studio downloads

TCC

TCC is lightweight, but builds without optimizations. The helper expects third_party\SDL2-2.26.3.

TCC releases

MSYS2

Install the MSYS2 build tools and SDL2 packages, then use make.

MSYS2 install

MSYS2 setup

Launch MSYS2 MINGW64 and confirm SDL2 before building.

sdl2-config --version
sdl2-config --cflags
sdl2-config --libs

Expected SDL2 compiler flags:

-IC:/msys64/mingw64/include/SDL2 -Dmain=SDL_main

Expected SDL2 linker flags:

-LC:/msys64/mingw64/lib -lmingw32 -mwindows -lSDL2main -lSDL2

Clone and extract

Clone, prepare Python, and extract assets.

Open Git Bash, PowerShell, or MSYS2 MINGW64.

git clone --recursive https://github.com/xander-haj/Z3R
cd Z3R

If the repo was cloned without submodules, initialize them before building.

git submodule update --init --recursive

Create the Python environment

macOS and Linux:

python3 -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt

Windows PowerShell:

py -3 -m venv venv
.\venv\Scripts\python -m pip install -r requirements.txt

Windows Git Bash or MSYS2 Bash:

python -m venv venv
./venv/Scripts/python -m pip install -r requirements.txt

Put zelda3.sfc or zelda3.smc in the project root.

macOS and Linux:

venv/bin/python assets/restool.py --extract-from-rom

Windows PowerShell:

.\venv\Scripts\python assets\restool.py --extract-from-rom

Windows Git Bash or MSYS2 Bash:

./venv/Scripts/python assets/restool.py --extract-from-rom

When extraction finishes, confirm zelda3_assets.dat exists in the project root.

Multi-language

Build extra dialogue assets.

You need the regular North American ROM and the ROM for the language you want to use.

For German, rename the German ROM to German.sfc and put it in the project root.

python assets/restool.py --extract-dialogue -r German.sfc
python assets/restool.py --languages=de

This creates dialogue_de.txt and font_de.png.

Select the language in zelda3.user.ini.

!include zelda3.ini

[General]
Language = de

Supported language codes

• German: de
• French: fr
• French-Canadian: fr-c
• English: en
• Spanish: es
• Polish: pl
• Portuguese: pt
• Redux: redux
• Dutch: nl
• Swedish: sv

Mac/Linux

Build from the project root.

make -j$(nproc)
make clean && make -j$(nproc)

Windows

MSYS2 build.

make

Windows

Visual Studio build.

1. Open Zelda3.sln.
2. Let Visual Studio restore NuGet packages from packages.config.
3. Select Release and x64.
4. In Solution Explorer, right-click zelda3.
5. Click Build.

The built executable is inside bin\x64-Release.

Windows

TCC build.

1. Create third_party.
2. Place tcc.exe at third_party\tcc\tcc.exe.
3. Place SDL2.dll at third_party\SDL2-2.26.3\lib\x64\SDL2.dll.
4. Double click the run_with_tcc.bat file.

The batch file performs basic error checks and starts the game.

Update

Update an existing folder.

cd Z3R
git pull

Rebuild after updating. Regenerate assets if asset scripts or extracted data changed.