slaterain/nv-rs

A from-scratch reimplementation of Fallout: New Vegas in Rust with the Bevy engine. It runs the game from the Data folder of an installation you own and aims to behave exactly like the original (1:1).

• Original files at runtime. nv-rs reads the game's own plugins, archives, meshes, textures, sounds, menus and shaders directly. There is no conversion step, and the installation is never modified. The game's executable is read too (version 1.4.0.525 only; any other build is refused at start-up with the reason), for the constants and tables of the translated code.
• Behaviour from the original program. Rules, constants and formulas come from the game's program (FalloutNV.exe, read in Ghidra), its data, and recordings of the original game. Nothing is invented or tuned by eye. The method is described in docs/METHODOLOGY.md and the decisions behind it in docs/adr/.
• Ported system by system. Every function in FalloutNV.exe is mapped and tracked in a ledger (docs/LEDGER.md). The game's code is being translated into Rust function by function in the engine crate, each piece marked with the address it came from and tested, in the order that matters most for running the game. The plan is in docs/ENGINE_PORT_PLAN.md.
• Checked against the original. Tools in research/ record what the original program actually does (function results on the real CPU, live arguments and state) so that Rust code can be tested against it.
• Simulation separate from presentation. Game rules live in plain Rust crates with no external libraries. The Bevy app only draws, plays sound and reads input. That split also keeps the planned VR support possible (docs/VR.md).

nv-rs/
├── Cargo.toml         # core workspace (no external crates)
├── crates/            # readers, game rules, tools and test fixtures (table below)
├── viewer/            # the Bevy app (its own workspace, Bevy 0.16)
├── research/          # Ghidra scripts, the engine map and native oracle tools
│   ├── ghidra/        # identity, complete export, function cards, name import
│   ├── engine-map/    # every function of the exe, by unit and subsystem
│   └── nv-oracle/     # nv-call, nv-probe, nv-inject (own workspace, 32-bit Windows)
├── docs/              # roadmap, method, decisions, ledger, topic findings
├── scripts/           # acceptance routes, the ledger, packaging
└── distribution/      # files shipped in playtest packages

The main work right now. Progress is measured in the ledger (docs/LEDGER.md).

• Phase 0: the map and the ledger. Every function in the exe has a unit, a subsystem and a status.
• Translation (ongoing): over 10,000 of the exe's functions are translated so far (about 15% of the whole program; counting only game code, about 35% is translated or traced). Most are not yet switched on in play.
• Phase 1: the frame skeleton (nearly done): the game's per-frame order, from the main loop down, drives the order of the app's systems (docs/FRAME_SKELETON.md).
• Phase 2: the state model and saves: the game's state lives in the translated code's memory, checked by reading a real save and writing it back identically.
• Phase 3 onward: whole systems switched over one at a time: the script engine, conditions, AI, animation, menus, the rest of Havok and audio.

Each milestone has an acceptance gate checked against the original game. Status and evidence are in docs/MILESTONES.md.

• M1: Opening and persistent world (active): the opening movie and wakeup, Doc Mitchell's character creation, leaving for Goodsprings, and saving and reloading with all state intact.
• M2: Core gameplay loop (active alongside M1): Sunny's tutorial and a Goodsprings quest branch: movement, weapons, damage, AI, dialogue, loot, trade, progression and V.A.T.S.
• M3: Base-game systems and campaign: coverage of quests, creatures, weapons, effects, factions, companions, travel and menus, up to campaign completion.
• M4: Stability and performance: long play without crashes or lost state, with measured frame times and streaming.
• M5: DLC and mods: official DLC and documented plugin, archive and script-extension behaviour.
• M6: VR: shared simulation with independent aim and views, tested on a headset.

What plays today (October 2026): Doc Mitchell's house and his walk to the door, Goodsprings with its people going about their routines, and two Goodsprings quests driven by their own scripts: Back in the Saddle (Sunny's tutorial) and Ghost Town Gunfight. Along the way: NPC combat, animation and navigation, dialogue, barter, the Pip-Boy, radio, physics and ragdolls, terminals and hacking; crafting, Caravan and parts of Dead Money are in but mostly checked by tests so far. These three routes are replayed automatically on every change (scripts/acceptance.ps1). Much of this was built before the engine port and will be replaced, system by system, by the translated code.

What it isn't yet: a complete playthrough. Parts of the routes are still driven by console lines, the face editor isn't built, and nothing has been compared side by side with the original game across a whole route. Native NVSE plugin DLLs are not supported, original-game saves can't be loaded, and VR and performance targets have not been validated. The open work is in docs/TASKS.md.

Download a Windows x64 ZIP from Releases, extract it, and run Play.cmd. Point it at your own Fallout New Vegas\Data folder. Read docs/PLAYTESTING.md first.

Install stable Rust, then:

# Core workspace: readers, game rules, nvinspect
cargo build --release
cargo test --workspace

# The Bevy app (separate workspace)
cd viewer
cargo run --release -- "<path to Fallout New Vegas\Data>" GSDocMitchellHouse

The core crates and their tests need no game files. Running the viewer and nvinspect on real assets needs your Data folder. To replay the acceptance routes (Windows, PowerShell):

powershell -File scripts\acceptance.ps1 -Data "<path to Fallout New Vegas\Data>" -Build

Windows is the tested platform. Native Linux and macOS (Metal) support are in open pull requests.

nv-rs is maintained by slaterain and welcomes contributors (and their AI agents). The way in:

1. Read CONTRIBUTING.md and AGENTS.md, and give both to your agent.
2. Claim a task: the major systems in docs/TASKS.md are GitHub issues titled [task] …; comment Claiming this before you start.
3. Work in a fork on a topic branch from the latest main, and open a small pull request against main that passes the checks and the acceptance routes.

Where help matters most now: with the game's own code being ported system by system, hand-written gameplay logic (quest scripts, AI, combat rules, menus) will be replaced as the translated systems come online. The most useful contributions are platform support, acceptance routes and playthrough tests, research into how the original behaves, tools, and bug reports from test builds, especially anything that behaves differently from the original game.

Already have work in a fork? Sync your fork first, then follow "Already working in a fork?" to get your work claimed, rebased and into a pull request.

Final decisions rest with the maintainer (docs/GOVERNANCE.md).

Original code is dual-licensed under MIT or Apache-2.0, at your option. The licence covers only original work. Fallout and Fallout: New Vegas are trademarks of their respective owners. Read LEGAL.md for the full notice, including how material learned from the game's program is handled.