world-across

World Across is a native PC port of The Legend of Zelda: A Link Between Worlds for Windows and Linux that supports higher resolutions and upscaling.

README

World Across

A native Linux and Windows build of The Legend of Zelda: A Link Between Worlds (Nintendo 3DS), made by translating the game's ARM11 code into C ahead of time rather than interpreting it at runtime. Inside the tree the project still goes by its working name, albw-port: the developer's program is build/albw-boot, and settings and saves live in directories of that name. There is no emulator underneath: each guest function becomes a C function, and the parts of the 3DS operating system the game expects are reimplemented as a small kernel in src/runtime.

This repository contains no part of the game. To build and run it you need your own decrypted dump of a cartridge you own; everything derived from it stays on your machine (see below). This project is not affiliated with, endorsed by or connected to Nintendo. The Legend of Zelda and A Link Between Worlds are trademarks of Nintendo.

Status: the opening is playable. The game gets through Horizon's service handshakes, reads archives out of its RomFS, answers its configuration queries, formats and opens its save data and starts its threads. It shows the loading screen, the title screen with its lit 3D scene, the file select and the name entry -- Rename opens a field to type your name in -- and plays through the opening into Link's house and out of its door: Gulley's dialogue, walking, the map on the bottom screen, the item menu, the weather vane that saves the game, and loading that save again. Further in, the game reaches code nobody has translated yet; the port then stops, notes the address, and tools/catch_up.sh translates it into the build (see below). Most of the game has never been played here.

Picture. By default the graphics card draws the game, at up to eight times the console's resolution (1440p for the top screen at six), with multisampled anti-aliasing; AMD FSR 3 and NVIDIA DLSS can upscale it instead, and above 60 frames a second frames in between are drawn from the game's real geometry. A software renderer draws the console's own resolution on the processor; it is what the regression checks compare against.

Sound comes from the port's own version of the DSP's audio firmware: the game's voices -- ADPCM music streams, PCM sound effects -- decoded, resampled, filtered and mixed, 32,728 samples a second.

What is missing: cube maps and the other GPU features this game has not been seen to use, the DSP's reverb and compressor, frame generation, and the certainty that the rest of the game runs. So this is a port whose first scenes can be played, plus the tooling to keep extending it as the game goes on -- not yet one anybody has played through.

Download

The releases have the launcher for Linux and for Windows. It holds no part of the game: the first time it starts, you choose your card -- a decrypted dump of a cartridge you own -- and it makes the game from it on your machine, reading the card, translating the game's code to C and compiling it. That takes a few minutes, once; the tools it needs (the translator, Python and a C compiler) come with it.

  • Linux: World-Across-x86_64.AppImage. Make it executable (chmod +x) and start it. It runs on any distribution with glibc 2.34 or later -- Ubuntu 22.04, Debian 12, Fedora 35 and newer -- and needs nothing installed besides a graphics driver.
  • Windows: World-Across-Windows.zip. Unpack it entirely and start WorldAcross.exe from the unpacked folder. Windows 10 or later, 64-bit.

The graphics card draws the game through Vulkan, which every current AMD, NVIDIA and Intel driver provides; without it the processor draws instead. What the launcher makes from your card stays on your machine -- ~/.cache/albw-port/build on Linux, %LOCALAPPDATA%\albw-port\build on Windows -- and is yours alone.

What you need to supply

Nothing in this repository is derived from the game. No code, no assets, no addresses read out of a binary anyone would have to own — with one exception noted below. To build something that runs, you supply your own dump of a cartridge you own, and everything derived from it stays on your machine: rom-extract/, src/generated/, ghidra*/ and *.3ds are all ignored by git.

The exception is entries/, lists of guest addresses the running game branched to that nothing in the image points at, one file per release by its product code (CTR-P-BZLE.txt is the American one), and, beside it, where that release's functions start as the search finds them on its own (CTR-P-BZLE.starts, made by tools/find_functions.py --starts). A release with no list of its own -- the European one, say -- has the American list carried over: the two are the same program laid out a little differently, the gaps between their functions show by how much each stretch moved, and an address moves with its stretch. They are kept so that a build is reproducible rather than depending on how far someone has played. They are addresses, not code. Another release needs none of them to build: its own file starts empty and fills as tools/catch_up.sh meets what is missing.

A dump must be decrypted; the RomFS reader refuses an encrypted image rather than producing confusing garbage.

Building

Required packages, by what they are for:

