GauntletDLRedone

Gauntlet: Dark Legacy — native PS2 reconstruction

A native Linux and Windows port of the PlayStation 2 game Gauntlet: Dark Legacy (USA release SLUS-20047), reconstructed from the original program and data in Rust and Bevy; the implementation follows the master plan. Release 1.0.0 was the complete port (acceptance report); release 1.1.0 added the graphics options below and playtest fixes; release 1.2.0 added network play for up to four computers (a native addition, lockstep over TCP: research/network.md) and fixed the size of an opened chest's item; release 1.3.0 made network play hold up over the internet (each computer draws the game ahead of the others' inputs and keeps its own clock); release 1.3.1 plays the movies without FFmpeg (a native MPEG-2 decoder: decisions/0007); release 1.3.2 fixes a lost graphics device on NVIDIA cards during slow loads (a patched wgpu-hal, third_party/) and draws many effects closer to the original — effect transparency and depth, enemy shadows and fades, texture animations, Sumner's ghost (research/release.md). The native game runs the original rules from the player's own disc: the Tower, all realms and bosses, one to four players, the original HUD, menus, audio and movies, and saves; a character has been played from a new game to the ending (docs/coverage.md M15). Native enhancements (widescreen, motion blending at the display's rate, key bindings, Xbox button prompts, texture packs, and since 1.1.0 sharp filtering, full colour, more lights, character shadows, ambient occlusion, bloom and HD textures generated on the player's machine; docs/research/enhancements.md) are optional, and the performance and platform checks are in docs/research/performance.md. Import tooling, inspectors and comparison harnesses sit beside it in crates/gdl_tools and tools/python.

Which version of the game this is

This is a port of the PlayStation 2 version of Gauntlet: Dark Legacy (USA release SLUS-20047), and of that version only. Its gameplay is the PS2 program's: the rules are reconstructed from that program and checked against it running in PCSX2 (docs/research/), and the installer accepts only that disc. Nothing comes from the later GameCube or Xbox releases.

Those releases (2002, built from the PS2 version) added features this port does not have, because the PS2 version does not:

• An item menu: power-ups can be kept and used later, and item pickups can be switched off. On the PS2, and here, a power-up takes effect when it is picked up.
• Sumner as a character unlocked in play (on the GameCube, reportedly by finishing the last coin room, in the Fortified Towers). On the PS2 he is reached only by a code.

