dev/glyph-bank-alignment (#3)
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
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>
This commit was merged in pull request #3.
This commit is contained in:
@@ -58,7 +58,7 @@ Rules:
|
||||
|
||||
Examples:
|
||||
|
||||
- `tile_bank`
|
||||
- `glyph_bank`
|
||||
- `sound_bank`
|
||||
|
||||
## Inputs
|
||||
@@ -92,8 +92,9 @@ Rules:
|
||||
|
||||
- `output.format` defines the semantic/runtime format contract;
|
||||
- `output.codec` defines storage/extraction behavior;
|
||||
- `output.codec` serialized values must use `SCREAMING_SNAKE_CASE`;
|
||||
- `output.metadata` carries runtime-relevant format-specific detail;
|
||||
- `output.pipeline` carries pipeline-injected metadata kept separate at authoring time;
|
||||
- `output.pipeline` carries tooling/build metadata kept separate at authoring time;
|
||||
- codec must remain explicit and must not be hidden inside format naming.
|
||||
|
||||
### Explicit Index Collections
|
||||
@@ -139,6 +140,8 @@ Rules:
|
||||
- declaration-time metadata may come from multiple sources under the asset contract (for example, format metadata, codec-related metadata, and build/pipeline-derived declarations);
|
||||
- `output.pipeline` may carry nested pipeline-derived metadata objects;
|
||||
- this segmentation exists for authoring clarity and does not define multiple runtime sinks;
|
||||
- `output.pipeline` is tooling-only and must not become part of the runtime-facing asset header by default;
|
||||
- pipeline-derived values required at runtime must be promoted explicitly into normative runtime-owned metadata fields;
|
||||
- runtime consumers must read effective metadata from the runtime asset entry metadata sink (`AssetEntry.metadata`);
|
||||
- convergence/normalization behavior is normative in the build artifact specification.
|
||||
|
||||
@@ -200,7 +203,7 @@ The `asset.json` schema is versioned independently from:
|
||||
- runtime-facing artifact schema
|
||||
- format contract versions
|
||||
|
||||
Format-specific contracts evolve through values such as `TILES/indexed_v1`.
|
||||
Format-specific contracts evolve through values such as `GLYPH/indexed_v1`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
|
||||
@@ -95,9 +95,15 @@ Baseline normalized metadata segmentation:
|
||||
|
||||
- `output.metadata` materializes at the metadata root;
|
||||
- `output.codec_configuration` materializes under `metadata.codec`;
|
||||
- `output.pipeline` materializes under `metadata.pipeline`;
|
||||
- `output.pipeline` remains tooling-only and must not materialize under `asset_table[].metadata` by default;
|
||||
- pipeline-derived runtime-required values must be promoted explicitly into normative runtime-owned metadata fields;
|
||||
- format-specific runtime-required fields may remain directly readable at the metadata root when the runtime consumer requires them there.
|
||||
|
||||
Asset entry codec serialization:
|
||||
|
||||
- `asset_table[].codec` MUST use `SCREAMING_SNAKE_CASE`;
|
||||
- the current known `NONE` value serializes as `NONE`.
|
||||
|
||||
### Preload
|
||||
|
||||
Preload is emitted deterministically from per-asset declaration.
|
||||
@@ -120,7 +126,7 @@ Rules:
|
||||
|
||||
- `build/asset_table.json` mirrors `header.asset_table` 1:1;
|
||||
- `build/preload.json` mirrors `header.preload` 1:1;
|
||||
- `build/asset_table_metadata.json` is tooling-only;
|
||||
- `build/asset_table_metadata.json` is tooling-only and may retain pipeline/build provenance that is intentionally excluded from the runtime header;
|
||||
- richer tooling data must not be added to the 1:1 mirror files.
|
||||
|
||||
## Alignment and Offsets
|
||||
@@ -139,15 +145,15 @@ Offset ambiguity guardrail:
|
||||
- internal pipeline indexing data (for example per-sample ranges for audio banks) must live under `asset_table[].metadata`;
|
||||
- internal indexing fields must not be interpreted as payload slicing fields.
|
||||
|
||||
## Format-Specific Baseline: `TILES/indexed_v1`
|
||||
## Format-Specific Baseline: `GLYPH/indexed_v1`
|
||||
|
||||
The first-wave producer contract for `TILES/indexed_v1` is fixed and runtime-aligned.
|
||||
The first-wave producer contract for `GLYPH/indexed_v1` is fixed and runtime-aligned.
|
||||
|
||||
### Tile Selection and Identity
|
||||
|
||||
Rules:
|
||||
|
||||
- only selected artifacts participate in the emitted tile bank;
|
||||
- only selected artifacts participate in the emitted glyph bank;
|
||||
- `1 artifact = 1 tile` in v1;
|
||||
- artifacts are normalized by ascending `artifacts[*].index`;
|
||||
- emitted `tile_id` equals the normalized artifact index;
|
||||
@@ -170,7 +176,7 @@ Rules:
|
||||
|
||||
Rules:
|
||||
|
||||
- the serialized payload for `TILES/indexed_v1` is:
|
||||
- the serialized payload for `GLYPH/indexed_v1` is:
|
||||
1. one packed `u4` pixel plane for the full emitted sheet;
|
||||
2. one palette block of `64 * 16 * 2 = 2048` bytes;
|
||||
- packed pixel bytes must be emitted by the packer, not inferred later by the runtime;
|
||||
@@ -183,7 +189,7 @@ Rules:
|
||||
Rules:
|
||||
|
||||
- emitted tile-bank entries use:
|
||||
- `bank_type = TILES`
|
||||
- `bank_type = GLYPH`
|
||||
- `codec = NONE`
|
||||
- tile-bank v1 metadata must expose at least:
|
||||
- `tile_size`
|
||||
@@ -202,7 +208,7 @@ Rules:
|
||||
- bank palettes are declared under `output.pipeline.palettes`;
|
||||
- each palette declaration uses the shape `{ "index": <int>, "palette": { ... } }`;
|
||||
- palette ordering is ascending numeric `index`, never raw array position;
|
||||
- palette ids in the emitted tile bank are the normalized declared palette indices;
|
||||
- palette ids in the emitted glyph bank are the normalized declared palette indices;
|
||||
- any tile in the bank may be rendered with any palette in the bank at runtime;
|
||||
- palette selection is a runtime draw concern, not a tile-payload embedding concern.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user