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