spriteforge/docs/studio.md

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.

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:

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.