145 lines
3.1 KiB
Markdown
145 lines
3.1 KiB
Markdown
# Asset Declaration and Virtual Asset Contract Specification
|
|
|
|
Status: Draft
|
|
Scope: Common `asset.json` contract
|
|
Purpose: Define the shared declaration model for raw and virtual assets.
|
|
|
|
## Authority and Precedence
|
|
|
|
This specification consolidates the initial packer agenda and decision wave into normative form.
|
|
|
|
## Core Rules
|
|
|
|
The common `asset.json` contract requires these top-level fields:
|
|
|
|
- `schema_version`
|
|
- `name`
|
|
- `type`
|
|
- `inputs`
|
|
- `output`
|
|
- `preload`
|
|
|
|
The common contract may also include:
|
|
|
|
- `build`
|
|
|
|
## Meaning of `name`
|
|
|
|
`name` is the logical asset reference label.
|
|
|
|
Rules:
|
|
|
|
- it is required;
|
|
- it is not the stable artifact identity;
|
|
- it may still be used by runtime-facing APIs and source-level workflows.
|
|
|
|
## Meaning of `type`
|
|
|
|
`type` identifies the authoring-side asset family.
|
|
|
|
Rules:
|
|
|
|
- it is not the runtime bank identity;
|
|
- the runtime-facing technical target belongs in `output.format`.
|
|
|
|
Examples:
|
|
|
|
- `image_bank`
|
|
- `sound_bank`
|
|
|
|
## Inputs
|
|
|
|
`inputs` is a structured object keyed by semantic role.
|
|
|
|
Rules:
|
|
|
|
- each key names an input role such as `sprites`, `palettes`, or `sources`;
|
|
- each value is a list of paths;
|
|
- paths are relative to the asset root;
|
|
- even a single input is represented as a list.
|
|
|
|
This model supports grouped virtual assets such as atlases and bank-style assets.
|
|
|
|
## Output
|
|
|
|
`output` is the runtime-relevant output declaration.
|
|
|
|
Required baseline fields:
|
|
|
|
- `output.format`
|
|
- `output.codec`
|
|
|
|
Optional baseline field:
|
|
|
|
- `output.metadata`
|
|
|
|
Rules:
|
|
|
|
- `output.format` defines the semantic/runtime format contract;
|
|
- `output.codec` defines storage/extraction behavior;
|
|
- `output.metadata` carries runtime-relevant format-specific detail;
|
|
- codec must remain explicit and must not be hidden inside format naming.
|
|
|
|
## Build
|
|
|
|
`build` is optional and process-oriented.
|
|
|
|
Rules:
|
|
|
|
- it may describe how authoring inputs are transformed or organized;
|
|
- if a parameter affects the runtime-facing output contract, it belongs in `output.metadata`;
|
|
- `build` must not hide runtime-relevant semantics.
|
|
|
|
## Preload
|
|
|
|
Each registered asset must declare preload intent explicitly.
|
|
|
|
Baseline shape:
|
|
|
|
```json
|
|
{
|
|
"preload": {
|
|
"enabled": true
|
|
}
|
|
}
|
|
```
|
|
|
|
Rules:
|
|
|
|
- `preload.enabled` is required and boolean;
|
|
- preload participation is declared, not inferred;
|
|
- richer preload policy fields are deferred.
|
|
|
|
## Defaults and Materialization
|
|
|
|
Defaults that affect runtime-visible behavior must not remain hidden.
|
|
|
|
Rules:
|
|
|
|
- runtime-relevant defaults should be materialized in `asset.json` whenever practical;
|
|
- if materialized later, the resulting artifact must expose effective values explicitly.
|
|
|
|
## Versioning
|
|
|
|
The `asset.json` schema is versioned independently from:
|
|
|
|
- registry schema
|
|
- runtime-facing artifact schema
|
|
- format contract versions
|
|
|
|
Format-specific contracts evolve through values such as `TILES/indexed_v1`.
|
|
|
|
## Non-Goals
|
|
|
|
- field-level format schemas for every output family
|
|
- rich preload policies
|
|
- source-language lowering behavior for asset references
|
|
|
|
## Exit Criteria
|
|
|
|
This specification is complete enough when:
|
|
|
|
- the common `asset.json` shape is stable;
|
|
- raw and virtual assets share a coherent baseline contract;
|
|
- format-specific specs can build on it cleanly.
|