Need help getting started? Try the player guide. These notes include older work; the game overview explains what’s ready now.

Development reference and research archive

These are detailed notes from the port’s development, including earlier milestones. For the current download, European ROM requirement, controls and setup, start with the player README. Older counts and limitations below describe the work at the time; they are not a current release checklist.

Windows x64 prerelease: download v0.8.0-beta.1. Extract the ZIP to a writable folder, put your own ROM at orig/SSA.gba, and run play-native.cmd. The package includes the native executable; no build tools are needed. ROMs and SoundFont banks are not included. See the release notes for features and known limitations.

Project website, features and roadmap · 3D level browser

Build from a fresh checkout

Install Visual Studio 2022 Build Tools with the C++ desktop workload and CMake tools. Clone this repository, open PowerShell in its folder, and run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-windows.ps1

Compilation does not require a ROM. To play, place your own game ROM at orig/SSA.gba, then run play-native.cmd. The launcher uses build/native-windows/Release/ssa_native_game.exe; build it first. All twelve campaign levels are enabled, including Caesar's Palace. Campaign playthrough validation is manual at the user's request.

Options lists Settings, Graphics, Extras, Clear Data, then Credits. Settings contains Language, Mouse sensitivity, Field of view, Music style, Music volume and Sounds volume. Graphics groups Display mode, Renderer, Aspect ratio and VSync; filtering/postprocessing; then scene details. Vulkan is preferred with Software fallback; GBA retains its original projection. VSync defaults On when available, and existing v22 choices are preserved. The Vulkan-only AA, sharp anisotropic filtering, world-texel AO and camera motion blur default Off.

Extras contains HUD, Vertical aim, Third-person, Jump, Automap, In-game NETRICSA, Enhanced weapons and Weapon bobbing. HUD defaults to Original. Jump, Automap, Enhanced weapons and Weapon bobbing default Off; Third-person, in-game NETRICSA and vertical aim default On. Saved choices win. Press F11 for fullscreen/windowed mode, M for the enabled automap, and R to reload enhanced Colts. With Enhanced weapons On, a new campaign starts with one Colt; picking up another unlocks and equips dual Colts. Each Colt fires every 0.45 seconds; duals alternate hands at 0.225 seconds. A click fires two alternating shots even when released quickly; holding fire continues the sequence. Each holds six shots with unlimited reserve ammo. Reload starts when the next gun's turn finds it empty, allowing 12 alternating shots from full duals. The right Colt reloads first, with the left starting 0.33 seconds later: 1.07 seconds per gun, 1.40 seconds for the complete pair. Single Colts reload alone after six shots. Each reload plays a local mechanical click. Re-equipping a Colt refills its six-shot magazine; switching from single to dual refills only the left gun that is drawn. These timing and magazine rules apply only with Enhanced weapons On. That mode also gives the double shotgun a fixed 14-pellet pattern, with 5 base damage per pellet (70 for a full hit), horizontal spread up to ±6.84° and vertical rows at +2.58°, +0.86°, −0.86° and −2.58°. It follows free aim and GBA auto-aim. The alternate double shotgun fires every 1.75 seconds, with its animation frames spread evenly across that cycle. Colts retain key 2: press it again to toggle single/dual once acquired. Mouse-wheel order puts single immediately before dual. Switching variants draws/stores only the left Colt. Password/level-select starts after the first level upgrade starting Colts to duals in this mode. Disabling in-game NETRICSA blocks Tab/N during gameplay; pre-level briefings still appear. Disabling Third-person returns to first-person and disables the H view toggle. GBA rendering keeps the camera level and moves the original crosshair vertically with auto-aim without following camera bob. Third-person cursor placement accounts for the raised camera. Use Left/Right or click a bar; preferences persist in settings.dat. For the optional SC-55 music style, run powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install-soundfont.ps1. You can load another GM bank with play-native.cmd --soundfont "path\bank.sf2". SoundFont is offered only when that file exists and loads successfully. MIDI uses Microsoft GS Wavetable Synth and needs no SF2 file; it is offered when Windows can open that device. Missing saved modes fall back to Original. MIDI mode compensates for the GS synth's measured delay by buffering only the original music samples for 185 ms. Sound effects stay immediate. For a different audio device, override with play-native.cmd --midi-delay 0..500 (milliseconds). SoundFont mode retains the ROM's sampled instruments and replaces only PSG instruments. Its music uses the volume slider without Original-mode fixed boosts/cuts; a 15 dB SoundFont trim balances it against the retained samples, then a shared +3 dB gain raises the whole mix. Final output gains raise both music modes to full peaks (Original +9.54 dB, SoundFont +6.02 dB), with peak protection to prevent overload. See audio settings and checks.

