133 lines
3.6 KiB
Markdown
133 lines
3.6 KiB
Markdown
---
|
|
id: PLN-0087
|
|
ticket: variable-tile-bank-palette-serialization
|
|
title: Variable Glyph Palette Spec Propagation
|
|
status: open
|
|
created: 2026-07-14
|
|
completed:
|
|
ref_decisions:
|
|
- DEC-0038
|
|
tags:
|
|
- specs
|
|
- packer
|
|
- studio
|
|
- glyph-bank
|
|
- palette-serialization
|
|
---
|
|
|
|
## Objective
|
|
|
|
Propagate `DEC-0038` into the canonical Studio and packer specifications before
|
|
code changes start.
|
|
|
|
## Background
|
|
|
|
Runtime `DEC-0041` makes `palette_count` the serialized and resident palette
|
|
count for `GLYPH/indexed_v1`. Studio/packer `DEC-0038` adopts that runtime
|
|
contract downstream. Current packer specs still describe a fixed
|
|
`64 * 16 * 4 = 4096` palette block and `palette_count = 64`.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
|
|
- Update packer specs for glyph-bank metadata, payload layout, and size formulas.
|
|
- Update Studio specs only where Studio-facing palette count projection or asset
|
|
details are documented.
|
|
- Preserve RGBA8888 channel order, packed `u4` pixels, and `GLYPH/indexed_v1`.
|
|
|
|
### Excluded
|
|
|
|
- Code changes.
|
|
- Fixture regeneration.
|
|
- Runtime spec changes.
|
|
- Any `GLYPH/indexed_v2` design.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Update asset declaration metadata rules
|
|
|
|
**What:** Define `palette_count` as the effective runtime metadata field.
|
|
|
|
**How:** Update glyph-bank declaration language so `palette_count` means the
|
|
number of serialized and resident RGBA8888 palettes, constrained to `1..=64`.
|
|
State that `palette_authored`, if present, is informative and not runtime
|
|
effective.
|
|
|
|
**File(s):**
|
|
|
|
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
|
|
|
### Step 2 - Update glyph payload layout
|
|
|
|
**What:** Replace fixed 4096-byte palette block text.
|
|
|
|
**How:** Change the layout to `palette_count * 16 * 4` palette bytes and update
|
|
formulas to:
|
|
|
|
```text
|
|
size = ceil(width * height / 2) + palette_count * 16 * 4
|
|
decoded_size = width * height + palette_count * 16 * 4
|
|
```
|
|
|
|
**File(s):**
|
|
|
|
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
|
|
|
### Step 3 - Preserve v1 boundaries
|
|
|
|
**What:** Explicitly prohibit v2, compatibility padding, and remapping.
|
|
|
|
**How:** Add rules that this remains `GLYPH/indexed_v1`, old fixed-padding is
|
|
not a compatibility mode, and v1 has no sparse-to-dense palette remapping.
|
|
|
|
**File(s):**
|
|
|
|
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
|
|
|
### Step 4 - Update Studio-facing spec text
|
|
|
|
**What:** Align Studio projections if they mention palette count or fixed bank
|
|
shape.
|
|
|
|
**How:** Search the Studio asset workspace spec for palette projection, details,
|
|
or pack wizard language and update only stale fixed-count wording.
|
|
|
|
**File(s):**
|
|
|
|
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
|
|
- Not applicable for this spec-only plan.
|
|
|
|
### Integration Tests
|
|
|
|
- Not applicable for this spec-only plan.
|
|
|
|
### Manual Verification
|
|
|
|
- Search specs for stale normal-path `palette_count = 64`, `4096`, fixed
|
|
64-palette block, `GLYPH/indexed_v2`, and remapping language.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Packer specs define `palette_count` as runtime-effective `1..=64`.
|
|
- [ ] Packer specs use variable palette byte and size formulas.
|
|
- [ ] Specs keep `GLYPH/indexed_v1` and reject v2 for this change.
|
|
- [ ] Specs reject fixed-padding compatibility and sparse-to-dense remapping.
|
|
- [ ] Studio specs contain no stale fixed 64-palette projection wording.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on accepted `DEC-0038`.
|
|
- Should complete before code plans.
|
|
|
|
## Risks
|
|
|
|
- Leaving stale fixed 4096-byte examples will make implementation review
|
|
ambiguous.
|
|
- Over-editing Studio specs could imply UI behavior not required by `DEC-0038`.
|