Reviews also describe GameCube-only shortcomings (more slowdown than the PS2 version and, outside the PAL release, no life bars for golems, gargoyles and bosses); this port follows the PS2 version there too. Sources: Wikipedia's Gauntlet Dark Legacy article (the item menu, saved power-ups, the GameCube's performance and life bars), Nintendo World Report's GameCube review (slowdown against the PS2 version) and The Cutting Room Floor's page on the game (Sumner's unlock on the GameCube; seen in a search summary, the page itself not read).

What the port adds is on top of the PS2 game and does not change its rules: graphics enhancements (widescreen, sharp filtering, full colour, more lights, character shadows, ambient occlusion, bloom, HD textures; the "Original" preset and "Original presentation" turn them off), motion blending at the display's rate, key bindings, Xbox button prompts, and network play.

To play, download the Linux or Windows package from the releases, run its installer and point it at your own copy of the game: the disc in a drive, a disc image or a copied folder. No game files are included or downloaded. The package's README.txt (release/README.txt) is the player's guide; release/KNOWN_ISSUES.txt lists the limits.

See milestone coverage, current state, toolchain and disc profile. Retail assets, BIOS files, saves and reference captures remain local and ignored (private/). Linux is the development platform; the Windows programs are cross-built and the Windows installer is built with Qt's MinGW kit (docs/toolchain.md "Windows build").

In the development working copy the root .git path is reserved, so its history is kept in private/source-control.git; the tools reach it through bash tools/git-local.sh (normal Git commands), which uses the clone's own .git when that folder is absent. Commits contain code and docs only.

Build the pinned Rust workspace:

cargo build --release --locked
cargo test -p gdl_core -p gdl_formats -p gdl_tools --locked
python3 -m unittest discover -s tools/python -p 'test_*.py'

The existing local extraction is in private/disc/. To reproduce the disc audit after a fresh extraction:

7z x 'Gauntlet - Dark Legacy.iso' -oprivate/disc -y
python3 tools/python/disc_dossier.py 'Gauntlet - Dark Legacy.iso'

Inspect or extract WAD.BIN to a new output path. Existing outputs are preserved:

target/release/gdl_tools wad-inspect private/disc/WAD.BIN private/reports/wad-new.json
target/release/gdl_tools wad-extract private/disc/WAD.BIN private/wad-new

The established cache is private/wad/; manifests bind each payload to the archive SHA-256, index and original path hash. Filenames are index/hash IDs, so unknowns and hash collisions cannot overwrite one another. Native metadata/pixel inspection:

target/release/gdl_tools texdef-inspect PATH_TO_TEXDEF NEW_METADATA_DIRECTORY
target/release/gdl_tools texdef-extract PATH_TO_TEXDEF PATH_TO_TEXTURES NEW_OUTPUT_DIRECTORY

With the established local cache and naming report, launch the native viewer:

# Requires the isolated virtual display described below.
python3 tools/python/run_viewer.py TITLE
python3 tools/python/run_viewer.py --scene LEVELS/levelG1
python3 tools/python/run_viewer.py --rig PLAYERS/SOR/YEL00
python3 tools/python/run_viewer.py --animate PLAYERS/SOR/YEL00

Left/Right select the source bitmap. A cycles source alpha, opaque RGB and an explicitly labelled GS alpha hypothesis. Esc closes. Source pixels and metadata remain unchanged; unsupported formats show a diagnostic. The TITLE package has 15 records; TITLE00 begins at record 11. The static scene uses original terrain, base textures and vertex colors, with explicitly diagnostic opaque/double-sided materials. The rig option shows a labelled translation-only rest hierarchy; animated pose/skin semantics remain unverified. Arrows orbit, WASD pan, Q/E change distance, P shows a detail view and R returns to overview. No native gameplay is implemented.

Independent research helpers require the separately pinned sources described in the upstream audit:

python3 tools/python/verify_wad.py
python3 tools/python/catalog_assets.py

The reference emulator uses its own private configuration and copied BIOS. It is a development dependency only. Do not use the texture viewer to infer native combat/campaign support. Gameplay, full animation acceptance, collision, saves, co-op and release qualification follow the remaining master-plan gates.

For global PINE setup and a saved-state-preserving reference launch, see reference setup. The launcher handles the private configuration; its memory probe accepts the default slot 28011. At the user's request all automated GUI work uses Xvfb; the launchers require the recorded virtual session and never silently use the desktop:

xvfb-run -a -n 191 -e private/reports/xvfb.log -s '-screen 0 1280x1024x24 -nolisten tcp' python3 tools/python/virtual_display.py
# While that process runs, use another terminal:
python3 tools/python/reference_snapshot.py --state private/reference/captures/poison-fields.p2s --out private/reports/NEW_SNAPSHOT.json
python3 tools/python/reference_trace.py --steps 24 --keys Up --out private/reports/NEW_TRACE.json
# A bounded JSON list of {"steps":N,"keys":[...]} supports multi-segment scenarios:
python3 tools/python/reference_trace.py --schedule SCHEDULE.json --out private/reports/NEW_SCHEDULE_TRACE.json

The virtual display selects Mesa software presentation. See reference evidence and geometry evidence for actual checks and limitations. The static research reports can also be exported as glTF:

python3 tools/python/export_scene_gltf.py OBJECTS_REPORT WORLD_REPORT TEXTURE_EXPORT_DIRECTORY NEW_PRIVATE_DIRECTORY

Headless animation research commands preserve original channel payload identities:

target/release/gdl_tools anim-inspect ANIM.PS2 NEW_REPORT.json
target/release/gdl_tools anim-keys ANIM.PS2 TREE_INDEX SEQUENCE_INDEX NEW_KEYS.json
# Requests are [{"tree":0,"node":N,"sequence":S,"frame":F}, ...].
target/release/gdl_tools anim-samples ANIM.PS2 REQUESTS.json NEW_SAMPLES.json
python3 tools/python/reference_trace.py --animation --steps 24 --keys Up --out private/reports/NEW_ANIMATION_TRACE.json
python3 tools/python/compare_animation_keys.py --trace TRACE.json --key-dir KEY_REPORT_DIRECTORY --out private/reports/NEW_COMPARISON.json

The bounded native sampler matches measured Sorceress channels, including walking and three attack clips. Source-qualified local matrices, clocks, bounded transitions and ordinary throw request timing now have reference comparisons. Renderer scale/world integration and complete events remain under recovery; the inspector is not playable. See animation evidence.

The --animate inspector uses original clips and source-qualified local matrices. PgUp/PgDn select clips, brackets step frames, and Space toggles a labelled preview loop. The preview uses presentation time; original gameplay clocks/transitions, world/VU composition and materials remain unaccepted. It is not a playable game.

target/release/gdl_tools anim-transforms ANIM.PS2 INITIAL_POSITION_ANIM.PS2 REQUESTS.json NEW_REPORT.json
python3 tools/python/compare_animation_poses.py --trace TRACE.json --animation-source ANIM.PS2 --rig-source INITIAL_POSITION_ANIM.PS2 --out private/reports/NEW_POSE_COMPARISON

Animation timing metadata uses timing_factor, not FPS: original InitAnim scales this value into a period. Clock-state experiments can be reproduced with:

target/release/gdl_tools anim-clock REQUESTS.json NEW_REPORT.json
target/release/gdl_tools anim-clock-start START_REQUESTS.json NEW_REPORT.json
target/release/gdl_tools anim-select SELECTION_REQUESTS.json NEW_REPORT.json
target/release/gdl_tools player-anim-select ANIM.PS2 PLAYER_REQUESTS.json NEW_REPORT.json
python3 tools/python/compare_animation_clock.py --trace CLOCK_TRACE.json --metadata ANIMATION_METADATA.json --out private/reports/NEW_CLOCK_COMPARISON
python3 tools/python/compare_player_animation.py --trace ACTION_TRACE.json --animation-source ANIM.PS2 --out private/reports/NEW_ACTION_COMPARISON

The bounded player animation chooser matches measured walking, stopping and throw transitions with original requested actions supplied. It predicts selected actions/clips and clock states for supported source branches. Pad/action production, gameplay events and complete game-loop timing remain open. See animation research for bounds and evidence.

Add --events to the player comparison for the bounded ordinary Sorceress throw-request timeline. This compares the event word and start timestamp; native projectile creation, successful launches and hits remain unimplemented.

gdl_tools world-matrix MATRIX_REQUESTS.json NEW_REPORT.json evaluates the bounded source-order world-matrix experiment. Stock debugger input/output capture uses tools/python/reference_world_matrix.py; inspected entry/return screenshots are required. See world transform research for the controlled-input distinction and current comparison limits.

anim-samples/anim-transforms requests can optionally include "transition":{"from":[nine prior channels],"fraction":F,"mirror":false}. The pose comparator supplies these observed values for nonzero reference blends. Recorded walk-release blending now matches every local matrix/scale output; this still does not predict actions or establish complete event timing.

Ordinary logical motion-intent/run-delay timer research can be reproduced with:

target/release/gdl_tools motion-code MOTION_REQUESTS.json NEW_REPORT.json
python3 tools/python/compare_motion_code.py --trace MOTION_TRACE.json --out private/reports/NEW_MOTION_COMPARISON

This bounded helper takes original logical controls and prior player context. It predicts stored motion code and timer; native pad polling, requested-action mapping, displacement and collision remain unimplemented. See clock/input evidence for bounds and repeated comparisons.

PlayerMotion's ordinary pre-collision displacement request and facing turn, using native reconstructions of the executable's own atan2f/sinf/cosf, can be reproduced from a raw --movement reference trace:

python3 tools/python/reference_trace.py --schedule SCHEDULE.json --movement --out private/reports/NEW_TRACE.json
python3 tools/python/compare_motion_request.py --trace private/reports/NEW_TRACE.json --out private/reports/NEW_REQUEST_COMPARISON

The request is the value stored before collision stages; it is not native movement. See movement evidence.

Interim playtest

An interim native walk-around (not the M12 slice) runs the Yellow Sorceress in The Poison Fields with original assets and the native, reference-compared movement and collision code:

python3 tools/python/export_start_state.py   # once; private start state from the save
python3 tools/python/run_play.py             # writes private/reports/play-config.json, runs gdl_play with it

Keyboard (player 1): WASD/arrows move, Space/K attack, E/L magic, Shift/I turbo (closes scrolls), Esc or Enter the pause menu (in the Tower: Settings, Manage Character → Save Character, Shop, Inventory, Quit Game). Player 2: TFGH, R attack, U start; gamepads by their buttons. target/release/gdl_play alone needs the config path: target/release/gdl_play private/reports/play-config.json from the repository root (run_play.py --config-only rewrites the config without starting the game).

Native settings (not part of the original game): Options → Display (on the title, or Settings → Display in the pause menu) or F10 opens the settings overlay — widescreen view, motion blending, VSync, frame cap, frames queued, fullscreen, anti-aliasing, reduced flashes, the frame-rate counter, "Original presentation" and player 1's key bindings; keyboard or controller (d-pad, A changes, B closes); the game waits while it is open. F11 toggles fullscreen and F3 the frame-rate counter. Settings are stored in settings.json beside the saves; a texture_pack directory there replaces textures (see enhancements). Options → Screen is the original Screen Adjust (moves the picture, as for a TV). Back on "Press Start" (Escape, Backspace, a controller's Y/triangle) quits; Back on the title menu returns to "Press Start".