The repository includes native source, Windows frontend, tests, scripts, research, recovered C and the complete static website. ROMs, saves, generated assembly, toolchains, dependency checkouts and local server databases stay local. See preserved recovery sources for the exact C export and sanitized candidate/attempt/note history. GitHub Pages publishes only site/; source additions do not change its URL.

Optional original-ROM timing tests use a pinned test-only mGBA checkout:

git clone https://github.com/mgba-emu/mgba tools/mgba-timing
git -C tools/mgba-timing checkout --detach 26b7884bc25a5933960f3cdcd98bac1ae14d42e2

The native game does not link against mGBA. Decompilation tooling is provisioned separately by scripts/bootstrap.sh under WSL/Ubuntu; see the setup below.

Current prototype

All twelve campaign levels are available natively on Windows. Run play-native.cmd to use your supplied orig/SSA.gba. This build includes actual enemy AI, weapon firing, damage/death, pickups, scripted waves, doors, the exit, and restart, with the original world, actors, HUD and weapon graphics. New Game includes the original Egypt intro; entering Rome shows its chapter panel. After the final level's bonus tally, the ending returns to Main. Up/W pauses the story, Down/S scrolls faster, Right skips a hold, and Enter/Space/Esc or a click skips the screen. Preview the ending directly with play-native.cmd --story 12. See campaign screens. Rome maps use the original golden ankh pickup, including its full and distant sprites decoded from the ROM. Time Strike targets now keep a valid rendered frame if their controller changes animation while frozen, preventing a reference-renderer failure during combat. Health, armor and boss bars now use the original scanline palette colors, including the original health-above100 variation. Player collision now detects large enemies before Sam enters their bodies. If a scripted spawn already overlaps Sam, movement away can free him while walls and other enemies still block him. Startup goes straight to the title screen. Options includes a Language row: Enter, click or Right cycles English/German/French; Left cycles backward. Language and beaten levels persist in save.dat beside this launcher. Single Player has New Game, Select Level, Password. Level 1 is always unlocked; beating a level unlocks its successor on any difficulty. Select Level uses the original localized campaign names, shows locked levels with padlocks, and omits multiplayer maps. Egypt and Rome each have a page of six levels, shown without number prefixes. Use Up/Down to select a level or Left/Right/the arrows to switch chapters. Caesar's Palace unlocks when Praetorian Fort is beaten, using the existing save. Selected levels use their original starting weapons and ammo after choosing difficulty. Options → Clear Data resets progress and language after a Yes/No warning; No is selected by default, and Esc cancels. New Game keeps existing unlocks. See saved data and level selection. The original background grid appears from the first title/main-menu visit. Choose Single Player, New Game and a difficulty to begin. Use arrows or WASD, Enter/Space to confirm, or hover and click a menu entry. Esc goes back. Mouse selection plays the original cycling sound only when the highlighted item changes. The title music continues after Press Start without restarting. Options → Credits now shows the original scrolling credits. Hold Up/W to pause or Down/S to speed up; Enter/Space/click or Esc returns to Options. Single Player → Password now restores original starting weapons and ammunition for all twelve campaign maps. Type the password directly (case-insensitive), with or without its trailing underscore placeholders; use Backspace/Delete to correct it, and Enter or a click to submit. Left/Right moves the cursor; Up/Down retains the original character cycling. Esc goes back. Passwords select difficulty too. Fresh --level launches use that map's original starting weapons and ammo. Advancing from a previous level keeps your carried weapons and ammunition. Original ROM sound effects and level music now play through a native audio mixer. Pickup names, boss introductions and death messages now use the original localized sprite lettering, reveal and expiry timing in both renderers. See original HUD notices. NETRICSA appears before the map view on every level start/restart, with its original animated background. During gameplay, press N or Tab to open it as an overlay over the paused game, without that animated background. Tab toggles it on/off during play; Esc or N also returns. It includes original localized weapon/enemy records, illustrations, strategic/tactical briefings and live statistics. Enter/Space cycles panel focus; Up/Down selects categories or scrolls text; Left/Right cycles records. Hover/click categories and panels, wheel to scroll, or click either half of an illustration to cycle records. The overlay preserves the current renderer's resolution. Click numbered weapon/enemy indicators above the text panel to view a record; unavailable records are dimmed and the current selection is highlighted. During play, NETRICSA fades in/out over250ms, removing the HUD while keeping the weapon visible and darkening the level with a green tint. Before map view, NETRICSA keeps the original fade speed; Tab closes it and proceeds to map view. See NETRICSA recovery and controls. The overall soundtrack plays at50% of its previous amplitude so effects stand out. Audio buffers refill on device events, keeping music at normal speed when the mouse and UI are idle. Footsteps follow grounded movement in both views without interrupting the music. Tommy gun fires about 8.53 times per second. Chainsaw uses the measured original GBA average of about 8.69 attacks per second, with increased 192-unit PC reach. The minigun also uses its measured original GBA cadence, about 8.53 rounds per second, with its existing damage per round. Chainsaw bites accumulate damage between attacks so they also hurt enemies on Hard. Special weapons 8 and 9 now fire natively: the area blast and targeted falling effect include their original background-palette flashes. Hurt flashes expire, allowing later hits to play the hurt sound again. Time Strike falls at the measured original GBA update rate and retains original damage, including tougher enemies surviving. Empty space, items, corpses and temporarily protected enemies consume no Time Strike ammo and play no firing sound. These attempts still play the weapon's firing gesture. Falling objects move smoothly between physics updates, preserving their landing and damage timing. Aim, movement and release remain responsive at 60 Hz. Continuous weapon loops stop on release, switching, empty ammo, pause or focus loss; the minigun keeps its wind-down sound. See weapon fixes. Prion gun shots now start on the aim line and fly independently immediately, like the corrected rocket launcher, without following later mouse movement. Cannonballs also fly independently from the instant of launch, so later mouse movement, walking or jumping cannot steer them. Prion-affected enemies run their behavior and animation at twice normal speed. They continually target the nearest living enemy or player, without preferring Sam. Quick fire clicks stay pending until the first shot, even if released during weapon startup, raising or reload. Holding fire keeps the same firing rate. World and enemy sounds pan left/right and fade with three-dimensional distance from Sam. Doors use the same smooth falloff as enemies, getting quieter as you move away even at close range. Pickups play locally like player sounds, without distance attenuation or positional panning. Door loops stop when each door stops; multiple enemies can sound at once, with moving sounds following their own source. The U.M.T. pickup cue finishes after its initial sequence instead of leaving a buzzing loop. The third-person camera keeps the same audio listener as first person. Before every level start/restart, the original map view plays its start music. Click or press Space/Enter to leave the map; it fades to solid black, pauses, then gradually reveals the level with its soundtrack. The weapon is visible from the start of the reveal. Movement, aiming and the live HUD are active during it. Death and level completion select their original music cues. Old effect loops stop on the end screens. Instrument note tails now follow the ROM's echo settings. Music and effects use separate voices, so weapons, enemies and footsteps can play together without cutting off the soundtrack. Player pickups, weapons and hurt sounds take priority over enemy/world effects when sound pools or output headroom fill up. Each music track plays one note at a time; repeated effects can overlap. Sampled instruments and effects receive a 6 dB PC volume boost to improve their balance against PSG channels. World, player and enemy effects receive an additional 50% boost with peak protection. Wave instruments also use the original lower octave and stepped volume conversion. Single-player Sam uses the original white-shirt variant. Enemies slide around one another in crowds and gradually separate overlapping spawns, while keeping walls, doors and the player solid. Gunrilla cannonballs clear their shooter's collision bounds before normal collision with that shooter resumes; walls, players and other enemies still block them.

