Implement DEC-0084 with factory-only Sprite/Animator structs, complete result lowering, validated animation sidecars, generated PBS factories and JavaFX/MCP authoring through shared services. Qualify native dev/release with ordinary and optimized producers, zero-allocation playback, private-cycle reclamation, canonical Composer pixels, installed JARs and JavaFX lifecycle. Preserve the runtime checkout and existing host ABI.
11 KiB
Build Artifacts and Deterministic Packing Specification
Status: Draft
Scope: Runtime-facing artifacts and deterministic build behavior
Purpose: Define how the packer emits assets.pa and companion artifacts.
Authority and Precedence
This specification consolidates the initial packer agenda and decision wave into normative form.
Runtime-side reading semantics remain upstream in:
../runtime/docs/runtime/specs/13-cartridge.md../runtime/docs/runtime/specs/15-asset-management.md
Core Rules
assets.pais the authoritative runtime-facing artifact.- Companion JSON files do not replace the internal header as the runtime contract.
- The global asset table order is deterministic by increasing
asset_id. - The runtime-facing
asset_idis the same stableasset_idallocated by the packer registry.
assets.pa Structure
Baseline structure:
[fixed binary prelude]
[canonical JSON header]
[binary payload region]
Prelude Fields
The baseline prelude includes:
magicschema_versionheader_lenpayload_offsetflagsreserved
Rules:
flagsandreservedexist from day 1;flags = 0unless later specified otherwise;reserved = 0unless later specified otherwise;header_checksumis not part of the baseline envelope contract.
Canonical JSON Header
The header is serialized canonically.
Rules:
- UTF-8 encoding;
- no extra whitespace;
- object keys sorted lexicographically;
- arrays preserve declared order;
- canonicalization applies recursively;
- runtime-facing header values in v1 must avoid floating-point numbers.
Header Contents
The header carries:
asset_tablepreload
Asset Table
asset_table is emitted as a deterministically ordered list of asset entries.
Rules:
- one entry per included asset in the current build set;
- no secondary runtime-only identity layer;
- no synthetic dense reindexing layer;
asset_namemay remain present as logical/API-facing metadata;asset_nameis not the operational compile-time identity used by backend-owned symbolic asset surfaces.
Asset Entry Metadata Convergence
Each emitted asset entry has one runtime metadata sink: AssetEntry.metadata.
Rules:
- packer materialization must normalize all runtime-consumable metadata-producing sources into
asset_table[].metadata; - equivalent declaration/build inputs must produce equivalent normalized metadata;
- metadata key collisions across independent sources must fail build unless the family/format spec declares an explicit merge rule;
- normalization behavior must be testable and covered by conformance-oriented tests.
Baseline normalized metadata segmentation:
output.metadatamaterializes at the metadata root;output.codec_configurationmaterializes undermetadata.codec;output.pipelineremains tooling-only and must not materialize underasset_table[].metadataby 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[].codecMUST useSCREAMING_SNAKE_CASE;- the current known
NONEvalue serializes asNONE.
Preload
Preload is emitted deterministically from per-asset declaration.
Rules:
- assets with
preload.enabled = falsedo not appear in emitted preload data; - assets with
preload.enabled = truedo appear; - preload ordering is deterministic by increasing
asset_id.
Companion Artifacts
The baseline companion artifacts are:
build/asset_table.jsonbuild/preload.jsonbuild/asset_table_metadata.json
Rules:
build/asset_table.jsonmirrorsheader.asset_table1:1;build/preload.jsonmirrorsheader.preload1:1;build/asset_table_metadata.jsonis 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
Alignment exists only when explicitly required by spec.
Rules:
- there is no implicit baseline alignment beyond envelope and format requirements;
- any required alignment must be normative and visible;
- emitted offsets are always relative to the payload region, never the start of the full file.
Offset ambiguity guardrail:
asset_table[].offset/asset_table[].sizedescribe payload slicing insideassets.pa;- 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: GLYPH/indexed_v1
The producer contract for GLYPH/indexed_v1 is runtime-aligned and uses a
variable RGBA8888 palette block.
Tile Selection and Identity
Rules:
- only selected artifacts participate in the emitted glyph bank;
1 artifact = 1 tilein v1;- artifacts are normalized by ascending
artifacts[*].index; - emitted
tile_idequals the normalized artifact index; - duplicate or gapped artifact indices are build-blocking structural failures.
Emitted Sheet Shape
Rules:
- the emitted tile-bank sheet is always
256 x 256in v1; - tile placement within that emitted sheet is row-major;
- runtime
widthandheightfor the bank entry therefore refer to the full emitted sheet, not one individual artifact; - resulting per-bank capacities are:
tile_size = 8->1024tilestile_size = 16->256tilestile_size = 32->64tiles
- capacity overflow is a build-blocking structural failure.
Payload Layout
Rules:
- the serialized payload for
GLYPH/indexed_v1is:- one packed
u4pixel plane for the full emitted sheet; - one palette block of
palette_count * 16 * 4bytes;
- one packed
- packed pixel bytes must be emitted by the packer, not inferred later by the runtime;
- the palette block is serialized as RGBA8888 values in runtime RGBA channel order;
- each palette entry is emitted as four bytes in
R,G,B,Aorder; - payload interpretation must not depend on incidental per-artifact boundaries.
Runtime Entry Derivation
Rules:
- emitted tile-bank entries use:
bank_type = GLYPHcodec = NONE
- tile-bank v1 metadata must expose at least:
tile_sizewidthheightpalette_count
- tile-bank v1 requires
palette_countin the inclusive range1..=64; palette_countis the number of serialized palettes and resident runtime palettes for the bank;- tile-bank v1 size formulas are:
size = ceil(width * height / 2) + palette_count * 16 * 4decoded_size = (width * height) + palette_count * 16 * 4
- fixed 64-palette padding is not a compatibility mode unless
palette_count = 64and the payload directly satisfies the v1 contract; GLYPH/indexed_v2must not be introduced for this palette-count correction.
Palette Contract
Rules:
- bank palettes are declared under
output.pipeline.palettes; - each palette declaration uses the shape
{ "index": <int>, "palette": { ... } }; - each palette payload uses canonical
rgba8888entries interpreted as0xRRGGBBAA; - palette ordering is ascending numeric
index, never raw array position; - palette ids in the emitted glyph bank are direct declared palette indices;
- v1 has no sparse-to-dense palette remapping metadata;
- palette index
0is ordinary and may carry any RGBA8888 value; - glyph palettes have 16 usable entries;
- transparency and partial transparency are encoded only by RGBA alpha;
- magenta color-key behavior is not part of the normal glyph-bank contract;
- 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.
Format-Specific Baseline: SCENE/tilemap_v1
SCENE/tilemap_v1 is the wave-1 Scene Bank publication format.
Canonical Build Input
Rules:
- packer receives a canonical editor-agnostic Scene Bank request as its publication input;
- packer must not parse
TMX,TSX, or other editor-specific source files directly as part of runtime scene publication; - the request is produced by Studio from canonical scene state after canonical validation;
- equivalent requests must produce equivalent emitted
SCENEpayloads.
Baseline request shape:
ScenePackRequest
- version: int
- layers: [ScenePackLayerRequest; 4]
ScenePackLayerRequest
- active: bool
- glyph_asset_id: int
- tile_size: int
- parallax_factor_x: float
- parallax_factor_y: float
- width: int
- height: int
- tiles: List<ScenePackTileRequest>
ScenePackTileRequest
- active: bool
- glyph_id: int
- palette_id: int
- flip_x: bool
- flip_y: bool
Request Semantics
Rules:
- the request always materializes exactly
4layer entries in wave 1; tile_countis derived fromwidth * height;glyph_asset_idis the runtime-facing glyph dependency identity carried by the scene payload;activeat layer scope determines whether the layer participates in emitted scene output;activeat tile scope determines whether the tile contributes an active tile record to the emitted scene payload;palette_iduses a layer-owned editorial default with optional per-tile override before the request reaches packer;- packer consumes only the resolved per-tile
palette_idvalues present in the canonical request; - request-to-binary projection should remain as close to isomorphic as possible.
Wave-1 Constraints
Rules:
- wave 1 remains limited to exactly one logical tileset/glyph source per layer before request emission;
- packer does not own editor-format interoperability rules; it trusts the canonical request boundary once the request is structurally valid;
- binary reserved fields must not require corresponding request fields unless a later decision gives them editorial meaning.
Determinism
Equivalent build inputs must produce equivalent outputs.
Rules:
- no filesystem iteration dependence;
- no hidden defaults that affect output;
- no usage-based hot-first packing in the baseline contract;
- determinism is preferred over speculative physical-layout optimization.
Non-Goals
- per-format payload internals for every output family
- future locality optimization policy
- cartridge-level integrity/signature strategy
Exit Criteria
This specification is complete enough when:
- runtime-facing artifact authority is explicit;
- companion artifacts are bounded;
- emitted ordering and header behavior are deterministic.
Animation integration contract
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude animations.studio.json from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
See the complete animation contract.