ForPackages
Buildingcmake, ninja, gcc
A window, input (optional)sdl3 — without it the port builds and runs headless
The launcher's text (optional)stb (stb_truetype) and any TrueType font — without it the game starts straight away
The GPU renderer and AMD FSR 1 (optional)shaderc (glslc) at build time, and a Vulkan driver — without them the processor draws and the picture is scaled plainly
AMD FSR 3 upscaling (optional)AMD's FidelityFX SDK 1.1.4 in external/ (below), vulkan-headers, python — without it the choice is dimmed
NVIDIA DLSS upscaling (optional)NVIDIA's DLSS SDK in external/ (below), vulkan-headers, and an NVIDIA RTX card to run it on
Translatingpython3, python-capstone
Verifying (optional)python-unicorn

Then, from a checkout:

python3 tools/extract_rom.py /path/to/your.3ds

That writes rom-extract/code.bin — the executable segment, loaded at 0x00100000 — plus the exheader and ExeFS pieces and the card's product code, and prints the segment layout and the services the binary declares.

python3 tools/find_functions.py
python3 tools/recompile.py --all --split 16

The first finds the game's functions in its code -- where each one starts and which addresses make up its body -- and writes them to rom-extract/functions.tsv; it takes about a minute and a half. The second translates them into src/generated/: one C file per chunk of translated functions, plus the dispatch table. It prints how much it could translate and what the remaining gaps are.

cmake -B build -G Ninja && ninja -C build
Windows

The Windows program is built on Linux -- or under WSL2 on Windows itself -- with the MinGW-w64 cross compiler, from the same translation (the extracting and translating steps above are the same):

cmake -B build-win -G Ninja -DCMAKE_TOOLCHAIN_FILE=cmake/mingw-w64-x86_64.cmake
ninja -C build-win

That needs mingw-w64-gcc (Arch; gcc-mingw-w64-x86-64-posix and g++-mingw-w64-x86-64-posix on Debian and Ubuntu) and, for the window, SDL3's MinGW development files: unpack SDL3-devel-<version>-mingw.tar.gz from SDL's releases into external/ (or point SDL3_DIR at its x86_64-w64-mingw32/lib/cmake/SDL3). Without them it is built headless. The result is build-win/albw-boot.exe, with SDL3.dll beside it; it needs Windows 10 or later and, for the GPU renderer, a Vulkan driver (every current AMD, NVIDIA and Intel driver has one). Settings and saves go to %APPDATA%\albw-port, and the log of the last run, when it was not started from a console, to %APPDATA%\albw-port\last-run.log.

The Windows build is checked the way the Linux one is, under Wine: ALBW_WINE=1 tools/frames_check.sh check and ALBW_WINE=1 tools/routes_check.sh check play it against the same reference, and it has to come out byte for byte the same. FSR 3 and DLSS are not in the Windows build yet. Like everything built from your cartridge, it is yours alone.

The launcher and the packages

Besides albw-boot, the build makes world-across (WorldAcross.exe on Windows): the same program without the translation linked in. It finds the game as a module -- libgame.so, or game.dll -- in the cache folder, and where there is none yet, it makes one from the card (src/runtime/albw_builder.c): it runs the three steps above with the tools of a kit and compiles the translation, with the glue in src/runtime/albw_game_glue.c, into a module that needs no C library (src/runtime/albw_game.h is the interface). world-across --build-game does the same without a window. In a checkout the kit is the checkout itself, with the system's Python and compiler.

The published packages are that launcher with a kit of their own:

tools/make_appimage.sh            # build-appimage/World-Across-x86_64.AppImage
tools/make_windows_package.sh     # build-win/World-Across-Windows.zip

Each bundles the translating tools, Python with capstone and a C compiler cut down to what the translation needs -- GCC 16 from musl-cross for Linux, from w64devkit for Windows -- with their licences and where their sources are. The scripts download nothing: they take what they bundle from external/kit/ and check each file against the SHA-256 sum they name, together with where it comes from. The AppImage builds SDL3 statically and holds the launcher to glibc 2.34 (tools/appimage/); the Windows package needs the Windows build of world-across first. Both refuse to package anything made from a card.

A module the packages' compilers made has to play exactly as albw-boot does: ALBW_BOOT names the program the checks run, so

XDG_CACHE_HOME=<its cache> ALBW_BOOT=build-appimage/World-Across-x86_64.AppImage tools/routes_check.sh check
ALBW_WINE=1 ALBW_BOOT=<unpacked package>/WorldAcross.exe tools/routes_check.sh check

play the AppImage and the Windows package against the same reference.

Running

./build/albw-boot /path/to/your.3ds

