Features and Roadmap

Features and Roadmap

A summary of docs/ROADMAP.md, which is the authority on the phase structure and gates. The three headline deliverables — smarter AI, real lighting, NIGHTWATCH — are goals; what ships today is described under Current status.

Scope decision: the full game

Full-game scope — all campaign levels, all multiplayer maps — is the stated goal, and it shapes every phase in one specific way:

Nothing may be hand-authored per level.

Twenty campaign levels plus MP maps means any manual step gets multiplied by twenty-plus and becomes the critical path. Every per-level artifact — lights, normals, spawn points, guard tables, camera graphs — must be derived automatically from existing level data, with a small hand-tuned override file for the cases the deriver gets wrong. An override file that exceeds about 30 lines means the deriver is wrong and should be fixed instead.

Milestone: Vertical Slice (Facility)

The demo target: get one level through the whole pipeline end to end, then run the rest through the same tools in batch. Contents: Facility at 1080p/60 with derived lighting and shadow-casting muzzle flashes; the full AI overhaul active; Nightwatch playable at 1v3; original assets, correctly rendered.

The slice is not judged on how good Facility looks but on whether the tooling generalizes: Facility required zero hand-placed lights; a second level runs through the untouched derivers to acceptable quality in under a day; Nightwatch's tables for both levels were derived, not authored; all Phase 0 traces still pass. Hand-tuning Facility until it is beautiful is the failure mode to avoid.

Phases

Phase 0 — The oracle (complete)

Leaving the matching build means losing the ability to prove correctness by comparing assembly, so the replacement had to exist before the divergence: a deterministic replay harness on the matching build, recorded input streams for every campaign level, per-tick state hashes (positions, health, weapons, RNG cursor, alarm and objective flags, animation frames), and a diff that reports the first divergent tick and which fields differ.

Gate: every campaign level replays byte-identically across 10 consecutive runs on the matching build. Met.

Phase 1 — Excise the RCP (open)

Cut cleanly between what to draw and how to draw it. Keep the room graph, portal culling, visibility determination, LOD selection and object culling; move display-list construction, TMEM tile loading, cartridge DMA and VI configuration behind a gfx_ interface. Also in this phase: byte-swap assets at build time rather than at run time, and convert raw-pointer entity references into stable handles (which networking and save compatibility both depend on). Explicitly not in this phase: codebase-wide fixed-point → float conversion and general beautification.

Gate: all Phase 0 traces still pass, and the game renders through a null/software gfx_ backend at parity with the matching build.

The plan of record for this phase is docs/decisions/phase1-tracks.md, which defines the tracks:

• T1 — slgfx IR: a typed command stream, tagged with provenance (room, prop, character), replacing display-list emission.
• T2 — render oracle: a vendored reference renderer driven by the replay harness, so framebuffers can be diffed the way make matching diffs bytes.
• T3 — libultra to zero: per-subsystem conversion of src/game to sl_ platform interfaces, shrinking the layering baseline monotonically to zero.
• T4 — byte-swap at extraction: build-time conversion in the extractor.
• T5 — pointer → handle: per subsystem, starting with character and prop cross-references.
• T6 — audio: native audio output for the sim.
• T7 — platform shell: the SDL window, input and timing for the native build, including mouse look and modern bindings.

Phase 2 — Decouple sim from render

A fixed 60 Hz simulation tick, inputs entering as command structs, and a renderer that interpolates between ticks. This one refactor is the prerequisite for both high-framerate rendering and networking. It is also where bit-exact parity with the original hardware ends: the original is welded to a vsync-locked tick with frame-budget hacks, so trace comparison after this phase validates behavioural equivalence at tick boundaries, with the harness updated and the new baseline documented.

Gate: traces pass under the tick-boundary comparison mode; frame rate uncapped and decoupled; gameplay speed unchanged at 30, 60, 144 and 240 fps.

Phase 3 — Lighting and rendering

