ReaperOfVeriod
a02f79a6d1
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.
120 lines
5.6 KiB
Markdown
120 lines
5.6 KiB
Markdown
# 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. |