Variable Glyph Bank Palette Serialization

This commit is contained in:
2026-07-14 16:23:42 +01:00
parent 3f99e90ac8
commit 013ca4355c
18 changed files with 1237 additions and 1491 deletions
@@ -1,87 +1,185 @@
---
id: AGD-0005
ticket: variable-tile-bank-palette-serialization
title: Variable Tile Bank Palette Serialization
status: open
title: Variable Glyph Bank Palette Serialization
status: accepted
created: 2026-03-26
resolved:
decision:
resolved: 2026-07-14
decision: DEC-0038
tags:
- packer
- legacy-import
- tile-bank
- glyph-bank
- palette-serialization
- versioning
- rgba8888
- runtime-alignment
---
## Pain
The current tile-bank contract serializes a fixed block of `64` palettes in v1 even when an asset authors far fewer palettes.
Domain owner: `packer`, with runtime-facing impact through `assets.pa`.
That keeps decoding simple, but it wastes cartridge space and leaves the system with a deliberate mismatch between authored and serialized palette counts.
The current `GLYPH/indexed_v1` glyph-bank contract serializes a fixed block of
`64` palettes even when an asset authors far fewer palettes.
After `DSC-0038`, each palette entry is RGBA8888, so the fixed palette block is
now `64 * 16 * 4 = 4096` bytes. That keeps decoding simple, but it wastes
cartridge space and leaves a deliberate mismatch between authored palette count
and serialized palette count.
## Context
Legacy source: `docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md`
Domain owner: `docs/packer`
Cross-domain dependency:
- runtime
Current aligned v1 contract:
Runtime follow-up:
- `../runtime/discussion/workflow/decisions/DEC-0041-variable-glyph-bank-palette-protocol.md`
is accepted and normative for the runtime side.
- Runtime `DSC-0046` keeps `GLYPH/indexed_v1`, adopts variable glyph-bank
palette serialization, and treats this as an incompatible v1 correction.
- Runtime plans `PLN-0167` through `PLN-0172` are done and publish the
downstream handoff.
Current runtime-owned `GLYPH/indexed_v1` contract:
- pixels are serialized as packed `u4`;
- palettes are serialized as `RGB565 u16`;
- `palette_count = 64`;
- payload size includes a fixed `64 * 16 * 2` palette block.
- palettes are serialized as RGBA8888 values in runtime `R`, `G`, `B`, `A`
byte order;
- `palette_count` is the number of serialized and resident palettes;
- `palette_count` must be in `1..=64`;
- payload size includes exactly `palette_count * 16 * 4` palette bytes;
- palette index `0` is ordinary;
- each palette has 16 usable colors;
- transparency is represented by alpha, not by a reserved index or magenta
color-key;
- resident runtime memory materializes exactly `palette_count` palettes;
- `palette_id` is a direct palette identity inside the loaded glyph bank and is
valid only when `palette_id < palette_count`;
- sparse-to-dense palette remapping is not part of v1;
- missing palettes must fail explicitly in scene/sprite/composer use, not
silently resolve to a default color.
The packer now exposes:
Downstream producers must emit:
- `metadata.palette_count = 64`
- `metadata.palette_authored = <actual authored count>`
- root effective metadata fields `tile_size`, `width`, `height`, and
`palette_count`;
- `size = ceil(width * height / 2) + palette_count * 16 * 4`;
- `decoded_size = width * height + palette_count * 16 * 4`;
- exactly `palette_count * 16 * 4` RGBA8888 palette bytes;
- no `GLYPH/indexed_v2` payload for this change;
- no fixed 64-palette padding unless `palette_count = 64` and the payload
directly satisfies the runtime v1 contract;
- no effective runtime behavior based on `palette_authored`.
`DSC-0038` intentionally did not solve variable palette-count serialization.
It changed the color encoding from RGB565-era semantics to RGBA8888 and kept
the fixed 64-palette model stable for that wave.
Runtime `DEC-0041` now closes the cross-domain protocol questions that this
agenda previously carried as open. The remaining Studio/packer work is
downstream alignment with the runtime-owned contract.
## Open Questions
- [ ] Should variable palette serialization arrive as a new payload version or as an incompatible change to the current one?
- [ ] If `palette_count` becomes variable, should runtime still materialize a 64-slot resident bank, or truly shrink in-memory representation too?
- [ ] Should sparse authored palette indices remain sparse in serialization, or be canonicalized into a dense runtime block?
- [ ] Which domain owns compatibility for existing cartridges: `packer`, `runtime`, or `shipper`?
- [x] Should variable palette serialization arrive as a new payload version or
as an incompatible change to the current one?
- Runtime `DEC-0041` resolves this as an incompatible correction to
`GLYPH/indexed_v1`, with no v2 format.
- [x] If `palette_count` becomes variable, should runtime still materialize a
64-slot resident bank, or truly shrink in-memory representation too?
- Runtime `DEC-0041` resolves this: resident runtime memory materializes
exactly `palette_count` palettes.
- [x] Should sparse authored palette indices remain sparse in serialization, or
be canonicalized into a dense runtime block?
- Runtime `DEC-0041` rejects sparse-to-dense remapping. `palette_id` remains
direct identity inside the loaded glyph bank.
- [x] Should this repository create the owner agenda/decision for the runtime
side, or should a matching runtime `discussion/` artifact be opened before
implementation planning?
- Runtime `DSC-0046` now owns the protocol through accepted `DEC-0041`.
Studio/packer must follow that handoff.
- [x] Which domain owns compatibility for existing cartridges: `packer`,
`runtime`, or `shipper`?
- Runtime `DEC-0041` introduces no compatibility mode. Old payloads with
`palette_count = 64` remain valid only when they satisfy the new contract
directly.
## Options
### Option A - Keep fixed 64-palette serialization
### Option A - Keep fixed 64-palette serialization in v1
- **Approach:** Preserve the current fixed v1 payload with zero-filled unused palette slots.
- **Pro:** No runtime change and current specs/tests remain stable.
- **Con:** Every glyph bank keeps paying the full palette cost.
- **Con:** Every glyph bank keeps paying the full 4096-byte palette cost.
- **Maintainability:** Medium.
### Option B - Move to variable palette serialization now
- **Approach:** Serialize only authored palettes and shrink payload size immediately.
- **Pro:** Better cartridge efficiency and tighter semantics for `palette_count`.
- **Con:** Reopens a just-stabilized cross-domain runtime contract and forces compatibility decisions now.
- **Maintainability:** Medium if done carefully, risky if done incidentally.
### Option B - Align packer output with runtime variable palette serialization
- **Approach:** Keep the `GLYPH/indexed_v1` format name, serialize only
`palette_count` palettes, and make packer metadata, payload sizes, fixtures,
and Studio projections follow runtime `DEC-0041`.
- **Pro:** Removes fixed padding while the project is still in v1, keeps the
public format vocabulary stable, and makes runtime metadata match the payload.
- **Con:** Requires coordinated packer/spec/test changes and fixture
regeneration because the current producer still emits the old fixed-padding
shape.
- **Maintainability:** Strong if implemented as an explicit contract update,
weak if done as an incidental size tweak. Runtime has already closed the
protocol questions.
### Option C - Keep v1 fixed and design variable serialization for v2
- **Approach:** Preserve v1 stability now and open a later versioned follow-up for variable palette serialization.
- **Pro:** Keeps current work stable while preserving a clean path for future optimization.
- **Con:** Known waste remains in v1.
- **Maintainability:** Strong.
### Option C - Keep fixed external metadata but trim trailing palettes
- **Approach:** Keep some 64-slot assumptions in metadata or runtime memory, but
serialize only a shortened trailing subset of palettes in the payload.
- **Pro:** Can reduce cartridge size while limiting some runtime changes.
- **Con:** Creates a split-brain contract where serialized count, logical count,
and resident count can disagree.
- **Maintainability:** Weak. It preserves the ambiguity this agenda is trying
to remove.
## Discussion
The retained agenda recommendation is already clear: the waste is real, but it is not a correctness bug, and reopening the runtime-facing contract immediately would mix optimization work into a freshly stabilized path.
The retained concern is still valid after `DSC-0038`, but runtime `DEC-0041`
has now closed the protocol. The problem is no longer an open cross-domain
design question; it is a downstream producer-alignment task for Studio/packer.
That makes versioned follow-up a cleaner vehicle than incidental mutation of the current contract.
The old recommendation favored a versioned follow-up because compatibility and
runtime stability were treated as constraints. Runtime `DEC-0041` removes that
constraint: the project is still in v1, keeps `GLYPH/indexed_v1`, and does not
need compatibility for the old fixed 64-palette payload.
That makes Option B the required direction for this repository. Runtime already
changed the contract directly; Studio/packer must now emit the runtime-owned
shape and stop treating `palette_authored` or the old 64-padding model as
effective runtime behavior.
Option C should be avoided because it preserves multiple meanings for palette
count. If the payload becomes variable, `palette_count` should mean the number
of serialized palettes, not an unrelated fixed resident capacity.
## Resolution
Recommended direction: adopt **Option C**.
Recommended direction: adopt **Option B**.
Imported retained recommendation:
Updated recommendation:
1. keep the current fixed 64-palette contract for v1;
2. if variable serialization is desired, design it explicitly as a versioned follow-up;
3. treat compatibility, runtime representation, and sparse-vs-dense palette identity as explicit next-wave questions rather than silent payload tweaks.
1. keep the format name `GLYPH/indexed_v1`;
2. follow runtime `DEC-0041` as the protocol authority;
3. remove the fixed 64-palette payload block from packer output;
4. make packer `palette_count` describe the serialized and resident RGBA8888
palette count;
5. emit exactly `palette_count * 16 * 4` palette bytes;
6. update `size` and `decoded_size` formulas to use variable `palette_count`;
7. do not create a v2 format solely for this change;
8. do not preserve compatibility with the old fixed-padding payload;
9. do not introduce sparse-to-dense palette remapping metadata;
10. treat `palette_authored` as informative only unless a later runtime
decision promotes it to effective metadata;
11. add downstream fixture coverage for `palette_count = 1`, an intermediate
count, and `palette_count = 64`;
12. add a negative producer validation case for metadata/payload mismatch.
Next step suggestion: if the team wants to remove the fixed padding, open the corresponding runtime-side discussion and close the versioning/compatibility story before planning implementation.
Next step suggestion: convert this agenda into a Studio/packer decision that
references runtime `DEC-0041` and scopes implementation to specs, packer
payload emission, Studio projections if needed, tests, and fixtures.
@@ -1,273 +0,0 @@
---
id: AGD-0041
ticket: studio-packer-rgba8888-asset-pipeline
title: Agenda - Studio and Packer RGBA8888 Asset Pipeline Alignment
status: accepted
created: 2026-05-23
resolved: 2026-05-23
decision: DEC-0037
tags:
- studio
- packer
- assets
- glyph-bank
- palette
- rgba8888
- runtime-alignment
---
## Pain
Domain owner: `studio`, with direct subdomain ownership in `packer` and
cross-domain dependency on `runtime`.
The runtime RGBA8888 migration changes the color contract underneath the Studio
asset pipeline. Runtime `DEC-0029` says RGBA8888 is the single canonical logical
color and physical framebuffer format, and that asset packages must encode
palettes as RGBA8888 without preserving RGB565 compatibility.
Studio still carries RGB565 in the packer-facing asset pipeline:
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
defines `GLYPH/indexed_v1` palette payloads as `64 * 16 * 2` bytes of
little-endian `RGB565` values.
- `PackerPaletteV1` stores both `originalArgb8888` and `convertedRgb565`.
- `PackerGlyphBankWalker` drops partial alpha, treats alpha 0 and magenta as
transparent index `0`, stores only RGB identity for palette lookup, and
converts palette colors to RGB565.
- `PackerAssetDetailsService`, `PackerReadMessageMapper`, test fixtures, and
project `asset.json` files expose `convertedRgb565` as normal pipeline data.
The problem is not only changing one serializer. The Studio/packer side must
decide how authoring metadata, palette UI/data, emitted `assets.pa`, tests, and
existing project fixtures align with runtime RGBA channel order and meaningful
alpha.
## Context
Runtime discussion context:
- `../runtime/discussion/workflow/agendas/AGD-0037-rgba8888-framebuffer-and-pixel-format-direction.md`
was consulted as the originating discussion.
- `../runtime/discussion/workflow/decisions/DEC-0029-rgba8888-runtime-pixel-format-contract.md`
is accepted and normative for runtime.
- Runtime plans already split execution across specs, HAL/ABI, renderer,
asset palettes/tooling, host presentation, and validation.
Relevant runtime invariants for this Studio discussion:
- raw color values use RGBA channel order;
- asset package palettes must be RGBA8888;
- old RGB565 palette assets are not compatible runtime input;
- indexed tile/sprite payloads may remain indexed/paletized;
- transparency is represented by alpha in the resolved palette entry, not by
reserving palette index `0` as a special transparent index;
- RGB565 helpers may exist only as temporary migration utilities, not the
normal runtime path.
Relevant Studio/packer state:
- `assets.pa` is the authoritative runtime-facing artifact owned by the packer.
- `output.pipeline` is tooling-only by default, but current glyph palette data
lives there and is used by packer details/read flows.
- `GLYPH/indexed_v1` currently emits a fixed 256x256 packed `u4` pixel plane
plus a fixed 64-palette RGB565 block.
- `DSC-0005` is still open around variable tile-bank palette serialization.
That discussion optimizes fixed-vs-variable palette count. RGBA8888 changes
the color encoding and transparency semantics first, so it should supersede
or reframe any RGB565 assumptions before variable palette work continues.
- Studio scene publication currently carries `palette_id` in scene pack
requests. Scene payload shape is mostly unaffected by color format, but scene
previews, palette defaults, validation, and any editor-visible palette data
must remain consistent with the glyph-bank contract.
## Open Questions
- [x] Should Studio keep the runtime-facing format name `GLYPH/indexed_v1` and
make it an incompatible v1 contract update, or should packer emit a new
explicit format/version such as `GLYPH/indexed_rgba8888_v1`?
- Keep `GLYPH/indexed_v1`. The structural change is in palette encoding; the
remaining glyph payload model stays stable.
- [x] What is the canonical authoring-side palette field name: keep
`originalArgb8888`, rename to `rgba8888`, or store structured channel data?
- Use `rgba8888` unless the decision stage finds a concrete tooling reason to
choose a more explicit variant.
- [x] How should Java `BufferedImage` ARGB input be converted to runtime RGBA
raw values without confusing storage order, JSON numeric representation, or
signed `int` display in tooling?
- Convert ARGB input to RGBA output directly at the packer boundary.
- [x] Does palette index `0` remain an ordinary palette slot immediately, as
runtime `DEC-0029` requires, or does Studio need a temporary migration step to
rewrite existing transparent-index assets into alpha-bearing palette entries?
- Palette index `0` becomes an ordinary palette slot. Glyph palettes therefore
have 16 usable colors, not 15 plus a reserved transparent index.
- [x] Should magenta color-key support disappear from Studio authoring now, or
survive only as an explicit import/conversion helper outside the normal pack
path?
- Magenta color-key support should disappear completely.
- [x] Should partial alpha in PNG tiles become first-class palette data, or
should the packer still reject/diagnose partial alpha until renderer behavior
is fully proven?
- Partial alpha becomes valid palette data now. Existing validations and
warnings that flatten or reject partial alpha should be removed.
- [x] Which existing fixtures and sample projects should be regenerated versus
deleted because they encode RGB565-specific expectations?
- `main` and `fragments` will be regenerated manually later; they should not
block the Studio/packer decision.
- [x] How should this agenda relate to `DSC-0005`: close it as superseded,
revise it after RGBA8888, or keep it open as a later palette-count
optimization?
- `DSC-0005` remains a later step. RGBA8888 should not absorb variable
palette-count serialization.
## Options
### Option A - Minimal serializer swap inside current names
- **Approach:** Keep current public names and `GLYPH/indexed_v1`, replace the
palette block with fixed `64 * 16 * 4` RGBA8888 entries, remove
`convertedRgb565`, and update tests/specs in place.
- **Pro:** Smallest naming churn and likely the fastest path to unblock runtime
asset decode.
- **Con:** The `v1` label would silently change binary meaning, which is risky
for fixtures, docs, and any stale build output.
- **Maintainability:** Medium. Fast, but it relies on the repository accepting a
coordinated breaking change with no compatibility ambiguity.
### Option B - Explicit RGBA8888 glyph payload format
- **Approach:** Add an explicit runtime-facing glyph format/version for the
RGBA8888 palette payload, retire RGB565 output from the normal pack path, and
update asset declarations, specs, materialization, tests, fixtures, and sample
projects to the new format.
- **Pro:** Makes the breaking contract visible in file format names, tests, and
diagnostics while still obeying the runtime decision not to support RGB565 as
compatible input.
- **Con:** More code and fixture churn; requires clear migration handling for
stale project declarations and generated build artifacts.
- **Maintainability:** Strong. The format boundary becomes explicit and easier
to audit.
### Option C - Broaden the wave into full palette model redesign
- **Approach:** Use the RGBA8888 migration to redesign palette count, sparse vs
dense indices, material palettes, import/export, alpha authoring UI, and scene
palette defaults in one decision.
- **Pro:** Could produce a cleaner long-term asset model and resolve `DSC-0005`
at the same time.
- **Con:** Mixes a mandatory runtime alignment with optional model improvements,
increasing risk and delaying the renderer/asset migration.
- **Maintainability:** Weak for this wave. Better reserved for follow-up after
the RGBA8888 contract is stable.
## Discussion
The discussion converged toward an in-place `GLYPH/indexed_v1` structural
update rather than a new format name. This keeps the glyph-bank identity stable:
indexed pixels, fixed emitted sheet shape, scene `palette_id` references, and
the broad runtime glyph-bank model remain the same. The incompatible change is
the palette block and palette metadata moving from RGB565-derived values to raw
RGBA8888.
The authoring/read projection should expose `rgba8888` as the canonical palette
field. Java image inputs may still arrive as ARGB through `BufferedImage`, but
that is an input representation only. The packer boundary converts ARGB to
runtime RGBA and the rest of the pipeline should speak RGBA8888.
Palette index `0` is no longer special. It becomes a normal usable palette
entry, which gives glyph palettes 16 usable colors. Transparency comes from the
alpha byte in the RGBA8888 palette value. As a consequence, the old magenta
color-key behavior should be removed completely, not retained as a normal
authoring shortcut or hidden compatibility rule.
Partial alpha is valid data in this model. The packer should preserve it in the
palette instead of warning, flattening, or rejecting it. Existing validations
around partial alpha and the 15-color limit are therefore stale and should be
rewritten around the new 16-entry RGBA palette contract.
Existing sample projects and fixtures that still carry RGB565 assumptions are
not part of the discussion blocker. `main` and `fragments` will be regenerated
later. `DSC-0005` remains a separate future discussion for palette-count
serialization and should not be folded into this RGBA8888 wave.
## Tradeoffs
### Compatibility vs explicit break
Runtime `DEC-0029` already rejects RGB565 compatibility for this migration.
Studio therefore should not preserve RGB565 input as a normal path. The open
tradeoff is whether the packer should make the break visible through a new
format/version or simply mutate the existing v1 meaning.
### Authoring convenience vs runtime truth
Java image tooling naturally reads pixels as ARGB ints. Runtime wants raw RGBA
channel order. Studio can keep ARGB only as an import-side implementation detail,
but packer output, public metadata, and tests need one unambiguous RGBA8888
representation.
### Indexed art identity vs alpha semantics
The indexed/palette model can remain. What changes is that every palette entry,
including index `0`, should be a real RGBA color. Transparent pixels should be
encoded by alpha, not by a hardwired index rule or magenta color key.
### Scope control vs complete cleanup
It is tempting to combine RGBA8888 with variable palette serialization from
`DSC-0005`. That should be resisted unless the decision explicitly expands
scope. RGBA8888 changes bytes per palette entry and transparency semantics;
palette count optimization is a separate axis.
## Recommendation
Adopt a refined Option A.
The Studio/packer decision should keep `GLYPH/indexed_v1` as the runtime-facing
format name, but redefine its palette block and palette metadata around
RGBA8888. This is an intentional structural break in the palette contract, not
a new glyph-bank format.
The recommended shape for the decision is:
1. emit palette entries as raw RGBA8888 values in runtime RGBA channel order;
2. replace `convertedRgb565` with canonical `rgba8888` data in authoring and
read/detail projections;
3. treat Java/PNG ARGB as an input decoding detail and convert deliberately at
the packer boundary;
4. make palette index `0` ordinary, yielding 16 usable palette entries;
5. represent transparency and partial transparency only through RGBA alpha;
6. remove magenta color-key behavior completely;
7. remove partial-alpha flattening/rejection and preserve partial alpha as
valid palette data;
8. preserve fixed 64-palette serialization for this wave unless a decision
explicitly revises `DSC-0005`;
9. regenerate or rewrite RGB565 fixtures instead of supporting stale RGB565
assets at runtime.
## Next Step
The agenda is ready to move to decision if the refined recommendation is
accepted.
The next artifact should be a Studio/packer decision that references runtime
`DEC-0029`, leaves `DSC-0005` for a later palette-count step, and defines
propagation targets for:
- `docs/specs/packer`;
- `docs/specs/studio`;
- `prometeu-packer` models, walkers, serializers, services, fixtures, and
tests;
- sample project assets;
- any Studio asset workspace UI/read projections that expose palette data.
## Resolution
Accepted on 2026-05-23.
The discussion is closed in favor of decision `DEC-0037`. The accepted
direction keeps `GLYPH/indexed_v1`, moves its palette contract to RGBA8888,
uses `rgba8888` as the canonical palette field, makes palette index `0`
ordinary, removes magenta color-key behavior completely, accepts partial alpha
as valid palette data, and leaves `DSC-0005` for a later palette-count
serialization step.