Sylpheed-Godot/docs/FORMAT.md

The open export format — v3

The format the disc is converted into, and the one the Godot project and any modding tool read. It is versioned, so a change is a deliberate act with a version bump, not a silent edit. Changes from v2 and Changes from v1 are at the bottom, with a reason for each.

Design rules, in priority order:

1. A human can read and edit it. Modding is a goal of this port, which makes the layout part of the product rather than a temp directory.
2. Names, never hashes. Where the disc's own name was never recovered — the six *2D archives and GP_READY_ROOM — emit a stable synthetic id and say 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, 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/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
  cue_bindings.json         # which cue fires on move / confirm / back

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

{
  "format": "sylpheed.screen/3",
  "exporter": "sylpheed-export 0.1.0",
  "formats_rev": "8b6dbcf",
  "source": { "archive": "dat/GP_TITLE.pak", "entry": 5, "build": 5 }
}

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

{
  "format": "sylpheed.screen/3",
  "exporter": "sylpheed-export 0.1.0",
  "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",
      "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],
      "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], "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": ["keyframe_time_unit", "paint_order_ties", "fade_out_duration"]
}

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.

focus is the focused state, and it supersedes focus_sprite. A focused button is not a sprite swap: ptbtn0Nf.rat is a nested .rat leaf declaring two elements — the spinning ring ptbtneff01.t32 and the bright label — and the parent bundle declares no element for the record at all, so the leaf is the only source of placement for both and there is nothing for it to inherit.

"focus": {
  "record": "ptbtn04f.rat",
  "elements": [
    { "id": "ptbtneff01", "sprite": "…/ptbtneff01.png", "pivot": [21, 23],
      "rest": { "pos": [500, 396], "rotation_deg": 0, "t": 120, … },
      "keyframes": [ { "t": 120, "rotation_deg": 0, … },
                     { "rotation_deg": 360, … } ] },
    { "id": "ptbtn04f", "sprite": "…/ptbtn04f.png", "rest": { "pos": [535, 395], … } }
  ]
}

Elements are back-to-front in the leaf's own declaration order — ring first, then label. Positions are absolute design-space top-left, not offsets from the button.

The label's (−7, −7) against its base is load-bearing, not noise: ptbtn0Nf.t32 is 13 px larger per axis, and −7 keeps the two concentric (535 + 96/2 = 583 against 542 + 83/2 = 583.5). Drawing the highlight at the base position pushes it 7 px down-right and off-centre.

⚠️ Leaf placement is authoritative for an f record and NOT for a base record. A base record's leaf duplicates its parent's placement and the two can disagree by a unit (ptbtn04: parent y=401, leaf y=402) — there the parent wins. The f record is the case where the parent declares nothing.

❔ The ring spins, and its period is unresolved. Its two keyframes differ in rotation_deg alone, 0 → 360. But the second is untimed, and what an untimed keyframe means inside a leaf — as opposed to at screen level, where it is the exit ramp — is untested. A consumer should draw the resting angle rather than invent a spin rate. This is listed in unresolved.

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.

rotation_deg is screen-plane rotation in degrees, clockwise-positive, decoded from the keyframe's +12. The game renders it, confirmed twice by the RE agent on different screens and different elements: the title's ptloop sweeps declare +30 / −45 and a GPU capture submits their quads at +30.26 / −45.28, and the main menu's focus ring ramps 0 → 360 with position, scale, alpha and tint all constant — a capture caught it mid-spin.

Rotation is about the declared pivot, which is measured rather than assumed: the ptloop sweeps scale 600 %/800 % vertically, where the pivot term is worth 450 and 630 px, and the capture puts both quad centres at y 359.1/360.0 against the pivot formula's 360.0 (top-left predicts 810/990, centre-as-position predicts 270).

⚠️ sylpheed-cli screen render does not draw rotation yet — its blit is axis-aligned. A rotation disagreement between it and a consumer that does draw rotation means the CLI is behind, not that the consumer is wrong.

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.

⚠️ rest is a heuristic over the keyframes, and it misfires. The rule excludes a run that ends the group, because that run is usually the exit. On an element with no exit animation the trailing run is the hold, and the rule then falls back to an earlier run — usually the invisible pre-roll. Six elements in this export are affected, and the condition that identifies them exactly is "the final untimed keyframe has the same pose as the last timed one": ptframe1/ptframe2 on both main menus, and pteff02 on both titles. A live capture of the running main menu shows ptframe1/ptframe2 on screen; rest says they are invisible.

A consumer that wants the pose after arrival should therefore take the last timed keyframe, not rest. rest is kept in the format because it is what the pinned decoders say and removing it would hide the disagreement — see docs/DECISIONS.md. The format is unchanged at v2: no field changed meaning, this is a warning about one of them.

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. 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/. 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

{
  "format": "sylpheed.flow/1",
  "boot": ["splash_developer", "intro_video", "title", "main_menu"],
  "screens": {
    "main_menu": {
      "actions": {
        "ptbtn01": { "label": "NEW GAME", "goto": "new_game_intro",
                     "why": "label read off the sprite; target is a placeholder for HANDOFF Q4" }
      }
    }
  }
}

goto may name an exported screen or a GamePart id from the executable's own table (29 entries at .rdata 0x820A1630 — that table is a disc fact; which button reaches which entry is Q4 and is not).

export/manifest.json

{
  "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"]
}

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 v2

v2 was written before the keyframe's +12 was decoded and before anyone could reach a .rat leaf through the public decoder API.

Change	Why
rotation_deg on every keyframe and on rest	Decoded at keyframe +12, and the game draws it — confirmed on two different screens with two different elements against GPU captures. Dropping it would have made the focus ring's whole animation invisible.
focus (a record with its own elements) added; focus_sprite kept but demoted	The focused state is two elements in a nested leaf, not one sprite. v2's single focus_sprite could not carry the ring at all, and drew the highlight label 7 px off-centre by inheriting the base's position. focus_sprite stays because it is still the 54-pair naming convention and a consumer may want the bare texture.
unresolved gains focus_ring_spin_period	The ring's rotation ramps 0 → 360 across two keyframes whose second is untimed. The screen-level rule for an untimed keyframe (the exit ramp) is not established to apply inside a leaf, so the period is unknown and is not being invented.

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.