141 lines
4.2 KiB
Markdown
141 lines
4.2 KiB
Markdown
---
|
|
id: PLN-0089
|
|
ticket: variable-tile-bank-palette-serialization
|
|
title: Variable Glyph Palette Payload Emission and Size Accounting
|
|
status: open
|
|
created: 2026-07-14
|
|
completed:
|
|
ref_decisions:
|
|
- DEC-0038
|
|
tags:
|
|
- packer
|
|
- assets-pa
|
|
- glyph-bank
|
|
- payload
|
|
---
|
|
|
|
## Objective
|
|
|
|
Change packer `GLYPH/indexed_v1` payload emission from a fixed 64-palette block
|
|
to exactly `palette_count * 16 * 4` RGBA8888 bytes, with matching size and
|
|
decoded-size accounting.
|
|
|
|
## Background
|
|
|
|
`FileSystemPackerWorkspaceService` currently defines fixed palette constants
|
|
and emits a fixed `GLYPH_BANK_PALETTE_BYTES` block. `DEC-0038` requires packer
|
|
to emit only the runtime-effective palette count and compute asset table sizes
|
|
from that count.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
|
|
- Replace fixed palette byte constants with count-dependent formulas.
|
|
- Emit exactly `palette_count` palettes in RGBA byte order.
|
|
- Update asset table `size` and `decoded_size`.
|
|
- Reject metadata/payload mismatches.
|
|
|
|
### Excluded
|
|
|
|
- Palette model extraction changes covered by `PLN-0088`.
|
|
- Studio UI changes.
|
|
- Runtime code changes.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Replace fixed palette byte constants
|
|
|
|
**What:** Remove normal-path fixed `64 * 16 * 4` size assumptions.
|
|
|
|
**How:** Keep maximum constants such as `MAX_PALETTE_COUNT = 64`, but compute
|
|
payload palette bytes as `palette_count * 16 * 4` at each glyph-bank packing
|
|
boundary.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
|
|
|
### Step 2 - Emit variable palette bytes
|
|
|
|
**What:** Write only runtime-effective palettes.
|
|
|
|
**How:** Update palette byte generation to allocate
|
|
`palette_count * 16 * 4` bytes and fill direct palette ids from `0` through
|
|
`palette_count - 1`. Each color remains RGBA8888 in `R`, `G`, `B`, `A` order.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
|
|
### Step 3 - Update size and decoded-size formulas
|
|
|
|
**What:** Align asset table sizes with runtime `DEC-0041`.
|
|
|
|
**How:** Compute:
|
|
|
|
```text
|
|
size = ceil(width * height / 2) + palette_count * 16 * 4
|
|
decoded_size = width * height + palette_count * 16 * 4
|
|
```
|
|
|
|
Use these formulas for asset table entries, materializer expectations, and
|
|
workspace build outputs.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
|
|
|
### Step 4 - Reject metadata/payload mismatches
|
|
|
|
**What:** Prevent stale fixed-padding artifacts.
|
|
|
|
**How:** Add validation that emitted palette byte length, root metadata
|
|
`palette_count`, `size`, and `decoded_size` agree. Do not allow a fixed
|
|
64-palette block when `palette_count < 64`.
|
|
|
|
**File(s):**
|
|
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
|
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
|
|
- Assert emitted palette bytes for `palette_count = 1`, an intermediate count,
|
|
and `64`.
|
|
- Assert `size` and `decoded_size` formulas for variable counts.
|
|
- Assert RGBA byte order is unchanged.
|
|
|
|
### Integration Tests
|
|
|
|
- Build a workspace and inspect `assets.pa` asset table and payload length for
|
|
variable palette counts.
|
|
|
|
### Manual Verification
|
|
|
|
- Search for fixed normal-path `4096`, `64 * 16 * 4`, and
|
|
`GLYPH_BANK_PALETTE_BYTES` residue.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Glyph payloads emit exactly `palette_count * 16 * 4` palette bytes.
|
|
- [ ] Asset table `size` and `decoded_size` use variable formulas.
|
|
- [ ] RGBA byte order is unchanged.
|
|
- [ ] Fixed 64-palette padding is emitted only when `palette_count = 64`.
|
|
- [ ] Metadata/payload mismatch is rejected or impossible by construction.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0088`.
|
|
|
|
## Risks
|
|
|
|
- Updating metadata without payload length will corrupt runtime slicing.
|
|
- Updating payload length without decoded-size metadata will fail runtime asset
|
|
validation.
|