Mouse look activates automatically during gameplay and when returning to the game. WASD moves, mouse turns, left mouse fires, Space jumps, H toggles first/third person, E uses doors, and 1–0 selects owned weapons. Mouse wheel up selects the previous usable weapon; down selects the next. Cycling wraps around and skips unowned or empty weapons. Q swaps to the last equipped weapon. Weapon changes wait until the current firing/reload animation ends; automatic weapons finish the current animation cycle. Buttons activate immediately on E, without waiting for the weapon to finish lowering. Esc or P opens the pause menu and releases the mouse. Continue resumes; Quit asks Yes/No, with No selected initially, then returns to Main. The separate Quit item at the bottom of Main asks Yes/No before closing the application, with No selected by default. No or Esc returns to Main with Quit selected. Arrows/WASD and Enter/Space, or mouse hover/click, operate it. Esc cancels quit confirmation or resumes gameplay. R is unbound and does not restart the level. Level completion now shows the original localized time/ammo bonus tally and score digits over the frozen level. Click or press Enter/Space to finish the current bonus count immediately, awarding every remaining point. Holding an action still counts faster. The final Sam text stays fully visible for three seconds and waits for completion music; a fresh confirm after one second can shorten the reading hold once music ends. The original sound7 is a short synthesized cue, not recorded speech. Then the next map retains earned weapons, ammo and the bonus-adjusted score, with100 health and no armor. Chapter and ending panels follow the tally. See original campaign entry. The native snapshot path also uses the recovered original weapon-progress capture, with verified per-weapon ownership, signed ammo and shot/hit counters. The original completion-statistics accumulator and checkpoint helpers are also recovered and verified. Completion totals and checkpoints now connect to the frontend's campaign session. High-score/name entry remains unfinished. See statistics recovery. The native backend now also reproduces the original timed time/ammo bonus tally and completion-record ordering. Its frontend presentation now uses the original notice and number sprites; see pause and tally integration. Press M to mute/unmute audio. Use play-native.cmd --no-music for effects only, or play-native.cmd --mute to start silently. Mouse look turns and aims vertically through 80 degrees up or down, with perspective-correct world rendering. The sky stays flat and perpendicular to the view, with horizontal panorama scrolling. At level aim its artwork fills the top three quarters. Looking up or down shifts the image vertically, extending each column's top/bottom edge pixel into exposed space. At level aim, the H camera sits 256 units behind the player with a 64-unit height bias. It orbits with mouse pitch and points along a common sight ray, keeping the original crosshair aligned; walls and ceilings retract the camera. Switching to the chainsaw keeps the same camera angle as ranged weapons. Weapon muzzle flashes are hidden in third-person view and visible in first person. Ranged weapons have no distance cutoff; shots stop at obstructions or the map boundary. Player projectiles continue until impact. Rockets follow their launch direction immediately, independently of later mouse turns or player movement. The chainsaw remains a melee weapon with a 192-unit trace, twice the ROM's 96. The original crosshair artwork and behavior are restored. Rendering now caches static geometry and presents completed frames offscreen to reduce black flicker. If launching fails, the launcher keeps the error visible and saves a separate session log under build/logs/. It also updates build/logs/last-launch.log when available. Multiple game sessions can launch concurrently.

