--- id: DEC-0037 ticket: studio-packer-rgba8888-asset-pipeline title: Studio and Packer RGBA8888 Asset Pipeline Contract status: accepted created: 2026-05-23 accepted: 2026-05-23 ref_agenda: AGD-0041 plans: - PLN-0081 - PLN-0082 - PLN-0083 - PLN-0084 - PLN-0085 - PLN-0086 tags: - studio - packer - assets - glyph-bank - palette - rgba8888 - runtime-alignment --- ## Status Accepted. Drafted from accepted agenda `AGD-0041` and accepted on 2026-05-23. ## Context Runtime `DEC-0029` makes RGBA8888 the canonical logical color representation and physical framebuffer format for Prometeu. It also requires asset package palettes to use RGBA8888, rejects RGB565 compatibility as normal runtime input, and defines transparency through alpha rather than a reserved palette index. Studio embeds the packer and owns the asset authoring and publication pipeline that emits `assets.pa`. Before this decision, the Studio/packer glyph-bank path still carried RGB565 assumptions: - `GLYPH/indexed_v1` palette payloads were specified as fixed `64 * 16 * 2` RGB565 `u16` values. - `PackerPaletteV1` exposed `originalArgb8888` and `convertedRgb565`. - `PackerGlyphBankWalker` flattened partial alpha, treated alpha zero and magenta as transparent index `0`, limited authored colors to 15 usable entries, and converted colors to RGB565. - Studio/packer read projections, details APIs, fixtures, and sample assets exposed `convertedRgb565` as ordinary pipeline data. The runtime decision is already normative for the color contract. This decision locks how Studio and packer align their glyph-bank asset pipeline with it. ## Decision Studio and packer SHALL keep the runtime-facing glyph payload format name `GLYPH/indexed_v1`. The `GLYPH/indexed_v1` glyph-bank model SHALL remain indexed/paletized. Indexed pixel payloads, fixed emitted sheet shape, scene `palette_id` references, and the broad glyph-bank identity remain stable. The structural change is the palette contract. `GLYPH/indexed_v1` palette data MUST move from RGB565-derived values to RGBA8888 values in runtime RGBA channel order. Packer output, packer metadata, Studio read/detail projections, tests, and fixtures MUST stop treating RGB565 as the normal palette representation. `convertedRgb565` MUST be removed from the normal authored and projected palette contract. The canonical authored/projected palette field for this wave SHALL be `rgba8888`. Java `BufferedImage` and PNG inputs MAY be read as ARGB by host APIs, but ARGB is only an input representation. The packer boundary MUST convert ARGB input to runtime RGBA8888 output deliberately before emitting or projecting canonical palette data. Palette index `0` MUST be an ordinary palette index. Glyph palettes SHALL have 16 usable entries, not 15 usable entries plus a reserved transparent index. Transparency and partial transparency MUST be represented only by the alpha channel in the RGBA8888 palette value. Magenta color-key behavior MUST be removed completely from the normal Studio and packer asset pipeline. Magenta MUST NOT remain a hidden compatibility rule, normal authoring shortcut, or runtime-facing transparency encoding. Partial alpha in PNG/glyph inputs SHALL be valid palette data. Packer behavior that warns about, flattens, rejects, or otherwise strips partial alpha MUST be removed or rewritten around the RGBA8888 palette contract. The fixed 64-palette serialization model remains in scope for this wave unless another accepted decision explicitly revises it. `DSC-0005` remains a later palette-count serialization discussion and MUST NOT be folded into this RGBA8888 migration by implication. Existing `main` and `fragments` sample project assets may be regenerated manually later. Their regeneration is not a blocker for this decision and MUST NOT justify preserving RGB565 compatibility in the packer. ## Rationale Keeping `GLYPH/indexed_v1` avoids renaming a format whose core identity remains the same: indexed glyph pixels resolved through palettes. The incompatible part is specifically the palette encoding and transparency semantics. Making RGBA8888 the normal packer-side representation aligns Studio with runtime `DEC-0029` without introducing a parallel RGB565 compatibility path. This keeps the asset pipeline direct: authoring input is normalized once at the packer boundary, and emitted runtime artifacts carry the runtime color contract. Treating index `0` as ordinary is required because transparency now belongs to the alpha channel. This also gives each glyph palette the full 16 authored entries available from the indexed payload. Removing magenta color-key behavior avoids a second transparency mechanism that would conflict with meaningful alpha. Allowing partial alpha preserves source image information and supports the broader RGBA8888 renderer direction. Keeping fixed 64-palette serialization separates mandatory color-format migration from later payload-size optimization. Palette count and sparse/dense serialization remain independent questions. ## Technical Specification ### Runtime-Facing Glyph Payload - The format name remains `GLYPH/indexed_v1`. - The indexed pixel plane remains packed `u4`. - The emitted glyph-bank sheet shape remains unchanged for this wave. - The palette block changes from 2-byte RGB565 entries to 4-byte RGBA8888 entries. - The fixed palette block remains `64 * 16` entries for this wave. - The byte-size formula for the palette block MUST be updated from `64 * 16 * 2` to `64 * 16 * 4`. - Size and decoded-size formulas for glyph-bank payloads MUST be updated accordingly. - Palette bytes MUST be interpreted as runtime RGBA channel order. ### Authored and Projected Palette Data - Canonical palette data exposed by Studio/packer SHALL use `rgba8888`. - `convertedRgb565` SHALL be removed from normal authored pipeline metadata, details projections, read projections, fixtures, and tests. - `originalArgb8888` SHALL NOT be the canonical field for runtime-facing or packer-projected palette data in this wave. - ARGB values read from Java image APIs MUST be converted to RGBA8888 before entering canonical packer metadata or emitted payloads. ### Transparency and Alpha - Palette index `0` is ordinary. - A glyph palette has 16 usable entries. - Alpha `0`, alpha between `1` and `254`, and alpha `255` are all valid palette-entry states. - Partial alpha MUST be preserved as data. - Packer warnings or validations that describe partial alpha as flattened, ignored, or unsupported MUST be removed. - Color limit validation MUST be rewritten for 16 usable palette entries. ### Removed Behaviors - RGB565 palette emission is not a normal packer output. - RGB565 palette projection is not a normal Studio/packer read or details contract. - Magenta color-key transparency is not supported in the normal path. - Palette index `0` is not reserved for transparency. - Runtime asset compatibility with stale RGB565 palette payloads is not a Studio/packer requirement for this wave. ## Propagation Targets ### Specs - `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`, if Studio-facing palette read/projection behavior is documented there. ### Code - `prometeu-packer` palette model types. - `PackerGlyphBankWalker`. - `PackerAssetWalker` glyph-bank size and metadata calculations. - `PackerAssetDetailsService`. - `PackerReadMessageMapper`. - Any packer serializer/materializer that emits `assets.pa` glyph payloads. - Studio asset workspace read/detail surfaces that display or depend on palette metadata. ### Tests and Fixtures - Packer glyph-bank walker tests. - Asset declaration parser tests that mention `convertedRgb565`. - Runtime asset materializer tests. - File-system workspace service tests. - Fixture `asset.json` files that still declare RGB565-derived palette data. - Test expectations for alpha, 16 usable colors, and removed magenta color-key behavior. `main` and `fragments` project assets are expected to be regenerated manually later and are not blockers for this decision. ## Constraints - This decision MUST NOT introduce an RGB565 compatibility mode. - This decision MUST NOT rename the runtime-facing format away from `GLYPH/indexed_v1`. - This decision MUST NOT change scene `palette_id` semantics except as needed to ensure referenced glyph palettes now resolve RGBA8888 entries. - This decision MUST NOT decide variable palette-count serialization. - This decision MUST NOT close or revise `DSC-0005`; that discussion remains a later palette-count optimization track. - Any implementation plan derived from this decision MUST preserve all normative requirements above unless the user explicitly requests a decision revision. ## References - Agenda: `AGD-0041` - Runtime decision: `../runtime/discussion/workflow/decisions/DEC-0029-rgba8888-runtime-pixel-format-contract.md` - Related future discussion: `DSC-0005` ## Revision Log - 2026-05-23: Initial accepted decision from `AGD-0041`.