fabi/Sylpheed-Godot
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: FORMAT v2, what P0 decided, and BLOCKED reconciled

Browse Source 
FORMAT is bumped to v2 with a "Changes from v1" table giving a reason per row.
v1 was written before HANDOFF answered Q1 and Q3 and before the two-colour
modulate was known; each change is a thing v1 could not have said. The paint
order moves from `unresolved` into the export, because Q3 decoded it — a u16
layer key at +0x0A, stable-sorted — and a decoded answer is read in the
exporter. `paint_order_ties` replaces it, because the tie-break is still
unknown.

Where a layer key is not in the file it comes from the decoders' table of keys
measured off the running game. That is a different kind of fact, so it is
labelled: `layer_source` is "sprite", "implied" or "none".

BLOCKED is reconciled against HANDOFF at /reborn e81dcad. Seven of its ten rows
are answered and are moved out; what remains is Q8 (no cue-to-event binding),
the two Q10 unknowns (which BGM, and where a loop restarts), Q9's unsettled
skippability, Q4's untested NEW GAME, and Q6's undecoded boot driver.

It also raises one question back, found by counting the export rather than by
reverse engineering anything: the decoders document a .t32 element's pivot as
"exactly half the decoded texture's dimensions (verified 7/7 on the tutorial
bundle)", and on GP_TITLE that holds for 55 of 93 sprite-bearing .t32 elements.
38 do not, some grossly — ptlogo_back2 is 1118x262 with pivot (500,117) where
half is (559,131). It changes nothing today, because the exporter emits the
declared pivot and the pivot only matters when scale != 100%. But scale IS
animated here — 177 keyframes across GP_TITLE are not 100%, including on the
title screen P1 has to draw — so the question of what the running game anchors a
scale to is worth an answer before P2. Noted there that the port and
`sylpheed-cli screen render` make the same choice, so a P1 diff cannot
distinguish them and their agreement is not evidence.
This commit is contained in:
Sylpheed port agent
2026-08-28 18:43:52 +00:00
parent 8dd0577e01
commit 8d2c092788
3 changed files with 340 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/BLOCKED.md
View File