Rendering now follows the window size automatically. Resize/maximize for more world detail, or run play-native.cmd --resolution 3840x2160 for a fixed size. Arbitrary dimensions are supported within memory and platform limits; this renders new world samples. --original-renderer restores the 240×160 reference view. See render settings.

The updated normal-input campaign run completes eleven consecutive maps in 140,712 frames, ending with 1,544,000 total score and 45 health. Weapons and ammo are earned; each next level uses the original 100-health/no-armor construction. It covers pickup-triggered doors, wall switches, elevated enemies, the first boss, Prion conversion, Time Strike and the real exits. GCC ASan/UBSan with leak detection and Windows MSVC agree on every result. Praetorian Fort completes in 17,231 frames with all 99 original enemy spawns, scripted waves, pit hazards and the real exit. Both renderers and the native mixer remain active. The final map separately completes from its original Normal starter loadout in 17,270 frames, including D8 defeat and the scripted exit. These are historical automated results. All twelve maps are now enabled at the user's request, without requiring an automated earned-inventory completion. To jump directly to the last map for manual testing, run play-native.cmd --level 11. See campaign details. Converted enemies can now fire safely after their previous target's actor slot has been cleared or reused, preserving the original slot behavior. See playable build details. Original feature and behavior parity is the completion target, alongside the explicitly requested PC controls and rendering changes. Full campaign playthrough verification, score/name entry and remaining menus/presentation effects are unfinished. Original chapter/ending panels now run natively; see campaign story recovery. Audio fidelity is still being refined; see audio integration. See special weapons and palette recovery for the new integration checks and remaining presentation limits. The native effect runtime now also supports original type-64 wall/sector clipping and relocation; see recovery and checks.

