clean up
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 58.63% (16555/28235)
* Branch Coverage: 51.34% (6336/12341)
* Lines of Code: 28235
* Cyclomatic Complexity: 11205
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 585
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 58.63% (16555/28235)
* Branch Coverage: 51.34% (6336/12341)
* Lines of Code: 28235
* Cyclomatic Complexity: 11205
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 585
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
This commit is contained in:
@@ -1,97 +0,0 @@
|
||||
---
|
||||
id: AGD-0004
|
||||
ticket: tilemap-and-metatile-runtime-binary-layout
|
||||
title: Tilemap and Metatile Runtime Binary Layout
|
||||
status: open
|
||||
created: 2026-03-26
|
||||
resolved:
|
||||
decision:
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- tilemap
|
||||
- metatile
|
||||
- runtime-layout
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
The repository has conceptual alignment around map responsibility split and active-window residency, but still lacks a closed runtime binary contract for handheld maps.
|
||||
|
||||
Without a canonical decision:
|
||||
|
||||
- packer cannot close the output specification for map artifacts;
|
||||
- runtime lacks one stable reading baseline;
|
||||
- Studio cannot align authoring and preview schemas with one binary target.
|
||||
|
||||
## Context
|
||||
|
||||
Legacy source: `docs/packer/agendas/Tilemap and Metatile Runtime Binary Layout Agenda.md`
|
||||
|
||||
Domain owner: `docs/packer`
|
||||
Cross-domain impact:
|
||||
|
||||
- `docs/vm-arch`
|
||||
- `docs/studio`
|
||||
- `docs/compiler/pbs`
|
||||
|
||||
Current discussion premises retained from source:
|
||||
|
||||
- visual and collision concerns should remain separated;
|
||||
- map cells should not duplicate large metadata per tile;
|
||||
- only a `3x3` active window of maps should remain resident in memory;
|
||||
- a `64 KiB` target budget per map bank has been discussed;
|
||||
- `map bank` and `tileset bank` do not need identical size rules.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Is `collisionId` with `5` bits (`32` classes) sufficient for expected projects?
|
||||
- [ ] Should `flag0` be reserved for fast trigger semantics or contextual visual variation?
|
||||
- [ ] Which optional chunks belong in `V1`, and which should wait for a later version?
|
||||
- [ ] Must `map bank` stay strictly at `64 KiB`, or should capacity be variable with explicit metadata?
|
||||
- [ ] What compression policy should the packer adopt by default for the stream?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - `u8` cells with auxiliary tables
|
||||
- **Approach:** Store only one `metatileId` per cell and derive collision/flags from side tables.
|
||||
- **Pro:** Smallest RAM and I/O footprint.
|
||||
- **Con:** Pushes too much semantic meaning into external lookup tables.
|
||||
- **Maintainability:** Medium.
|
||||
|
||||
### Option B - `u16` bit-packed cells
|
||||
- **Approach:** Use `16` bits per cell, with a compact split such as `visualId`, `collisionId`, and `flag0`.
|
||||
- **Pro:** Balances compactness, deterministic decoding, and enough expressivity for many handheld cases.
|
||||
- **Con:** Leaves less room for inline per-cell growth than `u32`.
|
||||
- **Maintainability:** Strong.
|
||||
|
||||
### Option C - `u32` cells
|
||||
- **Approach:** Use larger cells to keep more event/flag space inline.
|
||||
- **Pro:** Highest flexibility for per-cell triggers and future expansion.
|
||||
- **Con:** Doubles memory cost versus `u16` without current evidence that it is needed.
|
||||
- **Maintainability:** Weak for the current budget target.
|
||||
|
||||
## Discussion
|
||||
|
||||
The retained source already converged toward `u16` as the best baseline.
|
||||
|
||||
The suggested runtime shape is:
|
||||
|
||||
- fixed map header;
|
||||
- contiguous cell stream;
|
||||
- optional future-proof chunks.
|
||||
|
||||
The proposed `U16_PACKED_V1` split keeps visual and collision references compact while preserving predictable memory usage and straightforward streaming behavior for a handheld target.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction: adopt **Option B** as the baseline.
|
||||
|
||||
Imported retained recommendation:
|
||||
|
||||
1. authorship stays JSON-oriented around compact ids;
|
||||
2. build output packs deterministically into `U16_PACKED_V1`;
|
||||
3. runtime active-window budget remains explicit;
|
||||
4. any move to `u32` should happen only through a later versioned encoding with evidence of need.
|
||||
|
||||
Next step suggestion: convert this agenda into a decision that closes `U16_PACKED_V1`, propagation to `docs/vm-arch`, Studio editing schema alignment, and implementation planning for roundtrip tests.
|
||||
Reference in New Issue
Block a user