The core insight: N64 vertex colours are baked lighting, not vertex paint. Retain them as the ambient/indirect term and multiply dynamic lights on top, so Rare's art direction becomes free global illumination across twenty levels without twenty lighting passes. Clustered forward rendering, not deferred. Required: alpha-to-coverage, muzzle flashes as shadow-casting lights, automated normal generation, automated light derivation from emissive surfaces and vertex-colour analysis, the portal structure reused for light clustering, and a 32-bit framebuffer. Fog and the original filtering and dithering are preserved as art options. Texture upscaling comes last, after the renderer is stable — and it ranks last on merit, not just sequencing.

Gate: all levels render at 1080p/60 with derived lighting and no per-level manual light placement beyond override files; visual regression screenshots captured per level.

Phase 4 — Netcode

There is no netcode to modernize; the original is splitscreen. The architecture is authoritative client-server with snapshot interpolation, not rollback. Required: server-side lag compensation on hit traces (the game is hitscan with instant headshot kills), entity replication on the Phase 1 handle system, client prediction for local movement only, and a dedicated headless server build. Spawn candidates for eight players are derived from navmesh coverage and line-of-sight analysis, then curated.

Gate: 8 players, all MP maps, sustained 60 Hz server tick, playable at 100 ms RTT.

Phase 5 — NIGHTWATCH

One infiltrator running a campaign objective; up to seven human players as security, respawning into available guards. The design core is the alarm information graph: guards know only what has been communicated to them, through shouting range, radios, alarm panels and monitored cameras, and the infiltrator's counterplay is severing that network. The same system makes single-player stealth better, so it pays for itself twice. Balance is prototyped at 1v3 before tuning for 1v7. Guard respawn tables, objective clocks and the camera/alarm node graph are all derived from existing level data.

Gate: campaign levels playable as Nightwatch with derived tables and no per-level scripting.

Parallel track — AI overhaul

Not gated on any of the phases. Guard behaviour is pure game logic that runs on the matching build, touches nothing being deleted in Phase 1, and merges cleanly later. Work: squad communication and knowledge propagation (the single-player form of the alarm graph); Perfect Dark simulant behaviour archetypes reimplemented by design against Sightline's own AI interface — never a code merge, since PD's structures diverged too far; search patterns, investigation of bodies and noise, flanking, suppression. This track can ship independently as a standalone AI overhaul on the matching build.

Explicitly out of scope

• Bug-fixing as a goal. The decomp's bugs are Rare's bugs, faithfully reproduced. Fix only crashes, AI stalls and softlocks, and anything blocking a phase; any other intentional change goes behind a toggle. See Original Behaviour and Toggles.
• Codebase-wide cleanup and beautification.
• RCP emulation or static-recompilation approaches.
• Merging Perfect Dark source.
• Shipping any original or derived asset, including AI-upscaled textures.
• Replacing all assets with originals (the Freedoom approach) — a multi-year art project that must not creep in.

Current status

• Phase 0 is complete. All 20 campaign levels replay byte-identically across 10 consecutive runs of the trace harness.
• Phase 1 is open, on the tracks listed above.
• The parallel AI track runs against the matching build.
• The native Windows build boots the retail game data through the cartridge's own front end and plays the full single-player campaign.
• v0.2.0 shipped QoL Phase 1 on the native build — the first release with a downloadable Windows binary: semantic controls with persistent remapping, controller layouts and models, mouse and controller sensitivity, hold / toggle crouch and sprint, widescreen aspect ratios and FOV, resolution and window modes, native settings pages and QUIT GAME. See Releases. This is Phase 1's platform-shell track (T7: the SDL window, input and timing, mouselook and modern bindings) made playable; the phase structure and gates above are unchanged.
• v0.3.0 shipped Visual Fidelity on the native build: the PRESENTATION setting (ORIGINAL, the Community HD texture pack, or the XBLA remaster's textures and world assets prepared from user-supplied sources), WORLD DETAIL, and FRAME RATE above the game's own rate with a SHOW FPS counter. See Releases. All of it is a choice of what is drawn over the game's own simulation, made within Phase 1. It is not Phase 2's sim/render decoupling — extra frames re-draw a finished game frame with a blended camera, and the game still ticks at its own rate — and not Phase 3's derived lighting, which remains a goal.

Progress is tracked on the project board.