137 lines
3.9 KiB
Markdown
137 lines
3.9 KiB
Markdown
---
|
|
id: PLN-0081
|
|
ticket: studio-packer-rgba8888-asset-pipeline
|
|
title: RGBA8888 Packer and Studio Spec Propagation
|
|
status: review
|
|
created: 2026-05-23
|
|
completed:
|
|
ref_decisions:
|
|
- DEC-0037
|
|
tags:
|
|
- specs
|
|
- packer
|
|
- studio
|
|
- rgba8888
|
|
---
|
|
|
|
## Objective
|
|
|
|
Propagate `DEC-0037` into the normative Studio and packer specifications before
|
|
code implementation starts.
|
|
|
|
## Background
|
|
|
|
`DEC-0037` keeps `GLYPH/indexed_v1` but changes its palette contract from
|
|
RGB565 to RGBA8888. Specs currently still describe RGB565 palette bytes,
|
|
`convertedRgb565`, and a 2048-byte palette block.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
|
|
- Update packer specs for `asset.json` palette metadata and `assets.pa`
|
|
glyph-bank payload layout.
|
|
- Update Studio asset workspace specs if they expose palette metadata or
|
|
details/read projection behavior.
|
|
- Preserve the fixed 64-palette model and explicitly leave `DSC-0005` for a
|
|
later palette-count optimization.
|
|
|
|
### Excluded
|
|
|
|
- Code changes.
|
|
- Test changes.
|
|
- Variable palette-count serialization.
|
|
- Runtime spec changes, except references to runtime `DEC-0029`.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Update asset declaration palette fields
|
|
|
|
**What:** Replace `originalArgb8888`/`convertedRgb565` examples and rules with
|
|
canonical `rgba8888`.
|
|
|
|
**How:** Edit the palette portions of the asset declaration spec so
|
|
`output.pipeline.palettes[*].palette.rgba8888` is the canonical field. State
|
|
that ARGB may be an input API detail but is not canonical authored/projected
|
|
palette data.
|
|
|
|
**File(s):**
|
|
|
|
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
|
|
|
### Step 2 - Update glyph-bank payload layout
|
|
|
|
**What:** Change `GLYPH/indexed_v1` palette layout from RGB565 to RGBA8888.
|
|
|
|
**How:** Keep the format name. Change the palette block from
|
|
`64 * 16 * 2 = 2048` bytes to `64 * 16 * 4 = 4096` bytes. Update size and
|
|
decoded-size formulas. State that palette entries use runtime RGBA channel
|
|
order.
|
|
|
|
**File(s):**
|
|
|
|
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
|
|
|
### Step 3 - Document alpha and index semantics
|
|
|
|
**What:** Document that palette index `0` is ordinary and all 16 palette entries
|
|
are usable.
|
|
|
|
**How:** Add normative rules that transparency and partial transparency are
|
|
encoded only by RGBA alpha, magenta color-key is removed, and partial alpha is
|
|
valid palette data.
|
|
|
|
**File(s):**
|
|
|
|
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
|
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
|
|
|
### Step 4 - Update Studio-facing projection rules
|
|
|
|
**What:** Ensure Studio-facing docs use `rgba8888` where palette metadata is
|
|
visible.
|
|
|
|
**How:** Update asset workspace language only where it describes palette read,
|
|
details, scene preview, or palette default behavior. Keep scene `palette_id`
|
|
semantics unchanged.
|
|
|
|
**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 `RGB565`, `convertedRgb565`, 2048-byte palette block,
|
|
reserved index `0`, and magenta color-key language.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Packer specs define `rgba8888` as the canonical palette field.
|
|
- [ ] `GLYPH/indexed_v1` remains named exactly that.
|
|
- [ ] Palette block formulas use `64 * 16 * 4 = 4096`.
|
|
- [ ] Specs state palette index `0` is ordinary and all 16 entries are usable.
|
|
- [ ] Specs state partial alpha is valid and magenta color-key is removed.
|
|
- [ ] Specs leave `DSC-0005` variable palette-count work out of scope.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on accepted `DEC-0037`.
|
|
- Should complete before code plans are implemented.
|
|
|
|
## Risks
|
|
|
|
- Leaving stale RGB565 examples in specs will make implementation review
|
|
ambiguous.
|
|
- Over-editing scene specs could accidentally imply a scene payload change that
|
|
`DEC-0037` does not authorize.
|