Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/workflow/decisions/DEC-0037-studio-packer-rgba8888-asset-pipeline.md

9.0 KiB
Raw Blame History

id ticket title status created accepted ref_agenda plans tags
DEC-0037 studio-packer-rgba8888-asset-pipeline Studio and Packer RGBA8888 Asset Pipeline Contract accepted 2026-05-23 2026-05-23 AGD-0041
PLN-0081
PLN-0082
PLN-0083
PLN-0084
PLN-0085
PLN-0086
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.