141 lines
5.4 KiB
Markdown
141 lines
5.4 KiB
Markdown
# Asset Specification, Raw Assets, and Virtual Asset Contract Agenda
|
|
|
|
## Status
|
|
|
|
Closed
|
|
|
|
Resolved by [`002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md`](../decisions/002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md).
|
|
|
|
## Purpose
|
|
|
|
Define the contract of `asset.json`, including the split between raw assets, virtual assets, and format-specific output specs.
|
|
|
|
## Context
|
|
|
|
The draft already proposes:
|
|
|
|
- `asset.json` as the anchor spec,
|
|
- common fields for all assets,
|
|
- explicit pipeline declaration for virtual assets,
|
|
- future format families such as `TILES/indexed_v1` and `SOUNDS/pcm16le_v1`.
|
|
|
|
This needs decomposition into a stable common contract plus future format-specific specs.
|
|
|
|
This agenda assumes the managed asset is the asset root described by one `asset.json`.
|
|
That root may aggregate multiple source inputs.
|
|
|
|
Important example:
|
|
|
|
- an atlas or image bank asset may contain many source sprites plus one or more palettes;
|
|
- one `asset.json` describes the whole managed asset and its final packed output;
|
|
- the internal source files are inputs of that asset, not separate assets unless explicitly modeled that way.
|
|
|
|
The runtime-facing extraction path also depends on codec information.
|
|
Because codec affects how runtime opens, decodes, or materializes payload bytes, codec must be explicit in the asset contract rather than hidden inside format naming.
|
|
|
|
Preload intent is also asset-level information.
|
|
Each managed asset should carry an explicit entry indicating whether it participates in preload, so preload inclusion is declared intentionally rather than inferred indirectly later in the pipeline.
|
|
|
|
## Source Sections
|
|
|
|
- `5.3 Asset Types (Bank Targets)`
|
|
- `5.4 Raw vs Virtual Assets`
|
|
- `7. Asset Specification: asset.json`
|
|
- `14. Virtual Assets (Deep Explanation)`
|
|
|
|
## Key Questions
|
|
|
|
1. Which fields belong to every `asset.json` regardless of type?
|
|
2. Which parts of the file are common packer contract versus format-specific contract?
|
|
3. How explicit must virtual build steps be?
|
|
4. Where should defaults live, and when must they be materialized?
|
|
5. Is `type` the bank target, the user-facing kind, or both?
|
|
6. How should packer version output formats independently from registry and descriptor schemas?
|
|
7. How should one `asset.json` declare many internal inputs that together form one virtual asset, such as an atlas plus palettes?
|
|
8. Should codec be part of `output.format`, or a separate explicit field in the output contract?
|
|
9. How should each asset declare preload intent so the packer can materialize runtime preload entries deterministically?
|
|
|
|
## Options
|
|
|
|
### Option A
|
|
|
|
Keep a small common `asset.json` contract and push all output-specific rules into dedicated format specs.
|
|
|
|
### Option B
|
|
|
|
Keep a richer monolithic `asset.json` contract in one central spec.
|
|
|
|
## Tradeoffs
|
|
|
|
- Option A scales better as new asset formats are added.
|
|
- Option A keeps the core packer spec smaller and more stable.
|
|
- Option B looks simpler initially but becomes harder to evolve without coupling unrelated formats together.
|
|
|
|
## Recommendation
|
|
|
|
Adopt Option A:
|
|
|
|
- a compact common `asset.json` contract,
|
|
- format-specific normative specs for each output family,
|
|
- explicit virtual asset declarations with deterministic materialization rules.
|
|
|
|
Also adopt this modeling direction:
|
|
|
|
- `asset.json` describes the managed output unit;
|
|
- many internal source files may feed that single managed output;
|
|
- atlas/image-bank style assets should be modeled as one asset with many inputs rather than many implicit sibling assets.
|
|
|
|
Also adopt this output-contract direction:
|
|
|
|
- `output.format` identifies the semantic/runtime format contract;
|
|
- `output.codec` identifies how payload bytes are stored for extraction/materialization;
|
|
- codec must remain explicit because it affects runtime extraction behavior;
|
|
- codec should not be smuggled into format naming when it represents a distinct storage concern.
|
|
|
|
Also adopt this preload direction:
|
|
|
|
- each managed asset must expose an explicit preload-related declaration entry;
|
|
- preload participation must be declared, not inferred from ad hoc conventions;
|
|
- packer build must use that declaration to decide whether preload data is emitted into the runtime-facing artifact contract.
|
|
- `preload.enabled` should be the required runtime-relevant boolean;
|
|
- richer packer-side preload metadata may exist, but it must not change runtime behavior until separately specified.
|
|
|
|
Current recommended shape:
|
|
|
|
```json
|
|
{
|
|
"preload": {
|
|
"enabled": true,
|
|
"policy": "boot_critical"
|
|
}
|
|
}
|
|
```
|
|
|
|
Direction:
|
|
|
|
- `enabled` is the normative yes/no input for runtime preload emission;
|
|
- optional fields such as `policy` are packer-side hints for Studio, diagnostics, planning, or future evolution;
|
|
- packer-side preload hints must not silently alter the current runtime-facing preload contract.
|
|
|
|
## Expected Decisions to Produce
|
|
|
|
1. Common `asset.json` schema boundary.
|
|
2. Raw versus virtual asset contract.
|
|
3. Versioning strategy for asset format specs.
|
|
4. Rules for defaults and explicit materialization.
|
|
5. Multi-input asset declaration model for atlas, bank, and similar grouped assets.
|
|
6. Explicit separation between output format and codec in the asset contract.
|
|
7. Asset-level preload declaration model.
|
|
|
|
## Expected Spec Follow-up
|
|
|
|
- Common asset specification spec.
|
|
- Virtual asset contract spec.
|
|
- Format-specific specs such as `TILES/indexed_v1`.
|
|
|
|
## Non-Goals
|
|
|
|
- Final CLI UX for authoring these files.
|
|
- Incremental build internals.
|
|
- Cartridge builder consumption details.
|