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,228 +0,0 @@
---
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`.
@@ -0,0 +1,208 @@
---
id: DEC-0038
ticket: variable-tile-bank-palette-serialization
title: Variable Glyph Bank Palette Serialization for Studio and Packer
status: accepted
created: 2026-07-14
accepted: 2026-07-14
ref_agenda: AGD-0005
plans:
- PLN-0087
- PLN-0088
- PLN-0089
- PLN-0090
- PLN-0091
tags:
- packer
- studio
- glyph-bank
- palette-serialization
- rgba8888
- runtime-alignment
---
## Status
Accepted. Drafted from accepted agenda `AGD-0005` and accepted on
2026-07-14.
## Context
This decision belongs to the `packer` domain, with Studio-facing projection and
fixture impact. Runtime protocol ownership remains in `../runtime`.
Studio/packer already aligned glyph-bank colors with RGBA8888 through
`DSC-0038`. That work kept the `GLYPH/indexed_v1` format name and changed the
palette color encoding from RGB565-era data to RGBA8888 in runtime channel
order. It deliberately preserved the fixed 64-palette payload model for that
wave.
Runtime `DEC-0041` now changes the authoritative `GLYPH/indexed_v1` contract:
- `palette_count` is the number of serialized and resident palettes;
- `palette_count` MUST be in `1..=64`;
- payloads contain exactly `palette_count * 16 * 4` RGBA8888 palette bytes;
- `size = ceil(width * height / 2) + palette_count * 16 * 4`;
- `decoded_size = width * height + palette_count * 16 * 4`;
- resident runtime memory materializes exactly `palette_count` palettes;
- `palette_id` is direct identity within the loaded glyph bank and is valid
only when `palette_id < palette_count`;
- v1 has no sparse-to-dense palette remapping metadata;
- this remains `GLYPH/indexed_v1`, not a new v2 payload.
Studio/packer must now follow that runtime-owned contract as downstream
producers of runtime-conforming `assets.pa` payloads.
## Decision
Studio and packer SHALL adopt variable glyph-bank palette serialization for
`GLYPH/indexed_v1`, following runtime `DEC-0041` as the protocol authority.
Packer MUST stop emitting a fixed 64-palette block for glyph banks unless the
effective `palette_count` is actually `64`.
Packer MUST emit exactly `palette_count * 16 * 4` palette bytes for each
`GLYPH/indexed_v1` glyph-bank payload.
Packer MUST compute glyph-bank `size` as:
```text
size = ceil(width * height / 2) + palette_count * 16 * 4
```
Packer MUST compute glyph-bank `decoded_size` as:
```text
decoded_size = width * height + palette_count * 16 * 4
```
Packer MUST publish root effective metadata fields required by runtime:
- `tile_size`
- `width`
- `height`
- `palette_count`
For `GLYPH/indexed_v1`, `palette_count` MUST describe the number of serialized
RGBA8888 palettes and the number of resident palettes expected by runtime.
`palette_count` MUST be in the inclusive range `1..=64`.
Packer and Studio MUST NOT introduce `GLYPH/indexed_v2` for this change.
Packer and Studio MUST NOT preserve compatibility with the old fixed-padding
payload shape as a special mode.
Packer and Studio MUST NOT introduce sparse-to-dense palette remapping metadata
for v1.
`palette_authored`, when present in tooling or pipeline metadata, is
informative only. It MUST NOT be treated as effective runtime metadata unless a
later runtime decision promotes it.
Palette bytes SHALL remain RGBA8888 in runtime `R`, `G`, `B`, `A` byte order.
Palette index `0` and color index `0` remain ordinary indices. Transparency
remains represented by the alpha channel of the resolved RGBA8888 color.
## Rationale
Runtime owns the `GLYPH/indexed_v1` wire contract. Once runtime `DEC-0041`
accepted variable palette serialization, keeping packer output fixed at 64
palettes would make Studio/packer produce stale runtime payloads.
Making `palette_count` the effective serialized and resident count removes the
old mismatch between authored palette count and payload shape. The packer no
longer needs to pad every glyph bank to 4096 palette bytes unless the bank
really uses all 64 palettes.
Keeping the existing format name is correct because the project is still in v1
and runtime explicitly accepted this as an incompatible v1 correction. A v2
name would add migration surface without protecting any required compatibility
contract.
Rejecting sparse-to-dense remapping keeps `palette_id` direct. Scene, sprite,
packer output, and runtime lookup all refer to the same palette identity inside
the loaded glyph bank.
## Implications
### Specs
Packer specs MUST be updated so `GLYPH/indexed_v1` no longer describes a fixed
`64 * 16 * 4 = 4096` palette block as the normal payload shape.
Packer specs MUST define `palette_count` as the effective serialized palette
count for glyph banks, constrained to `1..=64`.
Studio specs MUST be updated only where Studio-facing projections, asset
details, pack wizard behavior, or fixtures expose the old fixed-padding model.
### Code
Packer payload emission MUST write only `palette_count` palettes.
Packer payload validation/materialization helpers MUST compute size and decoded
size from variable `palette_count`.
Packer metadata projection and Studio-facing read/detail APIs MUST expose the
runtime-effective `palette_count` correctly.
Studio code MUST NOT treat `palette_authored` as the runtime-effective count.
### Tests and Fixtures
Tests MUST cover:
- `palette_count = 1`;
- an intermediate `palette_count`;
- `palette_count = 64`;
- size and decoded-size formulas for variable counts;
- emitted RGBA8888 palette byte count;
- metadata/payload mismatch rejection or producer validation.
Fixtures that encode the old fixed-padding assumption MUST be regenerated or
updated unless they intentionally use `palette_count = 64` and satisfy the new
runtime contract directly.
### Non-goals
This decision does not change RGBA8888 channel order.
This decision does not change the packed `u4` indexed pixel plane.
This decision does not change scene `palette_id` payload shape.
This decision does not introduce v2, compatibility branches, or palette
identity remapping.
## 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 count projection is documented there.
- Code:
- packer glyph-bank payload emission;
- packer asset walking/materialization;
- packer read/detail projections;
- Studio asset details or pack wizard surfaces if they expose palette counts.
- Tests:
- packer parser, walker, materializer, workspace service, and fixture tests;
- Studio tests if Studio projections or UI logic expose palette counts.
- Docs:
- downstream implementation plans derived from this decision.
## References
- Agenda: `AGD-0005`
- Runtime decision:
`../runtime/discussion/workflow/decisions/DEC-0041-variable-glyph-bank-palette-protocol.md`
- Runtime handoff:
`../runtime/discussion/workflow/plans/PLN-0172-runtime-spec-handoff-to-packer-and-studio.md`
- Prior Studio/packer RGBA8888 lesson:
`discussion/lessons/DSC-0038-studio-packer-rgba8888-asset-pipeline/LSN-0053-rgba8888-is-the-canonical-studio-packer-palette-contract.md`
## Revision Log
- 2026-07-14: Initial accepted decision from `AGD-0005`, aligned with runtime
`DEC-0041`.