spriteforge/docs/manifest-v1.md

Manifest schema v1

Manifests are UTF-8 YAML and may use the compact flat form:

version: 1
defaults: {dirs: 8, fps: 12, pivot: bottom_center}

demo_actor:
  backend: blender
  rig: rigs/demo.blend
  anims: [idle, walk]

demo_floor:
  backend: procedural
  generator: floor_tile
  params: {color: '#706860', variants: 4}
  dirs: 1

An explicit assets: mapping is also supported, but it cannot be mixed with flat asset declarations. Asset IDs and backend names match [a-z][a-z0-9_]*. Unknown fields are errors, while generator-specific options belong under params.

Common fields are backend, dirs, fps, pivot, size, palette, palettes, tags, seed, and postprocess_scale. A pivot is a standard name (bottom_center, center, bottom_left, top_left) or signed x,y. Sizes use WIDTHxHEIGHT.

postprocess_scale applies a fixed nearest-neighbour scale before tight alpha cropping and target-size fitting. Set it to 0.25 for a 4x supersampled Blender render. Unlike adaptive bbox fitting, this preserves the relative world scale of short and tall assets.

Backend contracts:

Backend	Required field
procedural	generator
blender	rig
import	source
composite	non-empty layers

Additional backends register a contract through register_backend_contract() and put backend-specific configuration in params; neither the loader nor the manifest core needs modification.

Validate without producing assets:

sf validate assets/environment.yaml assets/actors.yaml
sf build assets/environment.yaml --tag environment --jobs 4 --dry-run

Diagnostics use absolute-file:line:column followed by the YAML property path.