# SpriteForge Studio workflow

Studio is a local browser application. Images and project decisions stay in a
chosen project directory; API tokens are never stored there.

```powershell
pip install -e .
sf studio C:\art\my_game --init --id my_game --name "My Game"
```

The normal authoring loop is:

1. Write the global style bible once.
2. Create an asset and set its generation canvas and final in-game box.
3. Add one or more approved appearance references.
4. Create an animation grid (for example 8 directions and 6 frames).
5. Add pose/depth controls, generate candidates and approve one per shot.
6. Use an inpainting mask to regenerate only a bad region. White pixels are
   editable; black pixels are protected.
7. Set alpha threshold/chroma key if required, adjust normalized pivot, Export.

Use **Approved preview** to play a selected animation and direction. Assets in
the same layer group are composited by `layer_order`, so body/armour/weapon
alignment can be checked before export. When frame N is generated, the approved
frame N-1 is automatically exposed to ComfyUI as `CONTROL_PREVIOUS` for a
low-denoise temporal img2img branch.

Every edit creates a content-addressed project revision. **Revision history**
can restore an earlier state without destroying the current one. Cloning an
asset copies its references, settings, controls and complete shot grid but not
its candidates; this is the normal way to create synchronized equipment layers.

Run validation from the UI or without images:

```powershell
sf studio-validate C:\art\my_game
```

The report covers missing approvals, ragged grids, broken media, empty
silhouettes, strong temporal silhouette drift, failed jobs and incompatible
paperdoll layers.

`Pipeline test` produces labelled cards without a GPU. It exists to verify the
complete queue, review, persistence and export path and is not an art backend.

Generation source canvases should normally be 512x512. A 60x60 unit is reduced
only during export. Large bosses may use 768x768 or 1024x1024 sources and export
up to a 600x600 in-game box.

Export refuses incomplete rectangular animation grids. Every animation must
have one approved candidate for every direction and frame. This prevents a
missing direction from silently becoming the wrong runtime frame.