RGBA8888 Is the Canonical Studio and Packer Palette Contract

Original Problem

The runtime moved to RGBA8888 as the canonical logical color and framebuffer format, but Studio and packer still treated glyph-bank palettes as RGB565-era data. The old pipeline exposed convertedRgb565, preserved ARGB as normal projected metadata, reserved palette index 0 for transparency, flattened or discarded alpha semantics, and carried magenta color-key behavior as a hidden transparency shortcut.

That made the asset pipeline ambiguous. A glyph-bank asset could look valid to Studio while still carrying palette data that no longer matched the runtime contract.

Consolidated Decision

GLYPH/indexed_v1 remains the runtime-facing format name and keeps its indexed/paletized glyph-bank identity. The incompatible change is inside the palette contract:

rgba8888 is the canonical authored, projected, and emitted palette field.
RGBA8888 values are interpreted as 0xRRGGBBAA in runtime channel order.
Java BufferedImage ARGB values are input-only host API details and must be converted deliberately at the packer boundary.
Palette index 0 is ordinary. Glyph palettes have 16 usable entries.
Transparency, including partial transparency, is represented only by alpha.
Magenta color-key behavior is not a normal Studio or packer feature.
RGB565 is not a compatibility path for runtime-facing glyph-bank palettes.

Implementation Result

The packer specs now define glyph-bank palette metadata with rgba8888, and the binary GLYPH/indexed_v1 payload uses a 64 * 16 * 4 = 4096 byte palette block instead of the old 64 * 16 * 2 = 2048 byte RGB565 block.

The packer palette model now carries canonical RGBA8888 values. Image import converts Java ARGB pixels into runtime RGBA values before palette extraction, and palette identity includes alpha. This allows transparent and partially transparent colors to be distinct palette entries.

Packer read, detail, write, and cache paths now use rgba8888 as the normal metadata contract. Emission writes palette bytes in R, G, B, A order and no longer emits a synthetic magenta entry for index 0.

Tests and fixtures were updated to prove the new contract: RGBA channel order, alpha preservation, 16 usable colors, index 0 as ordinary data, magenta as ordinary color data, and 4096-byte palette blocks. Final validation confirmed that remaining stale-looking references are either normative "not supported" statements, historical discussion context, or explicitly out-of-scope generated project cache data.

Practical Pattern

When a host API exposes color in a different layout than the runtime contract, name the boundary explicitly and keep the canonical field runtime-oriented. For this pipeline:

accept host ARGB only at import/read time;
convert to RGBA8888 before storing palette metadata;
project rgba8888 to Studio and packer clients;
emit RGBA bytes directly into assets.pa;
convert back to UI-friendly ARGB only inside presentation code.

This keeps tooling convenient without letting host representation leak into the runtime asset contract.

Common Pitfalls and Anti-patterns

Do not treat originalArgb8888 as canonical pipeline data. ARGB can be a UI or image-input representation, but rgba8888 owns the contract.
Do not reintroduce convertedRgb565 as a normal projected field or emitted payload. RGB565 compatibility was deliberately rejected for this path.
Do not reserve palette index 0 for transparency. Alpha owns transparency.
Do not use magenta as a hidden color key. A magenta RGBA value is just color data unless an explicit future import tool defines a separate conversion.
Do not change scene palette_id semantics as part of color-format work. Scene records still reference glyph-bank palette indices.
Do not fold DSC-0005 variable palette-count work into RGBA8888 cleanup. Palette encoding changed here; palette-count optimization remains separate.

References

DEC-0037: Studio and Packer RGBA8888 Asset Pipeline Contract.
PLN-0081: Packer and Studio spec propagation.
PLN-0082: Palette model and ARGB conversion boundary.
PLN-0083: Glyph payload emission and size accounting.
PLN-0084: Packer projections and workspace APIs.
PLN-0085: Tests, fixtures, and conformance updates.
PLN-0086: Final integration and residue removal.
docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md.
docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md.
docs/specs/studio/4. Assets Workspace Specification.md.

4.8 KiB Raw Blame History