Syplheed-Reborn/docs/re/structures/ui-paint-order-key.md

# The paint order comes from a layer key in the T8aD sprite header

**Status:** ✅ `CONFIRMED` on both screens whose paint order has been measured —
the key is **non-decreasing in paint order on every element that has a sprite**,
20 of 24 on one and 6 of 7 on the other. 🟡 ties are not explained. ❔ the field's
full meaning (it looks like flags, not a plain depth).

## The field

Every `T8aD` sprite begins with a 44-byte header. The word at **`+0x08`** —
untouched by this project's decoder, which reads width/height/tile-count at
`+0x14`/`+0x18`/`+0x1c` — sorts the screen.

Read in the order the game paints them (`ui-screen-runtime.md` has how that order
was measured — off the live child list, checked against a draw capture):

**`GP_TITLE` build 4, the title screen**

| paint slot | element | sprite | `+0x08` |
|---|---|---|---|
| 0 | 9 | `ptbase2` | `0x8000` |
| 3 | 10 | `pteff04` | `0x8020` |
| 5 | 6 | `pteff01` | `0x8040` |
| 6 | 20 | `ptlogo_back2eff` | `0x8081` |
| 7 | 19 | `ptlogo_back2` | `0x8082` |
| 8–12 | 14,15,18,16,17 | `back2eff1…5` | `0x8083` ×5 |
| 13–19 | 0,2,4,7,1,3,5 | `ptlogo1`/`tm`/`ptlogo2` | `0x80a0` ×7 |
| 20 | 22 | `ptlogoall_eff` | `0x80a8` |
| 21 | 23 | `ptlogoall_eff2` | `0x80a9` |
| 22 | 21 | `ptcopyright` | `0x8100` |

**`GP_TITLE` entries 11/14, the developer-logo splash**

| paint slot | sprite | `+0x08` |
|---|---|---|
| 1–3 | the three `_eff` glows | `0x a100` ×3 |
| 4–6 | the three base logos | `0x a110` ×3 |

Both are **ascending, with no inversion anywhere**. On the splash it explains the
whole permutation — the glows sort before their logos because `0xa100 < 0xa110`,
which is why the declaration table's interleaving (base, glow, base, glow) is not
what you see.

## Why this matters

It is the first **file-derivable** account of the paint order. Everything checked
before it failed: declaration order and its reverse, the placement region, the
RATC child order, keyframe start and rest times, resting Y, the runtime element
record's fields, and every other build's table. This is a per-sprite value the
port can read directly.

## What is not settled

* **Ties.** Two groups share a key (`0x8083` ×5 and `0x80a0` ×7) and the game
  paints them in an order that is *not* the declaration order —
  `14,15,18,16,17` and `0,2,4,7,1,3,5`. Something breaks those ties and it is not
  known. For the port it may not matter (tied elements are same-layer, and the
  three `ptlogo1`/`ptlogo2` instances are the ghosts that are not drawn at rest),
  but it is unmeasured, not proven harmless.
* **The field's meaning.** `0x8000`, `0x8020`, `0x8040`, `0x8081`… `0x8100` on
  one screen and `0xa100`/`0xa110` on another look like flag words with a layer
  in some of the bits rather than a plain integer depth. Sorting on the whole
  word works on both screens; which bits actually carry the layer is unknown.
* **Two screens is two screens.** A third measured permutation would either
  promote this to a rule or break it. The cheapest one available is any screen
  whose object is resident at the same time as the title's.


## Landed in the compositor (2026-08-19)

`ui_layout::compose` now paints in the **derived** order — a stable sort of the
elements by `sprite_layer_key` — for every build except the two whose measured
order is hard-coded, which stay as the ground truth they are. Elements with no
sprite (the `.prm` primitives) have no key; they keep their declaration position
among themselves and `compose` skips them anyway.

Verified three ways rather than by a green build:

* a disc-gated test asserts the measured orders are **non-decreasing** in the key
  and that the composite's key sequence comes out sorted — and it was checked
  both ways: reading the word from `+0x0c` instead of `+0x08` makes it fail;
* the title still composites identically (its measured order is used);
* a screen nobody has captured — `GP_MISSION_SELECT` — now composites cleanly
  ([capture](../captures/mission-select-derived-order.png)).

**Found on the way, and worth its own line:** the developer-logo splash bundle
has no `.rat` child, so `ui_layout::is_build` rejects it and the compositor never
sees it. Its measured order is therefore inert in practice, and the splash cannot
be rendered by `screen render` at all. That is a separate gap in what counts as a
"build", not a paint-order question.

## What the change did to the screens that were already verified (2026-08-19)