The card image is needed at runtime as well as at extraction time, because the game reads its RomFS through the filesystem service rather than from anything baked into the build. Its path is remembered (in ~/.config/albw-port/card), so after the first start ./build/albw-boot alone is enough, from any directory. Started with no card known, the launcher's first item is Choose card, which asks for it in the desktop's file dialog. ALBW_ROM=/path/to/your.3ds names it too, which is how the tools do it.

It will run until it hits something unimplemented and say what that was. Useful knobs:

VariableEffect
ALBW_ROMthe card image, for RomFS reads
ALBW_SAVE_DIRwhere saves go; see below
ALBW_DISCOVER=<file>record the first indirect branch target that has no translated function, then stop
ALBW_NEIGHBOURSreport where else a missing branch target appears in guest memory
ALBW_LOG_FIRST, ALBW_LOG_TOTALhow many times each kind of event is logged, and how many lines in total
ALBW_TRACE_FILE, ALBW_TRACE_SKIP, ALBW_TRACE_CAPwhere to write the instruction trace and which window of it (albw-boot-trace only)
ALBW_DUMP_FRAMES, ALBW_DUMP_EVERYwrite the screens as PPMs into a directory, and how often
ALBW_DUMP_CMDLIST, ALBW_DUMP_REGS, ALBW_DUMP_DRAWSwhat the guest asks the GPU for
ALBW_DUMP_SHADER=<dir>the uploaded vertex shaders, disassembled, one file per entry point
ALBW_RENDER=<n>, ALBW_RENDER_FROM=<frame>rasterise n frames, from this one, without a window
ALBW_STOP_AT=<frame>end the run at that frame, for benchmarks; the raster report says where the time went
ALBW_PROFILE=<file>a sampling profile of the run, as offsets addr2line -f -e build/albw-boot reads
ALBW_PROFILE_WALL=1, ALBW_PROFILE_FROM=<frame>profile the main thread's real time instead, from that frame
ALBW_DUMP_TARGET=<dir>the render target itself as a picture, one per draw
ALBW_DUMP_FROMthe first frame ALBW_DUMP_FRAMES writes
ALBW_SCAN, ALBW_PROBEwhere the interesting frames are; what a draw reads and writes
ALBW_WATCH_ADDR=<addr>backtrace every store to one address (albw-boot-nan only)
ALBW_PRESS=<frame>:<buttons>,...scripted controls, e.g. 1300:A,1310:-,7900:CDOWN,8100:-; buttons are A B X Y L R START SELECT UP DOWN LEFT RIGHT, the circle pad CUP CDOWN CLEFT CRIGHT, a touch on the bottom screen T<x>.<y> (e.g. T250.225), joined with +, and - lets go
ALBW_FRESH_SAVES=1with ALBW_SAVE_DIR, tools/discover_loop.sh empties that directory before each round, so a script sees the same menus every time
ALBW_TRACE_QUEUE=<frame>from that frame, each drain of the GPU command queue: lists and the target they left, transfers, fills
ALBW_NO_BATCH=1rasterise every draw on its own, to tell a batching mistake from any other
ALBW_DSP_LOG=<frame>from that frame, each buffer a voice starts (format, length, rate) and each voice switched on, off or run dry
ALBW_THREADS=1with ALBW_STOP_AT, what each thread is waiting on when the run stops
ALBW_SCREENSHOT=<frame>:<file.bmp>the whole window as it looked at that frame (works offscreen with SDL_VIDEO_DRIVER=offscreen)
ALBW_DUMP_MEM=<frame>,...write the guest's data, heap and linear memory at those frames, into ALBW_DUMP_MEM_DIR
ALBW_REPLAY_CHECK=1record every frame as the frames in between are drawn from, play it back unmoved into the shadow, and compare it with the game's own picture (it must come out byte for byte the same; works headless)
ALBW_REPLAY_HALF=<frame>write that frame's top screen, the one before it, and three frames between them as PPMs into ALBW_REPLAY_DIR
ALBW_REPLAY_VERBOSE=1what each recorded frame holds, and what a frame in between costs
ALBW_FSR3_TEST=<frame>:<count>[:<scale>]run FSR 3 headless over those frames and write what goes in (the jittered picture, depth, motion) and what comes out into ALBW_REPLAY_DIR
ALBW_GPU_FSR3_TEST=<first>-<last>:<render scale>:<shown scale>:<dir>the same through the GPU renderer: those frames drawn on the card at the render scale with the jitter and the upscaler's targets, upscaled by FSR 3 to the shown scale, and the last one written as fsr3-<frame>.ppm (with its input and motion) beside gpu-<frame>-native.ppm, the frame drawn straight at the shown scale
ALBW_VKUP_TIMES=1what each FSR 3 call spends on its inputs, the dispatch, the card and the output
ALBW_VK_VALIDATE=1FSR 3's Vulkan device with Khronos' validation layer, where it is installed
ALBW_GPU_TEST=<first>[-<last>]:<scale>:<dir>[:alone]draw those recorded frames headless on a GPU device of the port's own (no window, no display touched), at that scale, and write the last one's screens as gpu-<frame>-top.ppm and -bottom.ppm into the directory; :alone has the processor draw nothing from the first frame on, as with the window; ALBW_GPU_SAMPLES sets the multisampling
ALBW_REC_DUMP=<frame>what that frame's record holds, event by event: fills, transfers, texture copies, and each draw's target, viewport and state
ALBW_FRAME_TIMES=<file>each frame's wall time, syscalls, file reads and their bytes, the renderer's time, and how long each guest thread ran (entry point and priority) -- for finding where a hitch comes from
ALBW_WATCH_VRAM=1make VRAM inaccessible whenever guest code runs and report every place that touches it: the game's code never does, which is what lets the GPU renderer leave it undrawn

