Initialise native Rust port of Ratchet & Clank: Going Commando

Sets up the foundation for reimplementing the PS2 game in Rust rather than
emulating it. Nothing is implemented yet; this is the scaffold, the verified
target and the working agreements that keep a long project coherent.

Target disc, verified against a real image:

  SCUS_972.68 v1.01, USA Black Label, NTSC 60 Hz
  boot ELF 2,618,684 bytes, SHA-1 bacda860...d098a77, entry 0x00131AE8

The entry point independently matches the value recorded by the rac2-gc-decomp
community reference, which cross-confirms the identification. This is the exact
build the upstream research pins; Greatest Hits v2.00 is a different binary and
is not the target. NTSC matters beyond label compatibility: PAL discs run 50 Hz,
which would make chargeboots and other speed-sensitive movement run at 5/6
speed. Verifying the disc before writing movement code avoids discovering that
in Phase 5.

Contents:

- Five-crate workspace (formats, extract, game, video, engine) on Bevy 0.19.1,
  matching the version ReRAC uses so its Graphics Synthesizer and VU work stays
  portable. `cargo check --workspace` is clean.

- tools/identify-disc.py, which reproduces the identification against any
  disc image and distinguishes a truncated dump from a non-PS2 image.

- .githooks/pre-commit, refusing game data from entering git history: disc
  image extensions, asset directories, container signatures at offset 0, and
  files over 50 MiB. Verified against seven cases including a disc image
  renamed to look like source. Now that this pushes to a remote, this matters
  more than it would have locally.

- AGENTS.md, the operating agreements: no game data ever, reproduce the PS2
  float model rather than approximating it, bound every read, verify against
  the real disc.

- PROVENANCE.md, recording that this follows ReRAC (ISC) and learns from
  rac2-gc-decomp (MIT). Wrench is used as a written specification only and no
  GPLv3 code is copied, since that would relicense everything derived from it.
  RAC2Decomp is explicitly not used: its provenance is disputed in the upstream
  community reference, and it targets the wrong region.

- docs/roadmap.md, phased so the riskiest unknowns are retired early. The two
  that matter: overlay relocation transfers from ReRAC and makes 27 level
  overlays tractable, while VU1 microcode is binary and is the hardest single
  item. Phase 5 is a deliberately scoped Veldin vertical slice as the go/no-go.
This commit is contained in:
2026-10-09 15:42:10 +02:00
commit a02f79a6d1
20 changed files with 6880 additions and 0 deletions
+29
View File
@@ -0,0 +1,29 @@
//! Disc pipeline for *Ratchet & Clank: Going Commando* (PS2).
//!
//! Turns a legally obtained disc image into verified, unpacked asset files that
//! the engine can read directly, and does nothing else.
//!
//! # Stages
//!
//! 1. **identify** - read `SYSTEM.CNF`, confirm serial/version/video mode and
//! hash the boot ELF. Reports clearly when a disc is not the supported
//! build. A Python reference implementation of this stage lives in
//! `tools/identify-disc.py`.
//! 2. **unpack** - read `RC2.HDR`, walk the table of contents, decompress WAD
//! streams and write per-level and global asset directories.
//! 3. **verify** - check every extracted file against a recorded size and
//! SHA-1 table, so a corrupted or mismatched dump cannot quietly produce a
//! subtly wrong game.
//!
//! # Output layout
//!
//! Extracted data is written outside the repository (see `.gitignore`). The
//! pre-commit hook in `.githooks/` refuses disc images, asset directories and
//! oversized files, so nothing here can end up in git history by accident.
//!
//! # Verification is not optional
//!
//! Every parser downstream is only as trustworthy as the bytes it was handed.
//! A hash table committed to the repo (sizes and hashes only, never content)
//! is what lets a test say "this parse matches the retail disc" rather than
//! "this parse matches whatever happened to be on my disk".