Add shared human/task asset batches with reviewed atomic publication, explicit reference rebinds, ownership inspection and qualified glyph/scene budgets. Expose the same authoring and capacity results through Assets and MCP. Deliver isolated guest test targets, retained visual evidence and immutable runtime lifecycle/control observations. Preserve provider qualification and installed authoring examples alongside the completed discussion lessons. Close AGD-106 coordination and the delivered discussion workflows through housekeeping, updating lesson references and preserving qualification limits. Sound remains outside the asset delivery wave. Validation: 579 module tests and 31 additional desktop, process and installed checks passed; native glyph/scene 16/17 boundaries qualified. Discussion validation passed after housekeeping.
279 lines
9.6 KiB
Markdown
279 lines
9.6 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`
|
|
- `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:
|
|
|
|
- `glyph_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.codec` serialized values must use `SCREAMING_SNAKE_CASE`;
|
|
- `output.metadata` carries runtime-relevant format-specific detail;
|
|
- `output.pipeline` carries tooling/build metadata kept separate at authoring time;
|
|
- codec must remain explicit and must not be hidden inside format naming.
|
|
|
|
### Scene Bank Contract Boundary
|
|
|
|
For `Scene Bank` assets, `output.format = SCENE/tilemap_v1` identifies the runtime-facing scene contract.
|
|
|
|
Rules:
|
|
|
|
- `SCENE/tilemap_v1` is a runtime/publication format, not an editor-file format;
|
|
- `TMX`, `TSX`, and other editor-specific files may exist as tooling/editorial surfaces, but they are not the canonical publication contract;
|
|
- the canonical packer input for `Scene Bank` publication is the editor-agnostic Scene Bank request emitted by Studio from canonical scene state;
|
|
- packer must not reinterpret the presence of editorial files as authorization to bypass the request boundary;
|
|
- packer must not assume any external scene file is canonical persistence, even when Studio supports that file as import/export compatibility.
|
|
|
|
### 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": { ... } }`;
|
|
- glyph-bank palette payloads must expose canonical `rgba8888` color values in runtime RGBA channel order;
|
|
- ARGB values produced by host image APIs are import-side implementation details, not canonical declaration or projection fields;
|
|
- `convertedRgb565` is not part of the normal palette contract;
|
|
- glyph-bank `palette_count` is an effective runtime metadata field and means
|
|
the number of serialized and resident RGBA8888 palettes for the bank;
|
|
- glyph-bank `palette_count` must be in the inclusive range `1..=64`;
|
|
- `palette_authored`, when present, is informative tooling metadata only and
|
|
must not be treated as runtime-effective metadata;
|
|
- 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": {
|
|
"rgba8888": [4294901760, 16711935]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
For glyph-bank palettes, each `rgba8888` integer is interpreted as
|
|
`0xRRGGBBAA`.
|
|
|
|
Rules:
|
|
|
|
- palette index `0` is an ordinary palette slot;
|
|
- glyph palettes expose 16 usable colors;
|
|
- transparency and partial transparency are represented only by the alpha byte
|
|
in the RGBA8888 palette value;
|
|
- alpha values from `0` through `255` are valid;
|
|
- magenta color-key behavior is not supported as a normal declaration,
|
|
projection, or publication rule.
|
|
|
|
## 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;
|
|
- `output.pipeline` is tooling-only and must not become part of the runtime-facing asset header by default;
|
|
- pipeline-derived values required at runtime must be promoted explicitly into normative runtime-owned metadata fields;
|
|
- 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 `GLYPH/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.
|
|
|
|
|
|
## Animation integration contract
|
|
|
|
Expose the effective selected glyph layout through Packer API: asset UUID and stable artifact ID to glyph ID/fingerprint mapping from the same composition used for pack. Exclude `animations.studio.json` from glyph candidates and binary payload. The sidecar references existing identities and does not create an asset type, header or animation binary format. Reorder/removal/content drift requires explicit revision-checked rebind by authoring services; never retarget by path/order.
|
|
|
|
See the [complete animation contract](../studio/12.%20Animation%20Authoring%20Specification.md).
|
|
|
|
## Batch composition, ownership and dependency boundaries
|
|
|
|
Authorized PNG import, bank creation/registration, ordered composition,
|
|
build-inclusion and preload/contract changes MUST reuse existing declaration,
|
|
registry and canonical scene-request rules through the shared batch service.
|
|
No agent-specific manifest/index writer or second packer is introduced. External
|
|
source grants and expected hashes are validated before publication.
|
|
|
|
Generated-output ownership and dependency metadata MUST be declared and
|
|
queryable by asset/batch. It describes producer, output path, input asset edges
|
|
and stale dependent state without replacing registry identity. Only explicitly
|
|
requested internal batch operations execute. Metadata MUST NOT invoke shell,
|
|
external generators, ROM importers or automatic transitive regeneration.
|
|
|
|
Composition changes MUST preserve no-op/append identities and expose affected
|
|
animation/scene/metadata references for explicit incompatible rebind. Canonical
|
|
scene layers retain cold glyph AssetIds; a batch MUST NOT reinterpret them as
|
|
runtime slot numbers or synthesize hidden helper exports.
|