Playing

With SDL3 installed the port opens a window; without it, or with ALBW_HEADLESS=1, it runs headless exactly as before.

The window opens on a launcher: Play, Settings and Quit. The game itself starts only on Play -- nothing runs or sounds before. Behind the menu goes a picture of your own if you put one at ~/.config/albw-port/background.png (or .jpg); none comes with the port. Without one, the menu shows the scene the game was left in last time -- kept when the window closes after at least two minutes of play, from your own game, in the cache folder as backdrop.jpg. The menu is set in Fira Sans Condensed (SIL Open Font License, in third_party/fonts/), which the packages bring along. Settings (fullscreen, how the screens are arranged, the renderer, its resolution and anti-aliasing, upscaling and its sharpening, the frame rate, whole-pixel scaling, sound, gamepads, the touch screen controls, the game's language) are applied at once and saved in ~/.config/albw-port/settings; the environment variables below still win over them. Choices this build or machine cannot do -- FSR 3 or DLSS without their SDKs, DLSS without an RTX card, frame generation for now -- are shown dimmed, with what they would take. In game, Esc brings the menu back and F1 its settings, with the game paused underneath. ALBW_LAUNCHER=0 starts without it. The two screens are stacked as on the console, and the window can be resized — the picture keeps its shape.

ConsoleKeyboardGamepad
Circle padW A S Dleft stick
D-padarrow keysD-pad
A, BK, Jright and bottom face buttons
X, YI, Utop and left face buttons
L, RQ, Eshoulder buttons or triggers
Start, SelectEnter, BackspaceStart, Back
Touch screenleft mouse button on the bottom screentouchpad, right stick, or gyroscope (below)

The face buttons go by position, not by label: the console's A is on the right and its B at the bottom, and that is what hands remember, whatever the pad prints on them.

The touch screen from a gamepad, as the Touch Screen Controls setting has it (Mouse, Touchpad, Gyro, Stick, or All, the default; the mouse works with all of them). A small ring on the bottom screen shows where a touch lands:

  • Touchpad -- a DualShock 4's, a DualSense's, or either of the Steam Controller's: a finger on it shows a small ring on the bottom screen, the whole pad standing for the whole screen, and pressing the pad in touches the screen there.
  • Stick -- the right stick, which the console never had: tilting it moves the ring, slowly for a slight tilt, quickly for a full one; pressed in, it touches there -- held, it drags. Left alone a few seconds, the ring fades.
  • Gyro: press the right stick in and the ring appears; tilt and turn the pad to move it. Press the stick in again to touch -- held, it drags -- and let go: the touch ends and the ring is gone.

Whichever brought the ring up, the right stick pressed in while it is there touches.

The ring never leaves the screen.

Rename on the file screen opens the console's keyboard, and the window shows a field for it: type the name, or pick keys with a gamepad (A types, B deletes, X shifts, Y is a space) or the mouse; Enter or Start confirms, Esc keeps the name the game offered. Without a window -- headless, the tools -- or with ALBW_USERNAME set, that name (or the login name) is confirmed at once.

KeyDoes
Ppause and resume — the game simply does not get its next frame
Tab (held)run as fast as possible, for long texts and long walks
F11fullscreen
VariableEffect
ALBW_SCALEthe window's starting size, as a multiple of the console's (default 2)
ALBW_RENDERERgpu (default: the gra