bQUARKz
dd6c9dd718
All checks were successful
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 60.67% (15274/25176)
* Branch Coverage: 53.64% (5782/10779)
* Lines of Code: 25176
* Cyclomatic Complexity: 9960
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 545
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Reviewed-on: #3 Co-authored-by: bQUARKz <bquarkz@gmail.com> Co-committed-by: bQUARKz <bquarkz@gmail.com>
88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
---
|
|
id: AGD-0005
|
|
ticket: variable-tile-bank-palette-serialization
|
|
title: Variable Tile Bank Palette Serialization
|
|
status: open
|
|
created: 2026-03-26
|
|
resolved:
|
|
decision:
|
|
tags:
|
|
- packer
|
|
- legacy-import
|
|
- tile-bank
|
|
- palette-serialization
|
|
- versioning
|
|
---
|
|
|
|
## Pain
|
|
|
|
The current tile-bank contract serializes a fixed block of `64` palettes in v1 even when an asset authors far fewer palettes.
|
|
|
|
That keeps decoding simple, but it wastes cartridge space and leaves the system with a deliberate mismatch between authored and serialized palette counts.
|
|
|
|
## Context
|
|
|
|
Legacy source: `docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md`
|
|
|
|
Domain owner: `docs/packer`
|
|
Cross-domain dependency:
|
|
|
|
- runtime
|
|
|
|
Current aligned v1 contract:
|
|
|
|
- pixels are serialized as packed `u4`;
|
|
- palettes are serialized as `RGB565 u16`;
|
|
- `palette_count = 64`;
|
|
- payload size includes a fixed `64 * 16 * 2` palette block.
|
|
|
|
The packer now exposes:
|
|
|
|
- `metadata.palette_count = 64`
|
|
- `metadata.palette_authored = <actual authored count>`
|
|
|
|
## Open Questions
|
|
|
|
- [ ] Should variable palette serialization arrive as a new payload version or as an incompatible change to the current one?
|
|
- [ ] If `palette_count` becomes variable, should runtime still materialize a 64-slot resident bank, or truly shrink in-memory representation too?
|
|
- [ ] Should sparse authored palette indices remain sparse in serialization, or be canonicalized into a dense runtime block?
|
|
- [ ] Which domain owns compatibility for existing cartridges: `packer`, `runtime`, or `shipper`?
|
|
|
|
## Options
|
|
|
|
### Option A - Keep fixed 64-palette serialization
|
|
- **Approach:** Preserve the current fixed v1 payload with zero-filled unused palette slots.
|
|
- **Pro:** No runtime change and current specs/tests remain stable.
|
|
- **Con:** Every glyph bank keeps paying the full palette cost.
|
|
- **Maintainability:** Medium.
|
|
|
|
### Option B - Move to variable palette serialization now
|
|
- **Approach:** Serialize only authored palettes and shrink payload size immediately.
|
|
- **Pro:** Better cartridge efficiency and tighter semantics for `palette_count`.
|
|
- **Con:** Reopens a just-stabilized cross-domain runtime contract and forces compatibility decisions now.
|
|
- **Maintainability:** Medium if done carefully, risky if done incidentally.
|
|
|
|
### Option C - Keep v1 fixed and design variable serialization for v2
|
|
- **Approach:** Preserve v1 stability now and open a later versioned follow-up for variable palette serialization.
|
|
- **Pro:** Keeps current work stable while preserving a clean path for future optimization.
|
|
- **Con:** Known waste remains in v1.
|
|
- **Maintainability:** Strong.
|
|
|
|
## Discussion
|
|
|
|
The retained agenda recommendation is already clear: the waste is real, but it is not a correctness bug, and reopening the runtime-facing contract immediately would mix optimization work into a freshly stabilized path.
|
|
|
|
That makes versioned follow-up a cleaner vehicle than incidental mutation of the current contract.
|
|
|
|
## Resolution
|
|
|
|
Recommended direction: adopt **Option C**.
|
|
|
|
Imported retained recommendation:
|
|
|
|
1. keep the current fixed 64-palette contract for v1;
|
|
2. if variable serialization is desired, design it explicitly as a versioned follow-up;
|
|
3. treat compatibility, runtime representation, and sparse-vs-dense palette identity as explicit next-wave questions rather than silent payload tweaks.
|
|
|
|
Next step suggestion: if the team wants to remove the fixed padding, open the corresponding runtime-side discussion and close the versioning/compatibility story before planning implementation.
|