RE/Decompilation of Tunnels of Underworld

This repository contains a behavior-focused reconstruction of Tunnels of Underworld (TOU), a 2002 Windows game created by Hannu Kankaanpää and the rest of GigaMess.

The original source appears to be lost. This project was recovered through runtime comparison, disassembly, Ghidra, and an intentionally ugly-first static reconstruction. The original executable remains the authority for gameplay. I do not claim ownership of the original game or its assets.

The project has no official Discord server or subreddit. Please use the repository's Issues and Pull Requests for collaboration.

Current Status

The major gameplay-parity pass is complete. Weapons and Marks, enemy ships, turrets, physics, menus, controls, levels, audio, particles, match statistics, and effects have received hands-on comparison against the original game.

The modern runtime now provides:

• native Windows, Linux, and macOS builds for x86, x64, and ARM64 as applicable;
• SDL3 windowing, input, software-framebuffer presentation, and SDL_mixer audio;
• gamepad gameplay and menu controls, with configurable bindings and controller labels;
• windowed/fullscreen display modes and immediate audio controls;
• menu-selectable display scaling, FSR 1, and optional beta visual effects;
• English, Spanish, Brazilian Portuguese, and Finnish user interfaces;
• human-readable settings.json configuration;
• a visual normal/GG level editor and native level compiler; and
• direct-IP LAN deathmatch for two to four computers without split screen.

The source still looks like a decompilation. Original addresses, raw offsets, and Ghidra-style names remain where changing them without binary evidence could alter behavior. See Codebase before refactoring, Backlog for actual future work, and docs/ for the recovered formats and subsystem notes.

Repository Layout

Game code lives in source/game/; SDL input/audio/windowing and GPU presentation live in source/platform/. The editor and compiler are in source/level-editor/. Build/release scripts, asset/localization utilities, resources and dependencies have their own folders inside source/. Architecture and format documentation lives in docs/; runtime assets remain at the repository root.

See Building for the folder map and build/package commands.

Running a Release

Download the archive matching your operating system and architecture, then extract it completely. Run TOU.exe on Windows, TOU on Linux, or TOU.app on macOS. Keep the executable/app with its packaged asset directories.

The game writes settings.json beside its assets on Windows/Linux. On macOS, user data lives in ~/ToU/, including ~/ToU/settings.json; replacing the app does not replace your settings. Existing app-local settings are imported when the home-folder file is missing. The original default controls were designed for a Windows keyboard; MacBook users should remap them under Options → Controls. Right Option and Right Command are practical primary-action choices.

Press F12 to save a PNG of the final rendered game window, including menus, HUD, scaling and any enabled shader effects. Screenshots go into screenshots/ beside the game on Windows/Linux, or ~/ToU/screenshots/ on macOS. Window borders and other desktop windows are not captured. Filenames are timestamped and never overwrite existing images. Screenshot readback/encoding may briefly hitch a frame.

The reconstructed game identifies itself as Tunnels of Underworld - RE/Decompiled - v{version} so it cannot be confused with the original executable.

Raspberry Pi / Compute Module performance

On Raspberry Pi and Compute Module-based systems, prefer an X11 desktop session. Testing on a CM4 with Debian found severe performance problems and match audio stuttering under Wayland; the game ran better under X11. Changing audio sample settings did not resolve the observed issue. If you hit similar problems, try X11 before tuning the game's audio settings.

LAN deathmatch

Open Team Deathmatch → LAN Deathmatch. One computer hosts and the other one to three players connect by hostname/IP and TCP port (default 27015). Every computer must use the same game build, gameplay assets, ships, levels, and GG themes. There is no AI, discovery, reconnect, relay, or public lobby in this beta. See docs/LAN_BETA.md for the full flow and diagnostics.

Gamepads

SDL3 gamepad support uses its platform drivers (including HIDAPI where available), not a Windows-only XInput integration. Open Options → Controls → Gamepads to assign up to four controllers and change bindings, deadzone, and sensitivity. Keyboard controls remain available alongside controllers. Brake/reverse is listed below thrust. D-pad and shortcuts lists each direction separately alongside the fixed menu actions; these are not button combos.

Xbox defaults: left stick turns, RT thrusts, A fires the primary weapon, X fires the secondary, Y detonates, and LT or D-pad Down brakes/reverses. B is unassigned in gameplay by default and available for rebinding. The D-pad also supplies the original directional controls for weapon selection in bases. Start opens/closes the ESC menu; on that panel A skips the level and Back/View ends the match. In menus the left stick moves the cursor freely; hold A and move the stick left/right to drag sliders. The D-pad also selects rows and changes values. A activates and B returns. Face-button names adapt to detected Xbox, PlayStation, and Nintendo labels; unknown layouts use physical button positions.

Bindings and device slots are saved in settings.json. LAN uses this machine's Player 1 controller settings. Release the controls after reconnecting, changing bindings, or switching between menus and gameplay. Xbox Bluetooth menus and gameplay have passed hands-on testing. Other controller families and platforms still need hands-on testing; see docs/GAMEPADS.md.

Display scaling and beta effects

