prometeu-studio/docs/packer/agendas/01.2. Asset Specification, Raw Assets, and Virtual Asset Contract Agenda.md

Asset Specification, Raw Assets, and Virtual Asset Contract Agenda

Status

Open

Purpose

Define the contract of asset.json, including the split between raw assets, virtual assets, and format-specific output specs.

Context

The draft already proposes:

• asset.json as the anchor spec,
• common fields for all assets,
• explicit pipeline declaration for virtual assets,
• future format families such as TILES/indexed_v1 and SOUNDS/pcm16le_v1.

This needs decomposition into a stable common contract plus future format-specific specs.

This agenda assumes the managed asset is the asset root described by one asset.json. That root may aggregate multiple source inputs.

Important example:

• an atlas or image bank asset may contain many source sprites plus one or more palettes;
• one asset.json describes the whole managed asset and its final packed output;
• the internal source files are inputs of that asset, not separate assets unless explicitly modeled that way.

Source Sections

• 5.3 Asset Types (Bank Targets)
• 5.4 Raw vs Virtual Assets
• 7. Asset Specification: asset.json
• 14. Virtual Assets (Deep Explanation)

Key Questions

1. Which fields belong to every asset.json regardless of type?
2. Which parts of the file are common packer contract versus format-specific contract?
3. How explicit must virtual build steps be?
4. Where should defaults live, and when must they be materialized?
5. Is type the bank target, the user-facing kind, or both?
6. How should packer version output formats independently from registry and descriptor schemas?
7. How should one asset.json declare many internal inputs that together form one virtual asset, such as an atlas plus palettes?

Options

Option A

Keep a small common asset.json contract and push all output-specific rules into dedicated format specs.

Option B

Keep a richer monolithic asset.json contract in one central spec.

Tradeoffs

• Option A scales better as new asset formats are added.
• Option A keeps the core packer spec smaller and more stable.
• Option B looks simpler initially but becomes harder to evolve without coupling unrelated formats together.

Recommendation

Adopt Option A:

• a compact common asset.json contract,
• format-specific normative specs for each output family,
• explicit virtual asset declarations with deterministic materialization rules.

Also adopt this modeling direction:

• asset.json describes the managed output unit;
• many internal source files may feed that single managed output;
• atlas/image-bank style assets should be modeled as one asset with many inputs rather than many implicit sibling assets.

Expected Decisions to Produce

1. Common asset.json schema boundary.
2. Raw versus virtual asset contract.
3. Versioning strategy for asset format specs.
4. Rules for defaults and explicit materialization.
5. Multi-input asset declaration model for atlas, bank, and similar grouped assets.

Expected Spec Follow-up

• Common asset specification spec.
• Virtual asset contract spec.
• Format-specific specs such as TILES/indexed_v1.

Non-Goals

• Final CLI UX for authoring these files.
• Incremental build internals.
• Cartridge builder consumption details.