discussion framework migration
This commit is contained in:
@@ -0,0 +1,217 @@
|
||||
# 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`
|
||||
- `asset_uuid`
|
||||
- `name`
|
||||
- `type`
|
||||
- `inputs`
|
||||
- `output`
|
||||
- `preload`
|
||||
|
||||
The common contract may also include:
|
||||
|
||||
- `build`
|
||||
|
||||
## Meaning of `asset_uuid`
|
||||
|
||||
`asset_uuid` is the stable asset-local identity anchor.
|
||||
|
||||
Rules:
|
||||
|
||||
- it is required;
|
||||
- it must be stable across relocate and rename flows;
|
||||
- it is not the project-local runtime artifact identity;
|
||||
- it is not a substitute for registry-owned `asset_id`;
|
||||
- it exists so the asset root can preserve identity even when path-based assumptions drift;
|
||||
- it must remain compatible with packer reconcile behavior and migration flows.
|
||||
|
||||
## 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:
|
||||
|
||||
- `tile_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`
|
||||
- `output.pipeline`
|
||||
|
||||
Rules:
|
||||
|
||||
- `output.format` defines the semantic/runtime format contract;
|
||||
- `output.codec` defines storage/extraction behavior;
|
||||
- `output.metadata` carries runtime-relevant format-specific detail;
|
||||
- `output.pipeline` carries pipeline-injected metadata kept separate at authoring time;
|
||||
- codec must remain explicit and must not be hidden inside format naming.
|
||||
|
||||
### Explicit Index Collections
|
||||
|
||||
When `output.pipeline` carries ordered collections whose members need stable semantic identity, that identity must not depend on raw list position alone.
|
||||
|
||||
Rules:
|
||||
|
||||
- collections such as `output.pipeline.palettes` may remain JSON arrays for authoring ergonomics;
|
||||
- when a collection member has runtime- or packing-relevant identity, each entry must carry an explicit `index`;
|
||||
- `output.pipeline.palettes` entries must use the shape `{ "index": <int>, "palette": { ... } }`;
|
||||
- the packer must sort such entries by numeric `index`, not by physical array position;
|
||||
- duplicate or malformed indices are structural errors;
|
||||
- missing or malformed `palette` payloads are structural errors;
|
||||
- editorial reordering of the JSON array alone must not change semantic meaning.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"output": {
|
||||
"pipeline": {
|
||||
"palettes": [
|
||||
{
|
||||
"index": 0,
|
||||
"palette": {
|
||||
"originalArgb8888": [4294901760, 4278255360],
|
||||
"convertedRgb565": [63488, 2016]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Metadata Source Segmentation and Runtime Sink
|
||||
|
||||
`asset.json` may keep metadata segmented by concern during authoring.
|
||||
|
||||
Rules:
|
||||
|
||||
- declaration-time metadata may come from multiple sources under the asset contract (for example, format metadata, codec-related metadata, and build/pipeline-derived declarations);
|
||||
- `output.pipeline` may carry nested pipeline-derived metadata objects;
|
||||
- this segmentation exists for authoring clarity and does not define multiple runtime sinks;
|
||||
- runtime consumers must read effective metadata from the runtime asset entry metadata sink (`AssetEntry.metadata`);
|
||||
- convergence/normalization behavior is normative in the build artifact specification.
|
||||
|
||||
## 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.
|
||||
|
||||
## Operational State Exclusion
|
||||
|
||||
`asset.json` is a declaration artifact, not a catalog cache.
|
||||
|
||||
Rules:
|
||||
|
||||
- transient UI state must not be stored in `asset.json`;
|
||||
- registry-managed fields such as `asset_id` and `included_in_build` must not be duplicated into `asset.json`;
|
||||
- packer cache or snapshot bookkeeping must not be materialized into `asset.json` as normal operational state;
|
||||
- `asset.json` should remain focused on identity anchoring plus declared authoring/packing behavior.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user