port: the container agent answers the questions, it does not build the port
Some checks failed
Some checks failed
Corrects the split I got wrong in b5a1938. The container is for reverse
engineering, now focused on the menu port; a SEPARATE agent builds the port from
its investigation results. My previous version had the container agent writing
the exporter and the Godot project, which is not the intent.
This lands on the research/engineering line that was already in the estimate:
the container agent takes the research half, the port agent the engineering half.
docs/port/MISSION.md is now a list of open QUESTIONS (Q1-Q9) rather than build
milestones, ordered by what blocks the port earliest -- the keyframe time unit,
which build is which screen state, paint order for the six screens, button ->
GamePart, navigation semantics, the boot sequence driver, transitions, menu
audio bindings, and video binding. Each is done when a written result with
evidence exists, not when something compiles. S1, the Ready Room probe, stays
gated at one iteration and a go/no-go.
Most of these are BEHAVIOUR questions -- timing, transitions, what a d-pad press
does at the end of a list -- so the mission and the loop prompt both push hard
on measuring the oracle rather than reasoning from the file.
docs/port/FORMAT.md is deleted. The export schema is the port agent's design and
was not mine to specify. It is replaced by docs/port/HANDOFF.md, the single page
the port agent reads: a status table, what is already settled and can be relied
on today, and the facts that will trip the port up (the WMV3/WMA Pro intro, the
Static.slb size over-declaration, the voice-vs-music downmix, JNGL_001).
The derived/authored idea survives as the thing it always was -- a finding, not
a design. Every answer must be classified DECODED, MEASURED or UNDECODABLE-with-
reach, and never a fourth thing, because measured and undecodable both mean the
port agent is authoring that value and has to know it. Labelling a guess as a
decode would put it into the port wearing the badge of a measurement.
Reverts the Godot install from the RE container, its AGENT.md section, and the
export/ gitignore entry -- none of that belongs on this side of the wall.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Sylpheed RE agent
@@ -1,171 +1,131 @@
|
||||
# Primary objective — a playable menu shell in Godot
|
||||
# Primary objective — answer everything the menu port needs
|
||||
|
||||
**Status:** active, set 2026-08-28. This supersedes "work the RE backlog" as the
|
||||
agent's primary objective. Reverse engineering continues, but it is now *in
|
||||
service of* this goal: an item earns attention because the port needs it.
|
||||
**Status:** active, set 2026-08-28. This replaces "work the RE backlog" as the
|
||||
agent's primary objective. It does not change what the agent *does* — it is still
|
||||
reverse engineering — it changes what earns attention: an item is worth doing
|
||||
when the menu port is blocked on it.
|
||||
|
||||
## What we are building
|
||||
## Who builds what
|
||||
|
||||
A Godot 4 project that boots to an interactive main menu using the player's own
|
||||
disc, through the sequence the real game uses:
|
||||
**You do not build the port.** A separate agent will build it, from what you
|
||||
produce. Your deliverable is decoded, verified, written-down answers plus the
|
||||
reference data that proves them.
|
||||
|
||||
| | container agent (you) | port agent |
|
||||
|---|---|---|
|
||||
| decodes the disc | ✅ | ❌ — consumes your answers |
|
||||
| measures the running game | ✅ | ❌ — no emulator |
|
||||
| writes `docs/re/` and `docs/port/HANDOFF.md` | ✅ | reads them |
|
||||
| Godot project, asset pipeline, transcoding | ❌ | ✅ |
|
||||
|
||||
If you find yourself designing an export schema or writing GDScript, you have
|
||||
crossed the line. Stop and go back to the question you were answering.
|
||||
|
||||
`crates/sylpheed-viewer` is also **not yours to change** for this objective. The
|
||||
Explorer is the human's tool for exploring and verifying the RE work, it keeps its
|
||||
static-data-only rule, and the port does not depend on it.
|
||||
|
||||
## The target
|
||||
|
||||
Someone else has to build this, from your answers alone:
|
||||
|
||||
```
|
||||
developer logo splash → intro video → title / PRESS Ⓐ → main menu → submenus
|
||||
```
|
||||
|
||||
No gameplay. No 3D. No emulator. The success condition is a human pressing a
|
||||
d-pad and Ⓐ and moving through those screens with the right art, the right
|
||||
animation, the right music and the right transitions.
|
||||
No gameplay, no 3D, no HUD, no missions. If an answer is not needed to put those
|
||||
five screens on a display and let a person move through them with a d-pad and Ⓐ,
|
||||
it is not in this objective.
|
||||
|
||||
**Ready Room is a gated stretch goal.** See §6 — do the probe first, then stop
|
||||
and report rather than committing to it.
|
||||
## What is already answered
|
||||
|
||||
## 1. The two halves, and the wall between them
|
||||
Do not re-derive these. They are in `docs/re/` and the
|
||||
[disc atlas](../re/disc-atlas.html):
|
||||
|
||||
The Godot project **never reads a disc format**. It reads only open formats. The
|
||||
conversion happens offline, in Rust, and the wall between the two is the point:
|
||||
* **The screen archive.** `GP_TITLE.pak` holds the whole title-side tree — build 4
|
||||
the title with animating wordmarks, build 5 the five-button main menu, builds
|
||||
6/8/9 submenus, and the developer splash as the `palogo` bundle in the same pak.
|
||||
* **Buttons are identifiable as data.** Element kind `0x3002` is a button, `0x0`
|
||||
decoration, `0x10` a primitive; buttons sort top-to-bottom by resting Y; each
|
||||
pairs with an `f`-suffixed highlighted variant.
|
||||
* **The screen vocabulary.** The GamePart id table, 29 entries at `.rdata
|
||||
0x820A1630`, confirmed by the executable's own factory-registration strings.
|
||||
* **The resting pose rule** — the hold, not the longest dwell — and that a
|
||||
keyframe is the *start of a ramp*.
|
||||
* **Screen composition**, pixel-accurate for the tutorial pause menu and the title
|
||||
main menu, via `sylpheed-cli screen render`.
|
||||
* **The logo splash is not a video.** `logo1`–`logo4` are manifest-bound with no
|
||||
`.wmv` on the disc; the splash is the RATC screen, which already renders.
|
||||
|
||||
```
|
||||
disc ──▶ crates/sylpheed-export ──▶ export/ ──▶ port/ (Godot 4)
|
||||
(Rust, uses sylpheed-formats) JSON + PNG + OGG reads ONLY
|
||||
+ Ogg Theora open formats
|
||||
```
|
||||
## The open questions — these are the objective
|
||||
|
||||
* **No GDExtension. No Rust in the Godot project.** If Godot needs something it
|
||||
cannot read, the exporter's job is to emit it in a form Godot can, not to
|
||||
bridge the two runtimes.
|
||||
* **`crates/sylpheed-viewer` is not involved.** The Explorer is the human's tool
|
||||
for exploring and verifying the RE work. It stays Rust/Bevy, it keeps its
|
||||
static-data rule, and it is neither a dependency of nor a dependent on the
|
||||
port. Do not refactor it "to share code with" the port.
|
||||
* `sylpheed-formats` is shared, because it is the decoder and there must be one.
|
||||
Ordered by what blocks the port earliest. Each is done when its **gate** exists:
|
||||
a written `docs/re/` result with the evidence, and reference data committed
|
||||
alongside it.
|
||||
|
||||
## 2. The format is a deliverable, not a dump
|
||||
|
||||
The second goal of this port is **modding**. That makes the exported layout part
|
||||
of the product, not a temp directory:
|
||||
|
||||
* **JSON, not XML.** Godot parses JSON natively with `JSON.parse_string`; its
|
||||
`XMLParser` is a SAX-style API that would need a hand-written binding for every
|
||||
schema. JSON is also what every external tool a modder might reach for already
|
||||
speaks.
|
||||
* **Names, never hashes.** A file is `screens/title/main_menu.json`, not
|
||||
`0x90822a39.json`. Where the disc's own name was never recovered — the six
|
||||
`*2D` archives and `GP_READY_ROOM`, see [the atlas](../re/disc-atlas.html) —
|
||||
emit a stable synthetic id **and record in the file that the real name is
|
||||
unknown**. A modder must be able to tell a recovered name from one we invented.
|
||||
* **A tree that means something.** `screens/`, `sprites/`, `audio/music/`,
|
||||
`audio/sfx/`, `video/`, `text/<lang>/` — organised by what a person is looking
|
||||
for, not by which archive it came out of.
|
||||
* **Provenance in every generated file.** Source archive, entry index, and the
|
||||
exporter version. This is what keeps the export auditable against the disc
|
||||
instead of drifting into an unverifiable fork.
|
||||
|
||||
The schema lives in [FORMAT.md](FORMAT.md) and is **versioned**. Changing it is a
|
||||
deliberate act with a version bump, not a silent edit.
|
||||
|
||||
## 3. Derived vs authored — keep these apart
|
||||
|
||||
This is the discipline that matters most, and it is the corpus's own rule applied
|
||||
to a new artefact.
|
||||
|
||||
| | `export/` | `authored/` |
|
||||
| | Question | Gate |
|
||||
|---|---|---|
|
||||
| produced by | running the exporter | a human or the agent, by hand |
|
||||
| contains | what the disc says | what we decided |
|
||||
| edited by hand | **never** | always |
|
||||
| committed to git | **no** (see §4) | yes |
|
||||
| when regenerated | overwritten wholesale | untouched |
|
||||
| **Q1** | **What is a keyframe time?** Values run 16…269. 60 Hz frames would make the title intro ~4.5 s — plausible and untested. Also: is the ramp linear, or eased? | A measured answer against the running game, not an inference. Everything animated downstream depends on this number |
|
||||
| **Q2** | **Which build is which screen state?** Confirm build↔state for splash, title/PRESS Ⓐ, main menu and each submenu | A table, each row confirmed against a capture of the real screen |
|
||||
| **Q3** | **Paint order for these six screens.** Solved at runtime, unsolved from the file — the declaration table is provably not it | Either a rule derived from the bundle, or six measured orders and a clear statement that no file-side rule was found |
|
||||
| **Q4** | **What does each button do?** Labels are baked into the sprites; no decoded field says which GamePart a button opens | Button → GamePart id, from code or from driving the game. Say which |
|
||||
| **Q5** | **Navigation semantics.** Initial focus, wrap-around at the ends, whether left/right does anything, what B does on each screen | Observed behaviour, per screen |
|
||||
| **Q6** | **The boot sequence, and what drives it.** Order is observable; the *data or code* that sequences it is not decoded. Include the attract loop and what returns to the title | The sequence, plus whatever the game reads to decide it |
|
||||
| **Q7** | **Transitions.** What happens visually between screens — the `pteff00.prm` quads, a fade, a cut — and its timing | Described and timed against a capture |
|
||||
| **Q8** | **Menu audio.** Which BGM per screen; which cue on move / confirm / back / error. The cue table is complete; the event binding is not | Cue names bound to events, with how you established each |
|
||||
| **Q9** | **Video binding.** Which movie is the boot intro vs the new-game intro; whether playback is skippable and what ends it | Named movies plus the playback rules |
|
||||
| **S1** | **Ready Room probe.** *Gated* — one iteration, then stop | A written go/no-go (see below) |
|
||||
|
||||
Some things this milestone needs are **not on the disc in any form we have
|
||||
decoded**, and they must live in `authored/` with a stated reason:
|
||||
## Known unknowns — say so, do not fill them in
|
||||
|
||||
* **Which button does what.** `ptbtn01…05` are sprites with baked-in labels. A
|
||||
human can read "NEW GAME" off the image; there is no field that says so. The
|
||||
mapping button → GamePart id is an authored guess until code says otherwise.
|
||||
* **Paint order.** Solved at runtime, unsolved from the file — the declaration
|
||||
table is provably not it. For these six screens, author the z-order and mark it
|
||||
authored. Do **not** let a hand-tuned order leak into `export/` and later get
|
||||
mistaken for a disc fact.
|
||||
* **Sound-cue bindings.** Which cue fires on move / confirm / back.
|
||||
Some of these may turn out to be undecodable. That is a valid, useful answer, and
|
||||
it is better than a guess, because the port agent will otherwise have to author
|
||||
the mapping by hand and needs to know it is authoring rather than transcribing.
|
||||
|
||||
Every `authored/` entry carries a `why` field. When a later iteration decodes the
|
||||
real answer, the authored entry is deleted and the exporter emits it instead —
|
||||
and that transition is the measure of progress.
|
||||
For each question, the answer is one of:
|
||||
|
||||
## 4. Do not commit game assets
|
||||
* **decoded** — here is the field, here is the disc-wide check;
|
||||
* **measured** — not on the disc in any form we found, but here is what the
|
||||
running game does, and here is the capture;
|
||||
* **undecodable, with reach** — we looked here, here and here, and this is why it
|
||||
is not there.
|
||||
|
||||
`export/` is generated from the user's own disc and **must be gitignored**. The
|
||||
repository stays a clean-room port: code, schemas, authored mappings and
|
||||
documentation. Anyone building it supplies their own disc. If you find yourself
|
||||
committing a PNG of a game sprite or a transcoded video, stop.
|
||||
Never a fourth thing. In particular: if Q4 ends as "read the labels off the sprite
|
||||
images by eye", say exactly that — it is then an authored mapping on the port
|
||||
side, not a disc fact, and mislabelling it would put a guess into the port wearing
|
||||
the badge of a measurement.
|
||||
|
||||
## 5. Milestones, each with a gate
|
||||
## The Ready Room probe (S1) — one iteration, then stop
|
||||
|
||||
Do these in order. A milestone is done when its **artifact** exists, not when the
|
||||
code compiles.
|
||||
`GP_READY_ROOM.pak` is the largest UI archive on the disc, 1 106 entries, and only
|
||||
**6 of its names resolve**. It is also ISL-scripted. That is either a week or a
|
||||
quarter, and one cheap test tells you which.
|
||||
|
||||
| | Milestone | Gate (the artifact) |
|
||||
|---|---|---|
|
||||
| **P0** | Exporter skeleton; one screen and its sprites to `export/` | `export/screens/title/main_menu.json` validates against FORMAT.md, and the PNGs open |
|
||||
| **P1** | Godot renders that screen statically at 1280×720 | A screenshot from Godot beside `sylpheed-cli screen render` of the same build — they should agree |
|
||||
| **P2** | Keyframe animation | The main menu's buttons slide in. **Measure the time unit first** (§7) |
|
||||
| **P3** | Splash → title, with the transition | Godot runs the two screens back to back unattended |
|
||||
| **P4** | Intro video | `ADV.wmv` plays in Godot with audio (§7) |
|
||||
| **P5** | Main menu: d-pad navigation, focus states, Ⓐ into a submenu, B back | A human clicks through it |
|
||||
| **P6** | Audio — menu BGM and move/confirm SFX | Sound on the gate in P5 |
|
||||
| **P7** | New-game intro video after NEW GAME | Plays, then returns to a defined state |
|
||||
| **S1** | *Gated* — Ready Room. Run the probe in §6 and **stop** | A written go / no-go |
|
||||
|
||||
## 6. The Ready Room probe — do this early, it is one iteration
|
||||
|
||||
`GP_READY_ROOM.pak` is the largest UI archive on the disc, 1 106 entries, and
|
||||
only **6 of its names resolve**. It is also ISL-scripted. That could mean a week
|
||||
or a quarter, and one cheap test tells you which.
|
||||
|
||||
**The probe:** our screen catalog enumerates bundles by **content**, not by name
|
||||
— `is_build` / `is_composable` read the bytes. Unrecoverable *paths* therefore do
|
||||
not necessarily mean unrenderable *screens*.
|
||||
Our screen catalog enumerates bundles by **content**, not by name — `is_build` /
|
||||
`is_composable` read the bytes — so unrecoverable *paths* do not necessarily mean
|
||||
unrenderable *screens*.
|
||||
|
||||
```bash
|
||||
sylpheed-cli screen list "$SYLPHEED_DISC/dat/GP_READY_ROOM.pak"
|
||||
sylpheed-cli screen render --build <n> "$SYLPHEED_DISC/dat/GP_READY_ROOM.pak" /tmp/rr.png
|
||||
```
|
||||
|
||||
Report: how many builds it finds, whether any composite looks like a Ready Room,
|
||||
and whether the screens are 2D at all or whether the room is 3D with a UI overlay
|
||||
— because if it is 3D, this milestone is out of scope by definition and the
|
||||
answer is no-go, not "try harder".
|
||||
Report how many builds it finds, whether any composite looks like a Ready Room,
|
||||
and **whether the room is 2D at all** or 3D with a UI overlay — if it is 3D the
|
||||
answer is no-go by definition, not "try harder".
|
||||
|
||||
**Then stop and write the go/no-go.** Do not start Ready Room work on your own
|
||||
authority.
|
||||
|
||||
## 7. Two decisions already made, and one measurement owed
|
||||
## Handing it over
|
||||
|
||||
**Video: transcode to Ogg Theora.** `ADV.wmv` is WMV3 video with WMA Pro audio,
|
||||
1280×720 at 30 fps, 137 s. Godot 4 plays only Ogg Theora natively. Transcode with
|
||||
ffmpeg and **keep the exact command in the exporter's config** so it can be re-run
|
||||
with different settings. Theora at 720p is not great; if the result is visibly
|
||||
poor, say so and propose the FFmpeg-GDExtension fallback — do not silently adopt a
|
||||
dependency. Only `ADV.wmv` and the one new-game intro are in scope; the disc holds
|
||||
3.3 GB of video and transcoding all of it is not this milestone.
|
||||
[`HANDOFF.md`](HANDOFF.md) is the single page the port agent reads. Keep it
|
||||
current as you answer questions: it is a summary with links into `docs/re/`, not a
|
||||
second copy of the findings. An answer that is not reachable from HANDOFF.md has
|
||||
not been delivered.
|
||||
|
||||
**Screens: `GP_TITLE.pak` is the whole title-side tree.** Build 4 is the title
|
||||
with the animating wordmarks, build 5 the five-button main menu, builds 6/8/9 are
|
||||
submenus, and the developer splash is the `palogo` bundle in the same archive.
|
||||
Buttons are identifiable as data: element kind `0x3002`, ordered top-to-bottom by
|
||||
resting Y, each paired with an `f`-suffixed highlighted variant. You do **not**
|
||||
need the undecoded navigation graph to make a vertical menu work.
|
||||
## Out of scope
|
||||
|
||||
**The measurement owed: what is a keyframe time?** Values run 16…269 on the title
|
||||
build. 60 Hz frames would make the title intro ~4.5 s, which is plausible and
|
||||
untested. Settle it against a capture before building animation on it — this is
|
||||
exactly the kind of number that silently poisons everything downstream.
|
||||
[`ui-resting-pose.md`](../re/structures/ui-resting-pose.md) already establishes
|
||||
that a keyframe is the **start of a ramp**, not a pose that is held.
|
||||
|
||||
## 8. What is explicitly out of scope
|
||||
|
||||
3D, gameplay, HUD, missions, the emulator, save/load, localisation beyond English,
|
||||
and any archive outside `GP_TITLE`, `tables.pak`, `sound.pak` and `dat/movie/`
|
||||
— except for the Ready Room probe in §6.
|
||||
3D, gameplay, HUD, missions, save/load, localisation beyond English, the Godot
|
||||
project itself, any asset pipeline, and any archive outside `GP_TITLE`,
|
||||
`tables.pak`, `sound.pak` and `dat/movie/` — except for the S1 probe.
|
||||
|
||||
Reference in New Issue
Block a user