@@ -4,20 +4,67 @@ What this port cannot do until an answer lands in
[`/reborn/docs/port/HANDOFF.md`](https://git.mc02.dev/fabi/Syplheed-Reborn).
Recorded so it is not re-discovered every iteration.
| Milestone | Needs | HANDOFF question |
|---|---|---|
| P2 keyframe animation | the unit of a keyframe time, and the ramp shape | Q1 |
| P3 splash → title | which build is which screen state | Q2 |
| P1/P3 correct layering | paint order for these six screens | Q3 |
| P5 button actions | which button opens which GamePart | Q4 |
| P5 navigation | initial focus, wrap-around, what B does | Q5 |
| P3 sequencing | the boot order and what drives it | Q6 |
| P3 transitions | what happens visually between screens, and its timing | Q7 |
| P6 audio | which BGM per screen; which cue on move/confirm/back | Q8 |
| P4/P7 video | which movie is the boot intro vs the new-game intro | Q9 |
| P6 looping | whether a music bank's sub-waves are intro+loop or variations | Q10 |
**None of these may be guessed.** A value invented here is indistinguishable from
a decoded one a month from now. Where a milestone can proceed with a placeholder,
put the placeholder in `authored/` with a `why` naming the question it is standing
in for, so it is deleted rather than forgotten when the answer arrives.
the placeholder goes in `authored/` with a `why` naming the question it stands in
for, so it is deleted rather than forgotten when the answer arrives.
Last reconciled against HANDOFF.md on **2026-08-28**, at `/reborn` HEAD `e81dcad`.
## Still open — these block work
| Milestone | Needs | HANDOFF | State |
|---|---|---|---|
| P6 audio | which cue fires on move / confirm / back | Q8 | ❔ open. The cue table is complete; the **event binding is not**. P6 cannot bind a sound to a keypress without inventing it. |
| P6 audio | which BGM the menu plays | Q10 | ❔ **not on the disc.** All 32 banks are named `BGM_001`…`BGM_109` with no semantic name anywhere. The port is choosing a track, and that choice is authored. |
| P6 looping | where a menu loop restarts | Q10 | ❔ `BGM_001` fades out at 167.663 s into 6.15 s of silence, and no loop-point field has been identified. A menu loop is authored. |
| P4/P7 video | whether Ⓐ skips a movie | Q9 | 🟡 unsettled — the corpus says Ⓐ skips every time, the boot harness never taps during a movie because it breaks the title. P4 can play the movie; it cannot yet say what a button press does during one. |
| P5 `NEW GAME` | what Ⓐ on `NEW GAME` opens | Q4 | ❔ untested: Ⓐ on it **hangs the emulator**. The other four destinations are measured. |
| P3 sequencing | what code decides to advance the boot sequence | Q6 | 🟡 the order is observed and the attract cycle timed (~8–10 s idle → fade → `ADV.wmv` in full → title). The *driver* is not decoded. P3 can reproduce the observed behaviour and must say it is reproducing an observation. |
## Answered since this file was last written — no longer blocking
Q1 (keyframe time unit — linear ramp, 2 units per rendered frame, 1 unit = 1/60 s
*measured*), Q2 (which build is which screen), Q3 (paint order — a `u16` layer key
at `+0x0A`, **decoded**), Q5 (navigation: ⬆⬇ wrap, ⬅➡ nothing, Ⓑ up with focus
restored), Q7 (transitions: a fade through black, fade-in decoded, ~0.4 s fade-out
measured), Q9 (`ADVERTISE_MOVIE` → `ADV.wmv` is boot intro *and* attract; `MS00A` →
`S00A.wmv` is the new-game intro), Q10 (a bank is two stems played **together** —
do not concatenate), S1 (Ready Room: no-go).
Three of those are **measured**, not decoded, and so are authored here rather
than exported:
| Authored because it is not on the disc | HANDOFF | Where it lives |
|---|---|---|
| `1 keyframe unit = 1/60 s` | Q1 | not yet written — P2 |
| initial menu focus (not stable across boots; pick one and say so) | Q5 | not yet written — P5 |
| the ~0.4 s fade-out and the 0.17–0.23 s black hold | Q7 | not yet written — P3 |
## Questions this port has raised
Not blocking anything today; raised because the port found them and a guess here
would be believed later.
### The pivot is not half the texture on `GP_TITLE`
`sylpheed-formats`'s `ui_layout::Element::pivot_x` is documented as "for a `.t32`
element this is exactly half the decoded texture's dimensions (verified 7/7 on
the tutorial bundle)". Counting it over the whole of `GP_TITLE` as exported:
* **55 of 93** sprite-bearing `.t32` elements match within ±1 px.
* **38 do not**, and several are not close: `ptlogo_back2` is 1118×262 with pivot
(500, 117) where half is (559, 131); `ptmsg` is 223×38 with pivot (123, 19)
where half is (111.5, 19) — the Y matches and the X does not.
This changes nothing today: the exporter emits the **declared** pivot and never
derives one, and the pivot only affects drawing when scale ≠ 100 %. But it does
matter, because scale is genuinely animated here — **177 keyframes** across
`GP_TITLE` are not 100 %, including on the title screen the port must draw at P1.
The question for the RE agent, when it is cheap to answer: **does the running
game anchor a scale to the declared pivot, or to half the texture?** The two
differ by up to 59 px on `ptlogo_back2`, which is visible. Until then the port
follows the decoders and uses the declared pivot, which is also what
`sylpheed-cli screen render` does — so a P1 diff cannot distinguish them, and
agreement between the two is not evidence.

116
docs/DECISIONS.md Normal file
View File

