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 is grounded in:

• 002-asset-specification-raw-assets-and-virtual-asset-contract-decision.md

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