Options → Details & Visuals → Display and Rendering Settings offers Crisp (integer scaling), Smooth (linear filtering), and Pixel art (default). The setting is saved in settings.json and does not change gameplay resolution.

Select FSR 1 (beta) directly in that menu; no launch flags are needed. The game automatically tries the compatible shader backend on startup. FSR uses AMD's EASU upscaler followed by moderate RCAS sharpening fixed at 70%, with denoising enabled. Without a working shader backend it uses Pixel art instead. The effects and FSR filter remain experimental and optional; see docs/SHADER_PRESENTATION.md for troubleshooting, platform requirements, limitations, and manual checks.

In the same menu, Shader effects (beta) enables explosion bloom, team-colored exhaust flames, and a brief distortion ripple when a ship dies. Weapon-specific lights add yellow Turbo plumes, green MK1 waste pulses, laser glow, vivid machine-gun tracers, Digger cutting sparks, and Gamma Boom's final explosion ripple. Effects are off by default, leave gameplay unchanged, and protect LOS, HUD, and split-screen boundaries. Windows visuals, including the weapon-specific effects, have received hands-on acceptance; other platforms, edge cases and low-power performance still need validation.

Level Editor

Release archives include a separate level-editor/ directory containing:

• tou-level-editor, the visual normal/GG project editor; and
• tou-level-compiler, the command-line compiler and inspector.

Start with source/level-editor/README.md or the packaged HTML level-making guide. The recovered binary format is documented in docs/LEVEL_FORMAT.md.

Building

Requirements:

• a C/C++ compiler for the target platform;
• CMake 3.24 or newer; and
• Ninja, GNU Make, or Visual Studio's build tools.

The build fetches pinned SDL3 and SDL_mixer releases and links them statically:

On Windows, ./source/scripts/build.ps1 -Architecture x64 (or source/scripts/build.bat) uses MSVC. Use -Architecture Win32 or ARM64 for the other Windows targets. The game is written beside the assets, and editor tools go into level-editor/. For Linux/macOS or a configured Ninja toolchain:

cmake -S . -B source/.build/native -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build source/.build/native --parallel 8

The output is TOU.exe on Windows, TOU on Linux, or TOU.app on macOS. Windows packages do not require SDL DLLs or the Visual C++ redistributable. CI uses MSVC for Windows x86 (-A Win32), x64, and ARM64 builds. MinGW-w64 remains an alternative for local builds.

For Windows gamepad development, prefer MSVC with a current Windows SDK so SDL can include Windows Gaming Input and GameInput backends. Older MinGW toolchains may omit these and fail to detect some Xbox Bluetooth controllers. For example:

cmake -S . -B source/.build/x64 -G "Visual Studio 17 2022" -A x64
cmake --build source/.build/x64 --config Release --parallel 8

The Build GitHub Actions workflow runs once for each pull request and for direct pushes to main, except Markdown-only (.md) changes. Manual runs remain available. It builds Windows x86, Windows/Linux x64 and ARM64, and macOS Intel and Apple Silicon, validates localization, checks executable architecture, and stages the full runtime. It never publishes a release.

To create the Windows x64 archive layout used by CI:

cmake --install source/.build/x64 --config Release --prefix source/.build/stage
./source/scripts/package-release.ps1 -Version local -Platform windows-x64 `
  -ExecutablePath ./source/.build/stage/TOU.exe `
  -LevelEditorDirectory ./source/.build/stage/level-editor

Releases

The Build release workflow runs only through manual dispatch. Supply the release tag/version when choosing Run workflow. It builds seven desktop packages and creates or updates that GitHub Release. If the tag already exists, the workflow builds the tagged commit; otherwise it creates the tag at the selected commit. Ordinary commits and tag pushes do not publish releases.

Windows packages use ZIP. Linux and macOS packages use .tar.gz so executable permissions survive extraction.

Future Possibilities

• A simplified, expansion-friendly campaign using newly authored maps.
• LAN discovery, reconnect, latency hiding, AI, and internet-friendly transport.
• Additional community-maintained translations.
• Further optional shader effects behind the authoritative software framebuffer.
• Browser/WebAssembly after native desktop development remains stable.

Contributing

Behavior changes need evidence from the original executable. Refactors must keep x86 and the other native builds working without accidentally changing fixed-point arithmetic, RNG order, callback dispatch, or update order. A successful build is not gameplay acceptance.

Useful diagnostic workflows are documented in docs/REPLAY_DIAGNOSTICS.md and docs/SIMULATION_STATE.md.

Tools Used

• MSVC (Windows CI builds)
• MinGW-w64
• Ghidra and GhidrAssistMCP
• Runtime comparison on hardware capable of running the original game

License

No project-wide license is currently offered for the reconstruction or original game assets. This is not a clean-room decompilation, and the repository includes original game data for preservation purposes.

Third-party code retains its own licenses. The new presentation backend embeds AMD's FidelityFX FSR 1 and Jam3's Gaussian blur kernel under their MIT terms; see THIRD_PARTY_NOTICES.md for sources, pinned revisions, and full-license links. Release archives include both notices as TOU-FSR-LICENSE.txt and TOU-BLOOM-LICENSE.txt.