The separate run-native-viewer.cmd [--level 0..15] remains a diagnostic map viewer with idle objects; it is not the playable build.

Use the existing workspace from PowerShell

.\decomp.ps1 status
.\decomp.ps1 rebuild
.\decomp.ps1 test-input
.\decomp.ps1 test-movement
.\decomp.ps1 test-physics
.\decomp.ps1 test-maps
.\decomp.ps1 test-geometry
.\decomp.ps1 test-view
.\decomp.ps1 test-world
.\decomp.ps1 test-slide
.\decomp.ps1 test-horizontal
.\decomp.ps1 test-inventory
.\decomp.ps1 test-pickup
.\decomp.ps1 test-spawn
.\decomp.ps1 test-weapon-select
.\decomp.ps1 test-player-spawn
.\decomp.ps1 test-player-motion
.\decomp.ps1 test-player-frame
.\decomp.ps1 test-player-runtime
.\decomp.ps1 test-player-lifecycle
.\decomp.ps1 test-respawn-select
.\decomp.ps1 test-player-hazards
.\decomp.ps1 test-player-gameplay
.\decomp.ps1 test-sector-movers
.\decomp.ps1 test-switches
.\decomp.ps1 test-level-script
.\decomp.ps1 test-level-runtime
.\decomp.ps1 test-entity-pool
.\decomp.ps1 test-enemy-activation
.\decomp.ps1 test-script-spawn
.\decomp.ps1 test-enemy-motion
.\decomp.ps1 test-enemy-navigation
.\decomp.ps1 test-enemy-lifecycle
.\decomp.ps1 test-enemy-cd
.\decomp.ps1 test-enemy-cd-runtime
.\decomp.ps1 test-enemy-targeting
.\decomp.ps1 test-ray-traversal
.\decomp.ps1 test-ray-intercepts
.\decomp.ps1 test-enemy-ray
.\decomp.ps1 test-enemy-queries
.\decomp.ps1 test-combat-damage
.\decomp.ps1 test-combat-explosion
.\decomp.ps1 test-combat-rewards
.\decomp.ps1 test-combat-combined
.\decomp.ps1 test-combat-runtime
.\decomp.ps1 test-weapon-animation
.\decomp.ps1 test-weapon-controller
.\decomp.ps1 test-weapon-aim
.\decomp.ps1 test-weapon-hit
.\decomp.ps1 test-weapon-runtime
.\decomp.ps1 test-projectile-create
.\decomp.ps1 test-projectile-motion
.\decomp.ps1 test-projectile-controller
.\decomp.ps1 test-projectile-bounce
.\decomp.ps1 test-projectile-effect
.\decomp.ps1 test-projectile-runtime
.\decomp.ps1 test-projectile-conversion
.\decomp.ps1 test-entity-dispatch
.\decomp.ps1 test-entity-runtime
.\decomp.ps1 test-weapon-loadout
.\decomp.ps1 test-weapon-start
.\decomp.ps1 test-frame
.\decomp.ps1 test-sprite-dispatch
.\decomp.ps1 test-actor-animation
.\decomp.ps1 test-actor-animation-runtime
.\decomp.ps1 test-pickup-respawn
.\decomp.ps1 test-pickup-respawn-runtime
.\decomp.ps1 test-game-runtime
.\decomp.ps1 test-input-dispatch
.\decomp.ps1 test-pc-input
.\decomp.ps1 test-sprite-assets
.\decomp.ps1 test-texture-assets
.\decomp.ps1 test-map-texture-bindings
.\decomp.ps1 test-world-raster
.\decomp.ps1 test-raster-fill
.\decomp.ps1 test-mode-control
.\decomp.ps1 test-render-view
.\decomp.ps1 test-plane-renderer
.\decomp.ps1 test-world-visibility
.\decomp.ps1 test-wall-renderer
.\decomp.ps1 test-scene-coverage
.\decomp.ps1 test-world-scene
.\decomp.ps1 test-world-scene-rom
.\decomp.ps1 test-map-actors
.\decomp.ps1 test-actor-assets
.\decomp.ps1 test-actor-projection
.\decomp.ps1 test-actor-queue
.\decomp.ps1 test-actor-scene-rom
.\decomp.ps1 test-actor-scene
.\decomp.ps1 test-sprite-cache
.\decomp.ps1 test-sprite-pool
.\decomp.ps1 test-sprite-oam
.\decomp.ps1 test-display
.\decomp.ps1 test-hud-scene
.\decomp.ps1 test-hud-scene-rom
.\decomp.ps1 test-native-viewer
.\decomp.ps1 test-win32-input
.\decomp.ps1 test-entity-timer
.\decomp.ps1 gui

