| # Validation, milestones, decisions, and completion gates |
|
|
| The stages below are dependency gates rather than calendar estimates. One playable slice proves integration; it does not reduce the requested all-content/all-game scope. Use task IDs in the linked TODO documents to form implementation issues once the relevant research evidence exists. |
|
|
| ## Routine validation |
|
|
| Use the [Rust cargo xtask runner](TESTING.md) for affected report regeneration and dependency-selected tests before each task commit. Run `cargo xtask test-full --since <batch-base>` before pushing a batch. This replaces repeating the entire Python suite after every small task; platform/runtime milestone checks below remain separate. |
|
|
| ## Dependency order |
|
|
| ```mermaid |
| flowchart TD |
| A[Reference identity and all-file inventory] --> B[Original execution and evidence harness] |
| A --> C[VFS and original format specifications] |
| A --> D[Bevy and Solari hardware proof] |
| B --> E[Native and QVM ABI, rules and traces] |
| C --> F[Versioned conversion pipeline] |
| E --> G[Shared simulation and headless server] |
| F --> H[Bevy world, animation, audio and UI] |
| D --> I[Complete Solari material and rendering port] |
| H --> I |
| E --> J[Network and demo specification] |
| G --> K[Prediction, multiplayer and compatibility] |
| J --> K |
| G --> L[All modes, entities, gear and bots] |
| K --> M[Full content and platform conformance] |
| L --> M |
| I --> M |
| F --> M |
| M --> N[Packaging, documentation and release] |
| ``` |
|
|
| Every subsystem also loops through specification → fixtures → implementation → comparison → corrected findings. Early evidence can change architecture; keep those changes recorded and rerun affected tests. |
|
|
| ## Milestones and exit criteria |
|
|
| | Gate | Required outputs | Exit evidence | |
| | --- | --- | --- | |
| | M0: Research baseline | Reusable inventory, all-file/member coverage register, pinned reference, research setup, rights/source/service registers | Inputs reproduce the static inventory; every item has an analysis task; reference client/server can be observed or an alternative execution environment is established. | |
| | M1: Platform feasibility | Pinned Bevy/Solari candidate and macOS/Linux prototype results, hardware/denoising/material/animation decisions | Actual representative machines render the test scene and imported/animated test content; blockers and required renderer extensions have a plan. Raster-only results do not pass the Solari requirement. | |
| | M2: Engine and content contracts | VFS, formats, native/library responsibilities, QVM decoder/ABI, units, schemas | Candidate resolution matches controlled reference tests; every format has a parser/analysis plan; QVM instructions and required syscalls are mapped sufficiently for tested slices. | |
| | M3: Complete initial asset pipeline | Unpacking and batch conversion, audit, dependency graph, reports | All archive variants can be inspected; required selected content converts with tracked gaps; known Paris and FRF1 overrides are resolved correctly. | |
| | M4: Movement/world slice | One representative map and jump fixture, collision, movement, client camera, headless simulation | Golden movement/collision traces pass; stairs/walls/ladders/water/movers and frame-rate independence have evidence; map reload cleans up. | |
| | M5: Combat/network slice | One complete firearm, melee/projectile examples, damage/health, Rust client/server, prediction | Two native-platform clients complete a controlled match; weapon/hit/damage traces and impaired-network tests pass. | |
| | M6: Complete rules and interactive world | All weapons/gear, 47 observed entity classes plus discovered supported classes, all 11 modes/modifiers, match/admin behavior | Every required rule/state transition has evidence and tests, including simultaneous/timer/disconnect edge cases. | |
| | M7: Full presentation port | Every shader's mapping, models/animation/attachments, Solari and legacy comparison rendering, audio, video, fonts/UI/HUD | Full material/effect coverage reports; tested raytraced animation and denoising; no silently omitted original rendering behavior. | |
| | M8: Bots, demos, services, compatibility | Navigation/bots, recording/playback, discovery/download/auth strategy, original compatibility decision/implementation | Per-map bot tests and controlled demos pass; required compatibility directions work; external-service behavior/failures documented. | |
| | M9: Exhaustive analysis/content coverage | Every installation file and member variant analysed, all maps/assets validated, handbook complete | All-file analysis matrix has no unaccounted rows; unused/obsolete/overridden content documented; required runtime assets have no unresolved blocker. | |
| | M10: Cross-platform release qualification | Native packages, CI/conformance, GPU performance reports, long-run/network/parser robustness, installation docs | Full declared macOS/Linux and GPU matrix passes; minimum hardware/OS/driver/performance promises have measured evidence. | |
| | M11: Entire-game completion | All required research, runtime, content, Solari, multiplayer, documentation and release deliverables | Goals G1–G9 satisfied; differences explicitly reviewed; no required task hidden behind a fallback or unapproved exclusion. | |
|
|
| M0–M3 are the recommended first work tranche. Investigate platform blockers early while research progresses; do not spend the entire asset conversion effort before proving required rendering behavior. Move through an integrated movement/combat slice before expanding every ruleset, while continuing exhaustive static analysis. |
|
|
| ## Decisions that must be recorded |
|
|
| | Decision | Evidence needed | Resolve before | |
| | --- | --- | --- | |
| | Reference source/fork match and implementation license | Binary/source comparison, bundled licenses, copied-code policy | Reusing upstream implementation | |
| | Asset use/distribution and replacement strategy | Supplied restrictions, contributor credits, permitted media model | Public asset packaging/release | |
| | Rust/Bevy/Solari versions and patches | Exact release/commit capability tests | Renderer interfaces and lockfile | |
| | GPU/OS/CPU matrix, Intel Mac/Linux ARM64 scope | Native runs and measured limits | Public platform promises | |
| | macOS/Linux denoising strategy | Moving-scene image quality and frame cost | Full Solari presentation gate | |
| | Legacy shader/hybrid rendering architecture | Every directive/material family, ray participation | Material schema freeze | |
| | MD3 animation and raytracing geometry strategy | Fidelity, memory, upload and acceleration-structure tests | Model/animation runtime format | |
| | Coordinates, units, collision and numeric behavior | Reference traces and format contracts | Authoritative simulation freeze | |
| | Shared fixed-step simulation and scheduling | Timing measurements and deterministic replay | Prediction/network architecture | |
| | Original-wire compatibility vs new protocol/adapter | Protocol recovery, services, pure checks, executable tests | Multiplayer release scope | |
| | Bot navigation import vs regeneration | AAS semantics, traversal/objective tests | Navigation format freeze | |
| | Official services vs supported replacements | Protocol, permission/access, availability, failure behavior | Online feature contract | |
| | Original defect compatibility vs correction | Trigger, impact, parity need and security implications | Related implementation/test expectations | |
| | Runtime formats and package/schema upgrades | Required fidelity, startup/storage/memory constraints | Converter/runtime package contracts | |
|
|
| These are future engineering decisions to resolve with evidence, not requests for permission to write this plan. Existing user scope includes researching every file and implementing the eventual Rust game; this current deliverable is documentation only. |
|
|
| ## Risks and concrete mitigations |
|
|
| | Risk | Mitigation and closure evidence | |
| | --- | --- | |
| | No complete gameplay source in the cache | QVM decoder, native ABI mapping, instrumented reference oracle, behavior fixtures; track unresolved reachability explicitly. | |
| | Legacy binaries difficult to run | Suitable Linux reference environment and alternate native architectures; record platform failures and retain static analysis paths. | |
| | Wrong asset version/case resolution | Preserve all variants; reproduce runtime VFS; regression cases for Paris and FRF1. | |
| | Solari platform/denoiser/material/animation gaps | Early real-GPU spike, renderer patch/hybrid plan, per-shader mapping, quality/performance acceptance tests. | |
| | MD3 animation data and BLAS cost | Exact-frame representation benchmarks, resource budgets and measured acceleration-structure strategy. | |
| | Modern physics changes movement | Custom reference-compatible traces/controller; differential usercmd replay. | |
| | Network/demo or service compatibility underestimated | Early packet/demo capture and explicit compatibility/service contract; interoperability exit gate. | |
| | Baked art/lightmaps change under Solari | Separate legacy comparison and calibrated Solari profile; no double lighting; readability/image tests. | |
| | Unused/overridden files silently omitted | Every file/member occurrence has an analysis record and audited final disposition. | |
| | Original media redistribution constraints | Per-asset provenance and permission/replacement/user-import distribution decision before release. | |
| | “Almost complete” after one map/mode | Explicit all-mode, all-map, all-shader, all-entity, command/cvar and all-file matrices and M11 closure. | |
|
|
| ## Validation TODO: evidence and conformance harness |
|
|
| - [ ] QA-001 Define fixture IDs, input hashes, environment/cvar/map/mode requirements, outputs, clocks, units, tolerances, and intentional differences. |
| - [ ] QA-002 Implement deterministic usercmd replay, state/event snapshots, golden trace comparison, and useful first-divergence reports. |
| - [ ] QA-003 Implement reference QVM/native function capture where practical and black-box session fixtures where internals remain inaccessible. |
| - [ ] QA-004 Compare integer/enums/IDs/events/packet bytes exactly where the contract requires it; measure float tolerances explicitly by subsystem. |
| - [ ] QA-005 Compare macOS/Linux simulation traces and seeded randomness; investigate scheduler/architecture differences instead of assuming determinism. |
| - [ ] QA-006 Add per-rule coverage linking research findings to converted data, implementation and tests. |
| - [ ] QA-007 Create reproducible captures for all modes/weapon types/objectives/entities and configuration boundaries. |
| - [ ] QA-008 Version fixtures and rebaseline only with documented evidence, preserving changed-reference provenance. |
|
|
| ## Validation TODO: complete folder and content coverage |
|
|
| - [ ] QA-009 Require every one of the 39 initial installation files and all 9,835 member occurrences to have analysis status, findings, dependencies, and disposition. |
| - [ ] QA-010 Require analysis of all executables/libraries/platform resources, embedded payloads, discarded patch versions, auxiliary databases and authoring files. |
| - [ ] QA-011 Detect newly discovered files/payloads and extend the all-file register rather than freezing scope at the initial counts. |
| - [ ] QA-012 Verify every format/variant and every shader directive/combination in the parsed inventory, including unused content and malformed cases. |
| - [ ] QA-013 Require every required asset's transitive dependencies to resolve in the final package with correct VFS selection/case semantics. |
| - [ ] QA-014 Compare source/converted geometry bounds/counts/winding/UVs, animation frames/tag transforms, skin mapping, fonts, and audio metadata. |
| - [ ] QA-015 Audit all image alpha/texture sampling/mipmap behavior and all shader legacy/Solari mappings. |
| - [ ] QA-016 Audit every observed/supported entity class and every active weapon/item/gear ID with evidence and fixtures. |
| - [ ] QA-017 Verify archive/converter/runtime parser negative tests and resource limits, with fuzzing targeted at complex binary/text inputs. |
| - [ ] QA-018 Rebuild bundles twice from clean outputs and compare manifests/hashes; test cache invalidation/version migrations. |
|
|
| ## Validation TODO: gameplay, modes, bots, and administration |
|
|
| - [ ] QA-019 Cover movement on flats/slopes/stairs/corners, wall jumps, ledges/ladders/water/movers, injuries/stamina/gear, and latency/frame-rate variations. |
| - [ ] QA-020 Cover every weapon's firing/reloading/modes/ammo/recoil/spread/scope/animation/audio/attachments and interruption/death cases. |
| - [ ] QA-021 Cover every damage region/armor state, melee/projectile/radius/fall/environment damage, bleeding/healing and friendly/self damage. |
| - [ ] QA-022 Complete scripted matches for all 11 modes and all supported modifiers, including warmup/round/match/intermission/mapcycle transitions. |
| - [ ] QA-023 Cover spawn/respawn/waves/protection/occupied spawns, reconnects/disconnects, spectators/substitutes and match readiness/timeouts/swaps. |
| - [ ] QA-024 Cover simultaneous kill/objective/timer events and every original changelog regression relevant to recovered behavior. |
| - [ ] QA-025 Test every supported command/cvar range/flag/permission/mode restriction, persistence/latching, aliases/macros, and error behavior. |
| - [ ] QA-026 Test rcon/referee/voting/bans/mutes/flood/teamkill/inactivity/log/stat/admin flows and service outage behavior. |
| - [ ] QA-027 Test bot navigation and objective behavior on every map and supported mode, including ladders/jumps/water/movers and stuck recovery. |
| - [ ] QA-028 Run long matches and repeated map changes/restarts to detect state leaks, missing resets, resource accumulation and clock wrap issues. |
|
|
| ## Validation TODO: networking and demos |
|
|
| - [ ] QA-029 Complete codec fixtures for framing/fragmentation/compression/baselines/deltas/usercmds/events/configstrings/content negotiation. |
| - [ ] QA-030 Test Rust client/server on both platforms with cross-platform peers and headless servers. |
| - [ ] QA-031 Test every required original client/server interoperability direction against the pinned reference; include pure/package checks and version rejection. |
| - [ ] QA-032 Test controlled packet loss/reordering/duplication/jitter/high latency/bandwidth limits, reconnect/timeouts, and reliable overflow handling. |
| - [ ] QA-033 Verify prediction/reconciliation/lag compensation and compare event/score/objective outcomes under impaired transport. |
| - [ ] QA-034 Test discovery/browser/favorites/status/download cancel/resume/package reload/auth failure modes without depending solely on public services. |
| - [ ] QA-035 Test original and new demos per the chosen contract, including metadata/version/map requirements, seek/pause/camera/audio and deterministic outcomes. |
| - [ ] QA-036 Test malformed/truncated/oversized network and demo input without crashes, unbounded allocation, or invalid state transitions. |
|
|
| ## Validation TODO: presentation and performance |
|
|
| - [ ] QA-037 Create visual comparison fixtures for each map/material/effect family, model/skin/animation state, UI/HUD layout and camera mode. |
| - [ ] QA-038 Separate structural visual comparisons from intentionally changed Solari illumination, with accepted brightness/visibility tolerances. |
| - [ ] QA-039 Test raytraced animated geometry/attachments, moving shadows/reflections, masked/transparent surfaces, fog/portals and hybrid composition. |
| - [ ] QA-040 Test moving-scene noise, denoising/ghosting, first-person weapons, camera cuts/teleports/respawns, emissive flashes and night vision. |
| - [ ] QA-041 Test every sound family/event/frame/loop, environmental/spatial output, music/radio priority and video synchronization. |
| - [ ] QA-042 Test supported resolutions/DPI/window modes, mouse/text focus, resizing, device hot-plug, X11/Wayland and macOS fullscreen/Retina behavior. |
| - [ ] QA-043 Establish explicit performance budgets on representative hardware: frame percentiles, input latency, server tick cost, bandwidth, CPU/GPU memory and startup/load times. |
| - [ ] QA-044 Measure Solari sample/denoising/BLAS/material/texture costs on largest maps and full matches, including view weapons, bots and effects. |
| - [ ] QA-045 Test headless server memory/CPU/network budgets separately from the graphical client. |
| - [ ] QA-046 Profile cold/warm loads, shader compilation, asset streaming, map reloads, GPU validation warnings and long-session stability. |
| - [ ] QA-047 Publish measured requirements and benchmark methods; the original `com_maxfps 125` setting is context, not an established rewrite performance guarantee. |
|
|
| ## Validation TODO: release and documentation |
|
|
| - [ ] QA-048 Test a clean checkout and user-supplied installation through import/conversion/build/launch without undeclared local dependencies. |
| - [ ] QA-049 Test native packages on clean macOS/Linux environments, including CPU architecture, drivers, shared libraries, permissions and data paths. |
| - [ ] QA-050 Verify first-launch asset/hardware/service diagnostics and graceful unsupported-device/content handling. |
| - [ ] QA-051 Review licenses/attribution/source notices and validate the agreed bundle/user-import/replacement-media policy. |
| - [ ] QA-052 Finish user, developer, research, server, content-authoring, build, installation and troubleshooting guides with working commands. |
| - [ ] QA-053 Publish per-platform/Solari/content/gameplay/interoperability matrices and the list of intentional differences and remaining unsupported optional tiers. |
| - [ ] QA-054 Audit every unchecked task against goals and resolve all required blockers; scope changes require explicit recorded agreement rather than silent omission. |
| - [ ] QA-055 Record final M11 acceptance evidence and release hashes; do not label the entire rewrite complete while required features or file analysis are missing. |
|
|
| ## Per-map completion checklist |
|
|
| Each entry requires analysis of all archived variants, dependencies, materials, geometry/collision/entities/navigation, conversion, native macOS/Linux loading, legacy and Solari presentation, a gameplay pass for every declared/supported compatible mode, and bots where applicable. Preserve unsupported-mode handling and special features in its coverage record. The jump demonstration has its explicit research/example role rather than an assumed full matchmaking role. |
|
|
| - [ ] MAP-001 Complete `ut4_abbey` and every archived variant (initial candidate: `zUrT43_002.pk3`; 93 entity records). |
| - [ ] MAP-002 Complete `ut4_algiers` and every archived variant (initial candidate: `zUrT43_002.pk3`; 156 entity records). |
| - [ ] MAP-003 Complete `ut4_austria` and every archived variant (initial candidate: `zUrT43_002.pk3`; 147 entity records). |
| - [ ] MAP-004 Complete `ut4_bohemia` and every archived variant (initial candidate: `zUrT43_002.pk3`; 377 entity records). |
| - [ ] MAP-005 Complete `ut4_casa` and every archived variant (initial candidate: `zUrT43_002.pk3`; 498 entity records). |
| - [ ] MAP-006 Complete `ut4_cascade` and every archived variant (initial candidate: `zUrT43_002.pk3`; 359 entity records). |
| - [ ] MAP-007 Complete `ut4_docks` and every archived variant (initial candidate: `zUrT43_002.pk3`; 604 entity records). |
| - [ ] MAP-008 Complete `ut4_dressingroom` and every archived variant (initial candidate: `zUrT43_002.pk3`; 83 entity records). |
| - [ ] MAP-009 Complete `ut4_eagle` and every archived variant (initial candidate: `zUrT43_002.pk3`; 359 entity records). |
| - [ ] MAP-010 Complete `ut4_elgin` and every archived variant (initial candidate: `zUrT43_002.pk3`; 532 entity records). |
| - [ ] MAP-011 Complete `ut4_firingrange` and every archived variant (initial candidate: `zUrT43_002.pk3`; 55 entity records). |
| - [ ] MAP-012 Complete `ut4_ghosttown` and every archived variant (initial candidate: `zUrT43_002.pk3`; 242 entity records). |
| - [ ] MAP-013 Complete `ut4_herring` and every archived variant (initial candidate: `zUrT43_002.pk3`; 431 entity records). |
| - [ ] MAP-014 Complete `ut4_jumpents` and every archived variant (initial candidate: `ut4_jumpents.pk3`; 20 entity records; example/timer fixture). |
| - [ ] MAP-015 Complete `ut4_killroom` and every archived variant (initial candidate: `zUrT43_002.pk3`; 25 entity records). |
| - [ ] MAP-016 Complete `ut4_kingdom` and every archived variant (initial candidate: `zUrT43_002.pk3`; 390 entity records). |
| - [ ] MAP-017 Complete `ut4_kingpin` and every archived variant (initial candidate: `zUrT43_002.pk3`; 302 entity records). |
| - [ ] MAP-018 Complete `ut4_mandolin` and every archived variant (initial candidate: `zUrT43_003.pk3`; 483 entity records). |
| - [ ] MAP-019 Complete `ut4_mykonos_a17` and every archived variant (initial candidate: `zUrT43_003.pk3`; 162 entity records). |
| - [ ] MAP-020 Complete `ut4_oildepot` and every archived variant (initial candidate: `zUrT43_003.pk3`; 227 entity records). |
| - [ ] MAP-021 Complete `ut4_paris` and every archived variant (initial candidate: `zUrT43_021.pk3`; 522 entity records). |
| - [ ] MAP-022 Complete `ut4_prague` and every archived variant (initial candidate: `zUrT43_003.pk3`; 268 entity records). |
| - [ ] MAP-023 Complete `ut4_prominence` and every archived variant (initial candidate: `zUrT43_003.pk3`; 135 entity records). |
| - [ ] MAP-024 Complete `ut4_raiders` and every archived variant (initial candidate: `zUrT43_003.pk3`; 319 entity records). |
| - [ ] MAP-025 Complete `ut4_ramelle` and every archived variant (initial candidate: `zUrT43_003.pk3`; 536 entity records). |
| - [ ] MAP-026 Complete `ut4_ricochet` and every archived variant (initial candidate: `zUrT43_003.pk3`; 387 entity records). |
| - [ ] MAP-027 Complete `ut4_riyadh` and every archived variant (initial candidate: `zUrT43_003.pk3`; 212 entity records). |
| - [ ] MAP-028 Complete `ut4_sanc` and every archived variant (initial candidate: `zUrT43_003.pk3`; 404 entity records). |
| - [ ] MAP-029 Complete `ut4_suburbs` and every archived variant (initial candidate: `zUrT43_003.pk3`; 664 entity records). |
| - [ ] MAP-030 Complete `ut4_subway` and every archived variant (initial candidate: `zUrT43_003.pk3`; 327 entity records). |
| - [ ] MAP-031 Complete `ut4_swim` and every archived variant (initial candidate: `zUrT43_003.pk3`; 538 entity records). |
| - [ ] MAP-032 Complete `ut4_thingley` and every archived variant (initial candidate: `zUrT43_004.pk3`; 416 entity records). |
| - [ ] MAP-033 Complete `ut4_tombs` and every archived variant (initial candidate: `zUrT43_004.pk3`; 668 entity records). |
| - [ ] MAP-034 Complete `ut4_turnpike` and every archived variant (initial candidate: `zUrT43_004.pk3`; 248 entity records). |
| - [ ] MAP-035 Complete `ut4_uptown` and every archived variant (initial candidate: `zUrT43_004.pk3`; 647 entity records). |
|
|
| ## Tracking completeness |
|
|
| Track separately: **analysed file/member occurrences**, **specified/recovered behaviors**, **converted content**, **implemented features**, and **passed conformance fixtures**. These percentages have different denominators and cannot substitute for one another. Report blockers by goal and milestone. Initial static inspection is evidence for inventory/headers; it is not a completion mark for any full subsystem. |
|
|