@@ -0,0 +1,116 @@
# Decisions
One entry per decision that outlives the container it was made in. Newest last.
A decision that lives only in an agent's context is lost when that container
dies, which is what this file is for.
---
## P0 — the exporter, 2026-08-28
### The exporter reads one authored file, and stamps its provenance into the output
`export/` is derived and `authored/` is hand-written, and the natural reading of
that is that the exporter never touches `authored/`. But a screen has to be
*called* something, and the disc does not name its builds — the identification of
build 5 as the main menu is HANDOFF Q2, **measured against a live capture**, not
a field.
Two ways to handle that:
1. the exporter emits `build_05.json` and the runtime renames it from
`authored/screen_names.json`;
2. the exporter reads that map and writes `main_menu.json` directly.
Chose **2**, with a condition: every name it applies carries `name_source:
"authored"` and a `name_why` quoting the evidence, and `check` **rejects** an
authored name with no `why`. The file that lands in `export/` is therefore still
honest about which of its fields is a measurement — which is the property the
derived/authored split exists to protect — while a human opening the tree sees
`main_menu.json` rather than having to resolve a rename in their head. A build
nobody has identified exports as `build_NN` with `name_source: "index"`, which is
a locator and not a claim.
This is the **only** authored input the exporter takes. Everything else in
`authored/` is applied by the runtime over `export/`.
### Sprites are per screen, not a flat pool
`main_menu` and `extras` both ship a `ptbase.t32` and they are different
pictures. A flat `sprites/` directory would have silently collided; whichever
screen exported second would have won, and the loser would have drawn the wrong
background with no error anywhere. `sprites/<subdir>/<screen>/<name>.png`.
### The format is executable
`sylpheed-export check --out export` validates a tree against `docs/FORMAT.md`
with no disc in hand. It exists because "the export is correct" is otherwise an
assertion, and because the P0 gate is *"validates against FORMAT.md"* — which is
not a thing anyone can confirm by reading.
It reads the tree the way Godot will: as a stranger, with no access to the disc,
the decoders, or the exporter's internals. It deliberately does **not** check the
export against the disc — that is what `sylpheed-cli screen render` is for, at P1.
Checked that it bites, rather than assuming: five mutations of a valid
`main_menu.json` — a broken `paint_order` permutation, a dangling
`focus_sprite`, a reversed `buttons` list, a `#rrggbbaa` colour, an invented
`name_source` — are each caught with a specific message.
### The highlight sprite pairs by name; `opt ` is exported but not believed
FORMAT v1 said `focus_sprite` came from the element's `opt ` link. That reading
was **measured and refuted** by the RE agent, and this export shows why plainly:
on the main menu, `opt ` chains `ptloop01 → ptloop02 → ptbtn01` — two decorations
and then a button. It is a linked list of something, and it is not focus.
The highlight is paired by **sprite name** instead (`ptbtn01.t32` ↔
`ptbtn01f.t32`), which is HANDOFF's convention and holds for all 54 real pairs on
the disc. It resolves all five main-menu buttons. The raw link is still exported
as `opt_link`, renamed so that nothing downstream mistakes it for navigation, and
so that whoever eventually decodes it has the data.
Note this is 🟡 a naming convention, not a decoded field. It is authored in
effect, and lives in the exporter only because it is a rule over disc data rather
than a value we chose.
### The paint order is exported, not authored
Q3 decoded it — a `u16` layer key at `+0x0A` of each `T8aD` sprite header,
stable-sorted with declaration index. So it is read in the exporter, per the
contract's own rule for a decoded answer, and `paint_order` in `export/` is a
derived field. `"paint_order"` is gone from `unresolved`; **`paint_order_ties`
replaces it**, because the tie-break is still unknown and costs one element's
blend on one screen.
Where an element has no `T8aD` header the key comes from the decoders' table of
keys **measured off the running game**. That is a different kind of fact, so it
is labelled: `layer_source` is `"sprite"`, `"implied"` or `"none"`, and a
consumer that needs to know whether a layer is read or measured can tell.
### Colours are exported as two fields with the byte order in the name
There are two modulate colours and they multiply: `tint` is RGBA, `fade` is
**ARGB** and its high byte is the alpha that ramps. v1's single `"#ffffffff"`
could not carry both and silently discarded the ramping alpha. They are exported
as `tint_rgba` and `fade_argb`, raw hex, byte order in the key — because getting
it backwards is silent and looks like an art bug rather than a parse bug.
### `t` stays raw
HANDOFF Q1 is answered — linear ramp, 2 units per rendered frame, working
conversion 1 unit = 1/60 s — but that conversion is **measured off the running
game, not read from the file**, and the finding itself flags the 27.6 present-
frames/second measurement as the part worth re-testing. If the game turns out to
present at 60 Hz, every duration halves.
So `t` is exported exactly as the disc spells it, `keyframe_time_unit` stays in
`unresolved`, and the conversion will live in one authored place at P2. One
constant to change, in a file that says it is a decision.
### The final keyframe has no `t`, and `check` enforces that
The disc has no time slot on the last keyframe of a group. A file that carries
one there has invented it. `check` rejects it — this is the one place where the
temptation to emit a plausible number is strongest and the resulting error is
completely invisible.

