# Urban Terror Rust rewrite: research and implementation plan

Planning snapshot: **2026-10-10**. Reference installation: `.cache/UrbanTerror43/`.

The objective is to reverse engineer and document the supplied game, then rewrite its client and dedicated server in Rust with Bevy and Solari, running on macOS and Linux. The planning pass produced documentation and static inventory evidence. The first research step now also implements and verifies complete PK3 extraction; see [extraction findings](extraction/README.md). Repository storage setup now also includes Git/LFS/Xet filters and commit/push guards, described in [STORAGE.md](STORAGE.md). The [first QVM/native binary analysis](research/README.md) now provides reusable static scripts, reports and disassembly. The game, converters, runtime harnesses and further behavior analysis remain TODO; the original game binaries have not been launched.

Current assessment: see [progress toward the complete game](PROGRESS.md) for the2026-10-19 estimate, implemented evidence and remaining runtime/platform gates.

## Reading order

1. [Goals and definition of completion](GOALS.md): scope, fidelity, platforms, and deliverables.
2. [Initial findings](FINDINGS.md): verified local observations, external references, and remaining uncertainty.
3. [Reverse engineering TODO](REVERSE_ENGINEERING_TODO.md): establish the original game's specification and executable reference tests.
4. [Asset pipeline TODO](ASSET_PIPELINE_TODO.md): unpack, inspect, recode, convert, and validate all content.
5. [Rust, Bevy, and Solari TODO](RUST_BEVY_SOLARI_TODO.md): build the replacement client, server, rendering, and supporting tools.
6. [Validation and milestones](VALIDATION_AND_MILESTONES.md): dependencies, exit gates, risks, and release checks.
7. [Research ledger](RESEARCH_LEDGER.md): evidence conventions and templates for documenting subsequent discoveries.
8. [Inventory evidence](inventory/README.md): machine-readable manifests, hashes, formats, maps, overrides, and case collisions.
9. [Every installation file checklist](FILE_COVERAGE_TODO.md): explicit coverage of all 39 files, including every archive-member variant beneath the PK3 entries.
10. [PK3 extraction findings](extraction/README.md): the implemented unpacker, per-occurrence manifests, hashes, overrides, and case collisions.
11. [Git/Xet storage setup](STORAGE.md): one Hugging Face repository, ordinary Git code, Xet assets, and pointer/history validation.

12. [QVM/native binary analysis](research/README.md): full static decoding/disassembly, entry/ABI evidence, libraries/DLLs and remaining uncertainties.
13. [Large provisional backlog](PROVISIONAL_TODO.md): expanded remaining work, immediate research priorities, platform feasibility and whole-game completion gates.

14. [Dependency-aware testing](TESTING.md): Rust cargo xtask commands, focused report/test selection, full validation and registry maintenance.

## How to use the checklist

The provisional backlog uses separate `PROV` IDs and does not change canonical completion status. Task prefixes are `RE` (research), `AP` (asset pipeline), `RW` (rewrite), `QA` (validation), `MAP` (map completion), and `FILE` (installation file coverage). IDs are stable references for issues and evidence. Tasks stay unchecked until their deliverables exist and their verification is recorded. A section applies to **every applicable item in the inventory**, rather than only a representative example. Newly discovered features receive new tasks and evidence records.

Research produces specifications and reference fixtures; conversion produces versioned assets and reports; implementation consumes both. Each subsystem follows that cycle. The milestones stage the work, but the full completion target includes every supported game mode and all supplied playable maps, with explicit treatment of unused, broken, or example content.

The initial inventory uses archive filename order to identify override **candidates**. That is not a proven runtime virtual filesystem. Do not treat its candidate-selection columns as the final asset resolver.