Goals, scope, and definition of completion
Requested outcome
Reconstruct the complete behavior of the supplied Urban Terror installation, document the findings reproducibly, and implement a Rust replacement using Bevy with a working Solari rendering path on supported macOS and Linux hardware. Include a dedicated server and the scripts/tools needed to transform the original content into usable assets.
The supplied installation identifies itself as ioQ3 1.35 urt 4.3.4. That exact cache snapshot is the initial reference. Later versions, third-party maps, and fixes are separate changes with their own provenance; they must not silently alter the reference specification.
Goals
| Goal | Completion evidence |
|---|---|
| G1: Document the entire game | Engine/module architecture, file formats, rules, commands, configuration, networking, animation, audio, UI, bots, and platform behavior have indexed specifications and evidence. Every discovered subsystem is accounted for. |
| G2: Reproducible content pipeline | A fresh checkout plus a user-provided original installation produces a validated, versioned runtime asset bundle through documented commands. Overrides, original hashes, conversion settings, attribution, and unsupported content are reported. |
| G3: Rust runtime | Client and dedicated server gameplay run in Rust. Original executable/QVM code is useful as a research oracle, not a dependency required by the finished gameplay runtime. |
| G4: Bevy integration | Bevy provides client application/ECS integration, input, windowing, assets, audio integration, UI, and rendering. Shared authoritative simulation also runs headlessly. |
| G5: Solari | A tested Solari path renders converted maps and animated gameplay on the declared macOS and Linux GPU matrix, with measured image quality, latency, and performance. |
| G6: macOS and Linux | Installation, configuration, offline play, LAN/remote play, audio, input, rendering, persistence, and dedicated-server operation pass native platform tests. Declare minimum OS, CPU, GPU, and driver requirements from tests. |
| G7: Gameplay fidelity | Movement, collision, hit detection, weapon timing, health, stamina, objectives, scores, rounds, and team rules match documented reference measurements within explicit tolerances. |
| G8: Complete content and features | All supported modes, active weapons/items, playable supplied maps, players, skins, sounds, menus, bots, administrative functions, demos, and customization have a tested implementation or an explicitly approved disposition. |
| G9: Maintainability | Stable formats, clear crate boundaries, build documentation, provenance, regression fixtures, diagnostics, and continuous integration support future development. |
Meaning of “entire game”
The reverse engineering scope is everything found in the game folder: every standalone file, every archive and every member variant (including overridden versions), game logic, all shaders and rendering behavior, textures, maps, models, animation, sounds, fonts, icons, metadata, documents, authoring files, executables, bundled libraries/DLLs, and embedded resources or code discovered inside them. Inventory coverage is mandatory even for unused or obsolete material. The final runtime scope includes the engine services the game depends on, the server game module (qagame.qvm), client module (cgame.qvm), UI module (ui.qvm), active assets, and all reachable behaviors. A rendered map and a moving player are milestones, not completion.
Include all 11 gametypes listed in gameinfo.txt: Free For All (0), Last Man Standing (1), Team Deathmatch (3), Team Survivor (4), Follow the Leader (5), Capture and Hold (6), Capture the Flag (7), Bomb (8), Jump (9), Freeze Tag (10), and Gun Game (11). Instagib and other rule modifiers require their own coverage. ID 2 is absent from this list; determine its actual handling before defining it.
Include round and match administration, spectators, substitutes, ready/timeout states, votes, chat/radio, scoreboards, loadouts, gear restrictions, bot behavior, map interaction, recording/playback, content installation, configuration, and server operations. Services outside the installation—master servers, account authentication, moderation, downloads, and historical anti-cheat integrations—need documented protocols and a supported dependency or replacement strategy.
Every installation file and archive-member variant receives an analysis record and a disposition: used directly, converted, replaced, unused legacy content, editor/example material, auxiliary attribution, or unsupported with a tracked blocker. A disposition is not permission to omit analysis. Unused files do not automatically become playable features. ut4_jumpents is an entity demonstration map according to its included readme; validate it as a research fixture and document its final availability. Analyse platform-specific executables and bundled libraries even when they are not part of the macOS/Linux replacement; port their required behavior to Rust/Bevy/platform facilities rather than requiring the old binaries.
Fidelity policy
- Preserve measured gameplay and timing before introducing improvements. Retain simulation units and floating-point/quantization behavior where parity depends on them.
- Keep authoritative collision and movement semantics independent of visual mesh simplification and modern rendering.
- Give the renderer two documented visual targets: legacy appearance for comparison and Solari lighting for the requested modern presentation. Changes to scene brightness, visibility, and silhouettes need review against gameplay requirements.
- Catalogue original defects. Classify each as required compatibility behavior, corrected defect, or unresolved behavior; do not reproduce known vulnerabilities as a requirement.
- Specify tolerances before comparing traces. Never claim complete fidelity from visual similarity alone.
- Require traceability from behavior specification to asset dependencies, implementation, and validation evidence.
Platform contract to finalize in early research
macOS Apple Silicon is a primary target; evaluate Intel macOS as a separate hardware tier. Linux x86_64 is a primary target; Linux ARM64 is a decision to record, not an assumed release promise. Test macOS Metal and Linux Vulkan, with Linux X11 and Wayland window/input behavior covered. Headless server support must not depend on a GPU or a desktop session.
Solari is a required deliverable on the GPU/OS combinations proven to support it. Provide a tested raster rendering path for comparison and for hardware outside that matrix, with clear capability reporting. This fallback does not satisfy G5 by itself. Determine actual supported GPUs, denoising, animated geometry, material support, and minimum performance before promising broad Solari compatibility. See initial platform findings.
Compatibility decisions
The final rewrite must have working Rust-to-Rust multiplayer. Investigate original client/server interoperability and demo compatibility in full; they are separate exit gates because matching gameplay does not establish wire compatibility. Record whether releases require original-to-Rust interoperability, a compatibility adapter, or a documented new protocol. Do not claim parity with public original servers until verified against the reference implementation and authorized service access.
Account authentication and official anti-cheat cannot be reconstructed into a promise of access to operator-controlled services. Document their behavior and dependencies, implement offline/LAN play independently, and define the release policy for online identity and server discovery.
Deliverables
- Versioned reverse engineering handbook, evidence ledger, format specifications, recovered API/ABI tables, behavior tables, and open-question register.
- Reproducible inventories, content dependency graphs, extraction/conversion tools, intermediate schemas, runtime packages, and conversion QA reports.
- Rust client, shared simulation, dedicated server, networking, Bevy integrations, Solari/raster rendering, UI, audio, bots, demos, and administration.
- Differential reference fixtures, content-wide validation, cross-platform test reports, GPU benchmarks, and compatibility matrices.
- User, developer, server-operator, content-authoring, troubleshooting, build, installation, and release documentation.
- Explicit attribution/rights records for original assets and third-party material, and a release-content strategy. The supplied readme contains reuse restrictions; see F-015 in the findings. Planning and static research proceed while distribution requirements are recorded.
Completion requires the final milestone in Validation and milestones, not merely finishing an early playable slice.