200
docs/FORMAT.md
View File

@@ -1,9 +1,9 @@
# The open export format — v1
# The open export format — v2
The format the disc is converted *into*, and the one the Godot project and any
modding tool read. **This is a starting point, and it is yours to revise** — but
it is versioned, so a change is a deliberate act with a version bump, not a
silent edit.
modding tool read. **It is versioned, so a change is a deliberate act with a
version bump**, not a silent edit. [Changes from v1](#changes-from-v1) is at the
bottom, with a reason for each.
Design rules, in priority order:
@@ -14,92 +14,196 @@ Design rules, in priority order:
in the file that the real name is unknown**. A modder must be able to tell a
recovered name from an invented one.
3. **Provenance travels with the data.** Source archive, entry index, exporter
version. This is what keeps the export auditable against the disc instead of
drifting into an unverifiable fork.
version, decoder revision. This is what keeps the export auditable against the
disc instead of drifting into an unverifiable fork.
4. **Say what is unknown.** A field we could not decode is absent and listed in
`unresolved` — never guessed, never silently defaulted.
**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 per schema.
**The format is executable.** `sylpheed-export check --out export` validates a
tree against this document with no disc in hand, reading it the way Godot will —
as a stranger. Where the prose here and `crates/sylpheed-export/src/check.rs`
disagree, that is a bug in one of them and worth saying which.
## Layout
```
export/ # DERIVED. Regenerable. Gitignored. Never hand-edited.
manifest.json
screens/title/*.json
sprites/*.png
sprites/title/<screen>/*.png
audio/music/*.ogg audio/sfx/*.ogg audio/cues.json
video/*.ogv
authored/ # AUTHORED. Hand-written. Committed. Survives re-export.
screen_names.json # which build is which screen
flow.json # boot sequence + what each button does
paint_order.json # per-screen z-order
cue_bindings.json # which cue fires on move / confirm / back
```
Godot loads `export/` first, then applies `authored/` over it.
Sprites are **per screen**, not a flat pool: a sprite name is unique within a
bundle and not across them, and `main_menu`'s `ptbase.t32` and `extras`'
`ptbase.t32` are different pictures.
`authored/screen_names.json` is the one authored file the *exporter* reads; the
rest are applied by the runtime over `export/`.
## Common header
```json
{
"format": "sylpheed.screen/1",
"format": "sylpheed.screen/2",
"exporter": "sylpheed-export 0.1.0",
"source": { "archive": "dat/GP_TITLE.pak", "entry": 5 }
"formats_rev": "8b6dbcf",
"source": { "archive": "dat/GP_TITLE.pak", "entry": 5, "build": 5 }
}
```
`source.entry` is the pak **entry index** — the stable locator. Not the display
ordinal, which renumbers whenever the enumeration rule changes.
`source.entry` is the pak **entry index** — the stable locator. `source.build` is
the index into that pak's list of screen builds (what `sylpheed-cli screen
--build N` takes), which is stable only as long as the enumeration rule is.
`formats_rev` pins which decoders produced the file.
## `screens/*.json`
```json
{
"format": "sylpheed.screen/1",
"format": "sylpheed.screen/2",
"exporter": "sylpheed-export 0.1.0",
"source": { "archive": "dat/GP_TITLE.pak", "entry": 5 },
"formats_rev": "8b6dbcf",
"source": { "archive": "dat/GP_TITLE.pak", "entry": 5, "build": 5 },
"name": "main_menu",
"name_source": "authored",
"name_why": "HANDOFF Q2: builds 5/8 are the five-button main menu; 5 is English…",
"design": [1280, 720],
"elements": [
{
"index": 10,
"id": "ptbtn01",
"sprite": "sprites/ptbtn01.png",
"focus_sprite": "sprites/ptbtn01f.png",
"declared": "ptbtn01.rat",
"role": "button",
"kind_raw": "0x3002",
"sprite": "sprites/title/main_menu/ptbtn01.png",
"focus_sprite": "sprites/title/main_menu/ptbtn01f.png",
"opt_link": "ptbtn01f.rat",
"pivot": [42, 22],
"rest": { "pos": [542, 162], "scale": [1.0, 1.0], "tint": "#ffffffff" },
"layer_source": "sprite",
"layer": "0x00008110",
"rest": { "pos": [542, 162], "scale": [100, 100],
"tint_rgba": "0xffffffff", "fade_argb": "0xffffffff", "t": 64 },
"keyframes": [
{ "t": 28, "pos": [542, 142] },
{ "t": 34, "pos": [542, 157] },
{ "t": 64, "pos": [542, 162] }
{ "t": 28, "pos": [542, 142], "scale": [100, 100],
"tint_rgba": "0xffffffff", "fade_argb": "0x00ffffff" }
]
}
],
"paint_order": [1, 3, 4, 2, 5, 8, 9, 6, 7, 15, 10, 11, 12, 13, 14, 0],
"buttons": ["ptbtn01", "ptbtn02", "ptbtn03", "ptbtn04", "ptbtn05"],
"unresolved": ["paint_order", "keyframe_time_unit"]
"unresolved": ["keyframe_time_unit", "paint_order_ties", "fade_out_duration"]
}
```
**`role`** comes from the decoded element kind: `0x3002` → `button`, `0x10` →
`primitive`, `0x0` → `decoration`. Anything else exports as `"unknown"` with the
raw value in `kind_raw`. Do not invent a name for a kind nobody has decoded.
### `name` / `name_source` / `name_why`
`name_source` is `"authored"` or `"index"` and nothing else. `"authored"` means
the name came from `authored/screen_names.json` and **requires** a `name_why`
saying who decided it and on what evidence. `"index"` means nobody has
identified this build and the name is `build_NN` — a locator, not a claim.
### `elements[]`
`index` is the declaration index and is also the key `paint_order` uses; it
always equals the element's position in the array. `id` is `declared` with its
extension stripped.
**`role`** comes from the decoded element kind: `0x3002` → `button`, `0x10`
without a sprite → `primitive`, `0x0` → `decoration`. Anything else is
`"unknown"` with the raw value in `kind_raw`. Do not invent a name for a kind
nobody has decoded.
> ⚠️ `0x3002` is **not** a general button test. It is one member of a `0x3000`
> family with sub-bits, and `GP_READY_ROOM` uses `0x3000` / `0x3004` / `0x300c` /
> `0x3008` with zero `0x3002`. Every screen in this milestone is `GP_TITLE`,
> where the mapping is decoded. A consumer meeting `role: "unknown"` should read
> `kind_raw`, not assume.
> ⚠️ **`kind & 0x4` is a repeated instance of a template.** On the title screen
> those are motion-trail ghosts and are *not* on screen at rest — the draw
> capture shows one quad where the bundle declares three. A runtime should skip a
> `kind & 0x4` element **when another element in the same screen has the same
> `id` and does not have that bit**, and only then: 174 elements on the disc are
> `0x4` with no such template, and a blanket skip erases them. Both are visible
> in this format from `kind_raw` and `id`.
**`pivot`** is the declared pivot, and it is the **anchor scale grows about** —
`pos` is the element's top-left at 1:1, and at scale `s` the drawn top-left is
`pos − pivot·(s−1)`. At 100 % the pivot cancels, which is why it went unnoticed
for a long time.
> 🟡 The decoders document the pivot as "exactly half the decoded texture's
> dimensions (verified 7/7 on the tutorial bundle)". **That does not hold on
> `GP_TITLE`**: 38 of its 93 sprite-bearing `.t32` elements disagree, some
> grossly (`ptlogo_back2`, 1118×262, pivot 500,117 where half is 559,131). It is
> not a problem for this port — the exporter emits the declared pivot and never
> derives one — but it is a claim a consumer should not lean on. Raised in
> `docs/BLOCKED.md`.
**`sprite`** / **`focus_sprite`** are paths relative to `export/`. The highlight
pairs **by name** on the sprite — `ptbtn01.t32` ↔ `ptbtn01f.t32` — which is 🟡 a
naming convention that holds for all 54 real pairs on the disc, not a decoded
field.
**`opt_link`** is the raw `opt ` link inside the element's `.rat` record, carried
through unresolved. ⚠️ **It is not a focus link.** That reading was measured and
refuted: on the main menu it chains `ptloop01 → ptloop02 → ptbtn01`, across two
decorations and into a button. It is exported so whoever decodes it has it, and
named so nothing downstream mistakes it for navigation.
**`layer` / `layer_source`** are the paint-order key. `"sprite"` means it was
read from the `u16` at `+0x0A` of the element's `T8aD` header — a decoded disc
field. `"implied"` means the element carries no header and the key came from the
decoders' table of keys **measured off the running game**. `"none"` means neither
is known, and the element sorts last. A consumer that needs to know whether a
layer is a fact or a measurement reads `layer_source`.
**`size`** appears only on a `primitive`, which has no texture to take a size
from: the quad is `pivot × 2`, and its colour is the keyframe's `fade_argb`.
**`keyframes`** carry the on-disc time verbatim in `t`. A keyframe is the
**start of a ramp toward the next**, not a pose that is held, and the ramp is
linear. The **last keyframe of a group has no `t`** — the disc has no time slot
there — and a file that puts one on it is wrong, not merely odd. The unit of `t`
is measured, not on the disc, and so lives in `authored/` and is applied in
exactly one place.
**Two colours multiply.** `tint_rgba` is RGBA and is `0xffffffff` on essentially
every keyframe; `fade_argb` is **ARGB**, and its high byte is the alpha that ramps
during a fade. The byte order is in the key name because getting it backwards is
silent and looks like an art bug. The drawn modulate is their per-channel product.
**`rest`** is the resting pose: **the hold** — the longest run of consecutive
keyframes with an identical pose that does not end the group. Neither the first
nor the last keyframe, and not the longest-dwell frame either: a long gap after
keyframe *k* means the screen spends that time *arriving at* `k+1`.
**`paint_order`** is back-to-front, as declaration indices, and is a permutation
of them. It is the stable sort by `layer`. See `unresolved: paint_order_ties`.
**`buttons`** is navigation order: `button`-role elements sorted by resting Y.
This is **geometric, not a decoded neighbour graph** — the disc's real navigation
structure is unknown and `opt ` is *not* a focus link (measured and refuted). It
is right for a vertical menu and should not be trusted for anything else.
**`keyframes`** carry the on-disc time verbatim in `t`. A keyframe is the **start
of a ramp toward the next**, not a pose that is held. The unit of `t` is HANDOFF
Q1 and is unanswered — keep `t` raw so the conversion lives in exactly one place.
**`rest`** is the resting pose: the longest run of consecutive keyframes with an
unchanged value, falling back to longest-dwell. Neither the first nor the last.
structure is unknown. It is right for a vertical menu and should not be trusted
for anything else.
**`unresolved`** lists what this file does not answer; a consumer needing one of
those must get it from `authored/`.
those must get it from `authored/`. An empty list is a claim that nothing is
missing; an absent list is a gap, and `check` rejects it.
## `authored/screen_names.json`
Which build is which screen, keyed by archive and build index, each with a
`why`. The exporter reads this and stamps `name` / `name_source` / `name_why`
into the screen file. A build with no entry exports as `build_NN`.
## `authored/flow.json`
@@ -129,11 +233,31 @@ reaches which entry is Q4 and is not).
"format": "sylpheed.manifest/1",
"exporter": "sylpheed-export 0.1.0",
"formats_rev": "8b6dbcf",
"disc": "/disc",
"screens": [{ "name": "main_menu", "file": "screens/title/main_menu.json",
"sprites": 18, "missing_sprites": [] }],
"video_transcode": "ffmpeg -i ADV.wmv -c:v libtheora -q:v 8 -c:a libvorbis -q:a 5 ADV.ogv",
"warnings": ["GP_READY_ROOM not exported -- out of scope"]
}
```
`formats_rev` pins which decoders produced this export, and `video_transcode`
records the exact command so a modder can re-run it rather than reverse-engineer
what was done.
`video_transcode` will record the exact command so a modder can re-run it rather
than reverse-engineer what was done. It is absent until P4 writes a video.
## Changes from v1
v1 was written before HANDOFF answered Q1 and Q3, and before the two-colour
modulate was known. Each change below is a thing v1 could not have said.
| Change | Why |
|---|---|
| `rest.tint` (one `#rrggbbaa`) → `tint_rgba` **and** `fade_argb` | There are two modulate colours on the disc, in *different byte orders*, and they multiply. One field could not carry both, and a single `#rrggbbaa` silently discarded the alpha that every fade ramps. |
| `scale` is percent integers, not floats | It is a percent integer on the disc. Emitting `1.0` invents a precision the file does not have. |
| `paint_order` added, `"paint_order"` dropped from `unresolved` | Q3 decoded it: a `u16` layer key at `+0x0A`, stable-sorted. It is now derived, so it belongs in `export/` rather than `authored/`. `paint_order_ties` remains unresolved. |
| `layer` / `layer_source` added | Some keys are read from the file and some are measured off the running game. A consumer must be able to tell which. |
| `focus_sprite` now pairs by sprite **name**; `opt_link` exported raw | v1 implied `opt ` was the focus link. That was refuted. Pairing by name is the convention that survives. |
| `kind_raw` on every element, not only on `unknown` | The `0x3002` button test is not general and `kind & 0x4` changes whether an element draws at all. Both need the raw value present unconditionally. |
| `index`, `declared`, `parent`, `size`, `layer` added | Needed to reconstruct the screen: `paint_order` keys on `index`, primitives have no texture to take a size from, and `declared` keeps the disc's own spelling next to the derived `id`. |
| `name_why` required whenever `name_source` is `authored` | Rule 2. A name presented without its evidence is indistinguishable from a recovered one. |
| sprites moved from `sprites/*.png` to `sprites/<subdir>/<screen>/*.png` | Sprite names collide across builds. `main_menu` and `extras` both ship a `ptbase.t32`, and they are different pictures. |
| `unresolved` is required, and may be empty | An empty list is a claim; an absent one is a gap. |