The derived order is applied to **every** build on the disc on the strength of
two measured screens, so the first thing owed to it is a check of what it did to
the screens the corpus had already validated against the running game. Two exist:
the tutorial PAUSE menu and the title main menu
(`../captures/ui-layout/pause-tutorial-real-vs-rebuilt.png`).

Rendered both ways — `compose` as committed, then with `compose` temporarily
reverted to declaration order — and diffed:

| screen | pixels differing | RMSE | max per-channel delta |
|---|---|---|---|
| tutorial PAUSE | 35 162 / 921 600 (3.8 %) | 0.52 % | 45 / 255 |
| title main menu | 9 911 / 921 600 (1.1 %) | 0.36 % | 34 / 255 |

**No layout regression.** Side by side the two renders are indistinguishable:
every panel, label and glyph is in the same place at the same size. What moved is
confined to pixels where translucent sprites overlap — the glows around PAUSE,
the OBJECTIVE / DEFEAT CONDITION / HINT header bars, the menu underlines — i.e.
the order the blends compose in, which is exactly what a paint-order change is
supposed to touch and nothing else.

🟡 **Which of the two is more faithful on these two screens is NOT settled.** A
difference of ≤45/255 on a few per cent of pixels is not decidable against the
committed side-by-side oracle, and there is no fresh framebuffer capture of
either screen to diff at that magnitude. The derived order is kept because it is
the rule measured off the game on the two screens where the order *is* known, not
because it was shown to be better here. If a capture of the PAUSE menu is ever
taken, this is the first thing to check it against.

### Corpus-wide, and not a no-op

A disc-gated test (`every_composite_paints_in_layer_key_order`) composes every
build on the disc and asserts the draw list is strictly increasing in
`(layer key, declaration index)`. It also counts how far the rule reaches:

> **341 of 965 builds (35 %) are reordered** by it.

That matters for how much credit the rule gets. Had it been a near-no-op, the two
measured screens would be the entire evidence base; instead a third of the disc's
screens now composite in an order no capture has checked. The test asserts the
share stays above a quarter, so a future change that quietly collapses the rule
back to declaration order fails here instead of passing silently.


## A third measured permutation — the main menu (2026-08-19)

Read off the running game with `tools/re-capture/screen_children.py`, and
identified in the file by its pivot signature: **`GP_TITLE.pak` ratc-index 8**,
the NEW GAME / LOAD GAME / TUTORIAL / OPTIONS / EXTRAS screen, 16 elements.

```
paint order (child slots): 1 3 4 2 5 8 9 6 7 15 10 11 12 13 14 0
```

| slot | element | | slot | element |
|---|---|---|---|---|
| 0 | 1 `ptbase.t32` | | 8 | 7 `ptframe2` |
| 1 | 3 `ptloop01` | | 9 | 15 `ptmsg` |
| 2 | 4 `ptloop02` | | 10–14 | 10–14 `ptbtn01`…`ptbtn05` |
| 3 | 2 `pteff05` | | 15 | **0 `pteff00.prm`** |
| 4 | **5 `pteff02.prm`** | | | |
| 5–7 | 8 `pteff10`, 9 `pteff12`, 6 `ptframe1` | | | |

**This is the first measured screen with TWO primitives**, and they land in
different places — which is the point. `pteff02.prm` (the 25 % black dim) paints
4th, beneath the whole UI; `pteff00.prm` (the screen-transition fade, resting
transparent) paints **last**. Both match their positions on the title screen
exactly, where `pteff02.prm` is also slot 4 and `pteff00.prm` is also last.

So a primitive's place is **per-element and stable by role** across screens:

| primitive | role | measured position |
|---|---|---|
| `palogo_eff0.prm` | opaque black backdrop | **first** (splash) |
| `pteff02.prm` | 25 % dim under the UI | **slot 4** (title *and* menu) |
| `pteff00.prm` | screen-transition fade | **last** (title *and* menu) |

It is still not *derived* — a primitive has no `T8aD` header and so no layer key
— but there are now three permutations to test a candidate against instead of
two, and the candidate has to live in the 60-byte declaration entry.

### Verified against the live capture

The order is wired into `measured_paint_order` (keyed by element names, so both
language builds get it). Composited with `--primitives` and edge-correlated
against a framebuffer capture taken in the same session
([capture](../captures/main-menu-oracle.png),
[composite](../captures/ui-layout/main-menu-composited.png)):

> **0.9591 at shift (0, 0)**

That is a *third* screen confirming the whole stack at once — paint order,
resting pose, `fade` alpha and primitives — on a capture this project had not
seen before.

### Not settled

* ❔ `ptframe1`/`ptframe2` rest at `0x00ffffff` (alpha 0) and are therefore not
  drawn, but the capture shows the menu frame plainly. Either the resting rule
  picks the wrong plateau for them or the frame is drawn by something else.
* ❔ The derivation for primitives. Three permutations now, still no rule.