The GUI command prints the authenticated localhost URL. The analysis database and matched sources are under decomp/serious-sam-3/; the generated rebuild tree is decomp/serious-sam-3/source/. rebuild checks that existing tree.

If PowerShell disables scripts, run a command in a process with a temporary policy override: powershell -NoProfile -ExecutionPolicy Bypass -File .\decomp.ps1 test-geometry.

# Retry remaining machine drafts after improving shared types or discovery:
.\decomp.ps1 autopilot

# Regenerate the source tree from the database (backs up source edits first):
.\decomp.ps1 export

# Agent tools are also callable without modifying global MCP settings:
.\decomp.ps1 tool -ToolName get_function -ToolArgs '{"function":"sub_08003028"}'

Re-running autopilot alone does not solve the remaining reverse engineering. Its drafts, claims, notes and best attempts persist in the database.

Reproduce the setup

Requires Ubuntu in WSL, Git, GCC, and uv. In Ubuntu, from this repository:

bash scripts/bootstrap.sh
.venv-linux/bin/python scripts/decomp.py import --own-copy
.venv-linux/bin/python scripts/decomp.py autopilot
.venv-linux/bin/python scripts/decomp.py export

Place your own ROM at orig/SSA.gba. The ownership flag confirms that copy is legally obtained. ROMs and generated ROM-derived assembly stay out of Git. The importer deliberately uses conservative discovery; broad speculative scans of this ROM proposed thousands of unverified starts in asset data.

Build the portable native libraries under Ubuntu:

.venv-linux/bin/cmake -S . -B build/native
.venv-linux/bin/cmake --build build/native

Build all native Windows libraries with the installed Visual Studio 2022 BuildTools, using its bundled CMake:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-windows.ps1
# Also run the hidden-window input test:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build-windows.ps1 -TestInput

Output is build/native-windows/Release/, including the playable ssa_native_game.exe, static libraries, diagnostic viewer and validation tools.

Source and evidence

The tests use Unicorn to execute isolated original functions as an oracle. Unicorn is a development dependency; the native library contains no emulator.