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:
+120
@@ -0,0 +1,120 @@
|
||||
# PROVENANCE
|
||||
|
||||
This project is built on the work of other people. Their licences apply to their
|
||||
code, and those notices travel with anything derived from it.
|
||||
|
||||
## Summary
|
||||
|
||||
| Project | Role | Licence | Code copied into this repo? |
|
||||
|---|---|---|---|
|
||||
| [ReRAC](https://github.com/re-rac/rerac) | Native Rust/Bevy port of Ratchet & Clank (2002) — the architecture this follows | ISC | Not yet; derived from, attribute when used |
|
||||
| [OpenRAC / rac2-gc-decomp](https://github.com/OpenRAC/rac2-gc-decomp) | Matching decompilation research for this game | MIT | No — consulted for documentation |
|
||||
| [rac2-gc-decomp community reference](https://github.com/OpenRAC/rac2-gc-decomp/blob/RAC2/docs/COMMUNITY-ENGINE-REFERENCE.md) | Engine architecture notes, moby struct layout | MIT | Documentation only |
|
||||
| [Wrench](https://github.com/chaoticgd/wrench) | Insomniac container format documentation | GPLv3 | **No.** Specification reference only |
|
||||
| [RAC2Decomp](https://github.com/platypet2217-star/RAC2Decomp) | Functional decompilation, PAL | MIT | **Not used** — see below |
|
||||
|
||||
## Game content: none
|
||||
|
||||
No game assets, disc images, extracted data, BIOS dumps or proprietary
|
||||
toolchains are or may be committed to this repository. The build takes the
|
||||
user's own legally obtained disc as input. This is enforced by
|
||||
`.githooks/pre-commit`.
|
||||
|
||||
Ratchet & Clank is a trademark of Sony Interactive Entertainment. This is an
|
||||
unofficial fan project, not affiliated with or endorsed by Sony Interactive
|
||||
Entertainment or Insomniac Games.
|
||||
|
||||
---
|
||||
|
||||
## ReRAC — ISC
|
||||
|
||||
The direct model for this project. ReRAC re-implements the *first* Ratchet &
|
||||
Clank as a native Rust application on Bevy, reading assets from the player's own
|
||||
disc. This project follows the same architecture for the second game.
|
||||
|
||||
What we take from ReRAC:
|
||||
|
||||
- **The architecture.** Crate split (`formats` / `extract` / `game` / `engine` /
|
||||
`video`), Bevy 0.19.1, the PS2 float-model discipline, and the milestone
|
||||
gating style.
|
||||
- **Overlay relocation.** `rc-formats::level_overlay` implements
|
||||
relocation-tolerant code-identity matching so one level's function can be
|
||||
found on every other level. R&C2's 27 overlays have the same seven-section
|
||||
layout (`.lit`, `.bss`, `.data`, `lvl.vtbl`, `lvl.camvtbl`, `lvl.sndvtbl`,
|
||||
`.text`), so this machinery transfers directly. It is the single most
|
||||
valuable thing we inherit.
|
||||
- **Verified format specs.** `docs/formats/disc_layout.md` documents all four
|
||||
R&C games' container layouts, derived from behavioural analysis.
|
||||
- **Discipline worth copying.** Golden tests against committed snapshot hashes;
|
||||
bit-exact CPU/GPU identity checks; documenting negative results.
|
||||
|
||||
ISC permits use, modification and redistribution with the notice intact. When
|
||||
code is derived from ReRAC it must carry:
|
||||
|
||||
```
|
||||
Copyright (c) 2026 ReRAC contributors
|
||||
Licensed under the ISC License.
|
||||
```
|
||||
|
||||
Pinned checkout: `vendor/rerac` at commit
|
||||
`d00cb00ad4018f776556e72640dcba438d098a77` (2026-10-09). Not tracked by git —
|
||||
clone it yourself; the commit is recorded so everyone uses the same one.
|
||||
|
||||
Note that ReRAC targets a *different game*. Its per-level documentation is a
|
||||
useful hint about Insomniac's engine in general, but R&C2's spherical worlds
|
||||
changed roughly 50,000 lines of gameplay code, so nothing about R&C1's
|
||||
movement, camera or level geometry should be treated as directly applicable.
|
||||
|
||||
## OpenRAC / rac2-gc-decomp — MIT
|
||||
|
||||
Matching decompilation research for **this** game, targeting exactly our disc
|
||||
(`SCUS_972.68` v1.01). It reconstructs the boot ELF and all 27 level overlays
|
||||
byte-for-byte, and publishes verified struct layouts, symbol names and engine
|
||||
documentation.
|
||||
|
||||
We use it as a **reference**, not as source. Its value is that it tells us what
|
||||
the structures *are*, which saves a great deal of guessing.
|
||||
|
||||
Its matching progress is low (~1.6% of code in C) and byte-matching is not a
|
||||
prerequisite for this port anyway — it is a verification technique. We are not
|
||||
pursuing a byte-identical rebuild.
|
||||
|
||||
## Wrench — GPLv3, specification reference only
|
||||
|
||||
Community documentation and tooling for Insomniac's container formats. We use
|
||||
the written format *specifications* as a reference for how the data is laid
|
||||
out.
|
||||
|
||||
**No Wrench code is copied into this repository.** That is deliberate and
|
||||
load-bearing: copying GPLv3 code would impose GPLv3 terms on everything derived
|
||||
from it. Clean-room reimplementation from a written specification does not. If
|
||||
this boundary is ever crossed, the licensing of this project changes and
|
||||
`AGENTS.md` must be updated to say so.
|
||||
|
||||
## RAC2Decomp — not used
|
||||
|
||||
A functional (non-byte-matching) decompilation of the PAL release. It is
|
||||
recorded here only so its absence is a decision rather than an oversight.
|
||||
|
||||
The `rac2-gc-decomp` community reference explicitly flags it as *"criticized by
|
||||
community for questionable provenance and non-clean-room C code. Avoid
|
||||
copying."* Given that we are building a reimplementation and its provenance is
|
||||
disputed, we do not use it. It is also the wrong region: PAL, 50 Hz.
|
||||
|
||||
## Third-party libraries
|
||||
|
||||
Rust dependencies keep their own licences; see `Cargo.lock` and each crate's
|
||||
`LICENSE` file. Notable ones:
|
||||
|
||||
- **Bevy** (MIT / Apache-2.0) — application framework and wgpu renderer.
|
||||
- **wgpu / wgpu-hal / wgpu-types** (MIT / Apache-2.0) — GPU abstraction used for
|
||||
the Graphics Synthesizer reimplementation.
|
||||
- **bytemuck** (Zlib OR Apache-2.0 OR MIT) — zero-copy casts over asset
|
||||
structures.
|
||||
- **thiserror**, **anyhow** (MIT OR Apache-2.0) — error handling.
|
||||
|
||||
## When you add a dependency or port code
|
||||
|
||||
1. Record it in this file, with its licence and what you took.
|
||||
2. Keep the upstream notice intact in any file containing derived code.
|
||||
3. If it would change this project's licensing terms, stop and say so first.
|
||||
Reference in New Issue
Block a user