packer & compiler test
This commit is contained in:
@@ -7,6 +7,7 @@ This directory contains active packer discussion agendas.
|
||||
1. [`Tilemap and Metatile Runtime Binary Layout Agenda.md`](./Tilemap%20and%20Metatile%20Runtime%20Binary%20Layout%20Agenda.md)
|
||||
2. [`Pack Wizard Studio Decision Propagation Agenda.md`](./Pack%20Wizard%20Studio%20Decision%20Propagation%20Agenda.md)
|
||||
3. [`Tile Bank Packing Materialization Agenda.md`](./Tile%20Bank%20Packing%20Materialization%20Agenda.md)
|
||||
4. [`Variable Tile Bank Palette Serialization Agenda.md`](./Variable%20Tile%20Bank%20Palette%20Serialization%20Agenda.md)
|
||||
|
||||
The first packer agenda wave was consolidated into normative specs under [`../specs/`](../specs/) and didactic material under [`../learn/`](../learn/).
|
||||
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
# Variable Tile Bank Palette Serialization Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Active
|
||||
|
||||
## Domain Owner
|
||||
|
||||
- `docs/packer`
|
||||
|
||||
Cross-domain dependency:
|
||||
|
||||
- `../runtime`
|
||||
|
||||
## Purpose
|
||||
|
||||
Decide whether `tile bank` payloads should keep serializing a fixed block of `64` palettes in v1, or evolve to serialize only the palettes actually authored by the asset.
|
||||
|
||||
## Context
|
||||
|
||||
The current `tile bank` contract is aligned between `packer` and `runtime`:
|
||||
|
||||
- pixels are serialized as packed `u4`;
|
||||
- palettes are serialized as `RGB565 u16`;
|
||||
- `palette_count = 64`;
|
||||
- payload size is derived from `ceil(width * height / 2) + (64 * 16 * 2)`.
|
||||
|
||||
This means a `tile bank` with `1` authored palette still serializes `64` palette slots. Unused slots are currently zero-filled, which is valid for the runtime, but wastes cartridge space.
|
||||
|
||||
The packer now exposes:
|
||||
|
||||
- `metadata.palette_count = 64`
|
||||
- `metadata.palette_authored = <actual authored count>`
|
||||
|
||||
This makes the waste explicit, but does not remove it.
|
||||
|
||||
## Problem
|
||||
|
||||
The runtime-facing v1 contract favors fixed-size decode simplicity over cartridge efficiency.
|
||||
|
||||
We need to decide whether:
|
||||
|
||||
1. fixed `64` palette slots remain the normative contract for `tile bank`;
|
||||
2. `palette_count` becomes variable and payload size shrinks to the authored set;
|
||||
3. another staged strategy is better.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A: Keep Fixed 64-Palette Serialization
|
||||
|
||||
Keep the current contract unchanged:
|
||||
|
||||
- `palette_count` remains `64`;
|
||||
- every `tile bank` serializes `64 * 16 * 2 = 2048` bytes of palettes;
|
||||
- authored palettes populate their indexed slots;
|
||||
- unused slots are zero-filled.
|
||||
|
||||
### Option B: Move to Variable Palette Serialization
|
||||
|
||||
Evolve the contract so `tile bank` serializes only authored palettes:
|
||||
|
||||
- `palette_count` becomes the authored count;
|
||||
- payload size becomes `ceil(width * height / 2) + (palette_count * 16 * 2)`;
|
||||
- runtime validates and decodes variable palette blocks.
|
||||
|
||||
### Option C: Keep V1 Fixed, Design Variable Serialization for V2
|
||||
|
||||
Preserve the current runtime-facing v1 contract now, but explicitly open a v2 format/contract:
|
||||
|
||||
- v1 stays fixed at `64`;
|
||||
- v2 introduces variable palette serialization;
|
||||
- packer and runtime keep clear compatibility boundaries.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
### Option A
|
||||
|
||||
Pros:
|
||||
|
||||
- no further runtime work;
|
||||
- simplest decode path;
|
||||
- current specs and tests stay valid.
|
||||
|
||||
Cons:
|
||||
|
||||
- every `tile bank` pays the full 2 KB palette cost;
|
||||
- cartridge size is inflated for small authored palette sets;
|
||||
- the metadata now exposes a mismatch between authored and serialized counts by design.
|
||||
|
||||
### Option B
|
||||
|
||||
Pros:
|
||||
|
||||
- reduces cartridge size;
|
||||
- makes `palette_count` semantically tighter;
|
||||
- removes fixed empty palette padding from the payload.
|
||||
|
||||
Cons:
|
||||
|
||||
- requires coordinated changes in `packer`, `runtime`, specs, and tests;
|
||||
- changes the `size` / `decoded_size` formulas;
|
||||
- raises compatibility and migration questions for existing assets and cartridges.
|
||||
|
||||
### Option C
|
||||
|
||||
Pros:
|
||||
|
||||
- keeps current work stable;
|
||||
- makes room for a cleaner future contract;
|
||||
- avoids mixing optimization work into the current tile-bank rollout.
|
||||
|
||||
Cons:
|
||||
|
||||
- known waste remains in v1;
|
||||
- adds future format/version management work.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Recommendation for now: `Option C`.
|
||||
|
||||
Reasoning:
|
||||
|
||||
- the current fixed-size contract is already implemented and aligned;
|
||||
- the waste is real, but it is not a correctness bug;
|
||||
- changing it now would reopen a cross-domain runtime contract that was just stabilized;
|
||||
- if we want variable palette serialization, it should be introduced deliberately as a versioned follow-up, not as an incidental tweak.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should variable palette serialization be introduced as a new `tile bank` payload version, or as an incompatible change to the current one?
|
||||
2. If `palette_count` becomes variable, should runtime still materialize a 64-slot bank in memory, or truly shrink the resident representation too?
|
||||
3. Should palette slot identity remain sparse by authored `index`, or should serialization canonicalize into a dense runtime block?
|
||||
4. Which domain owns the compatibility story for existing cartridges: `packer`, `runtime`, or `shipper`?
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
If the team wants to eliminate the fixed 64-palette padding:
|
||||
|
||||
1. create a corresponding runtime agenda/decision;
|
||||
2. define the versioning and compatibility story;
|
||||
3. update `packer` and `runtime` specs together;
|
||||
4. then plan code changes in both domains.
|
||||
Reference in New Issue
Block a user