97 lines
3.2 KiB
Markdown
97 lines
3.2 KiB
Markdown
# Asset Specification, Raw Assets, and Virtual Asset Contract Agenda
|
|
|
|
## Status
|
|
|
|
Open
|
|
|
|
## 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.
|
|
|
|
## 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?
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|