80 lines
2.3 KiB
Markdown
80 lines
2.3 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.
|
|
|
|
## 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?
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|