prometeu-studio/docs/packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md

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:

• 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.

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:

{
  "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.