See playtest notes for exactly what is native and what is interim.

The current checkpoint records exact progress, passing checks, preserved reference state and ordered next steps.

Release packages and the installer (M21)

bash tools/package.sh linux private/dist builds a package: the Qt 6 installer (installer/) and payload/ (gdl_play, gdl_import, the shipped reference files in release/import/, licenses, release/README.txt and KNOWN_ISSUES.txt). The installer copies the payload into a folder in the user's home and imports the game from the user's disc, an image or a folder with gdl_import (crates/gdl_install); an installed gdl_play needs no argument. Without the installer:

target/release/gdl_import probe 'Gauntlet - Dark Legacy.iso' --reference release/import
target/release/gdl_import install 'Gauntlet - Dark Legacy.iso' INSTALL_DIR --reference release/import
INSTALL_DIR/gdl_play   # after copying target/release/gdl_play into INSTALL_DIR

See decision 0005 and release research. The Linux package is built in an Ubuntu 20.04 container (tools/linux/); the Windows package's installer is built on a Windows machine with Qt's MinGW kit, over SSH (GDL_WINDOWS_HOST=HOST bash tools/package.sh windows private/dist) or beforehand (WIN_INSTALLER_DIR; docs/toolchain.md).

License

Copyright (c) 2026 Gauntlet native reconstruction contributors. The project's code is licensed under the GNU General Public License, version 3 or (at your option) any later version (GPL-3.0-or-later; LICENSE, decision 0004). Third-party code and its notices are listed in THIRD_PARTY.md. Retail game files and BIOS data are not part of the project and are not covered by its license.