Variable Glyph Bank Palette Serialization
This commit is contained in:
@@ -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`.
|
||||
Reference in New Issue
Block a user