Files
prometeu-studio/docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md
T
bquarkz 1471b427f1
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit
feat(studio): deliver asset authoring and automation workflows
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.
2026-11-11 01:21:25 +00:00

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.