spriteforge/docs/studio-architecture.md

SpriteForge Studio

SpriteForge has two deliberately separate halves:

1. Studio is the human-facing authoring system. It stores art direction, references, generation recipes, candidates, decisions and revision history.
2. Compiler is the existing deterministic pipeline. It converts approved RGBA frames into palettes and .sfa files for the game.

The separation keeps generation providers replaceable. A Studio project never depends on a particular hosted API or model.

Project layout

my-art/
  project.json              # compact, versioned source of truth
  media/ab/cd/<sha256>.png  # content-addressed source and candidate images
  masks/                    # editable alpha/region masks (future)
  exports/                  # approved RGBA sequences for the compiler

project.json contains no embedded images. Every state-changing operation adds an event with a timestamp and enough metadata to audit the decision. Generation recipes record provider, model, seed, prompts, dimensions, references and control inputs so accepted art can be reproduced.

Generation boundary

A provider receives a provider-neutral GenerationRequest and yields one or more PNG candidates. Initial providers are expected to be remote because Intel Iris Xe is suitable for running the Studio but not for interactive diffusion. Likely adapters are a remote ComfyUI worker and a hosted image API. Providers are plugins and must not be referenced by the project store or compiler.

Large sprites are authored on a source canvas up to 1024x1024 and may export to an in-game box as large as 600x600. Small units are also authored at 256x256 or 512x512 and downsampled only during export; diffusion is never asked to paint directly at 60x60.

Human control loop

The primary unit of work is a shot: asset + animation + direction + frame. Each shot may have many candidates but at most one approved candidate. Reject, approve and supersede operations retain history. Batch generation is an accelerator, not an irreversible action.

The first production gate is intentionally small: one approved reference, one direction and four idle frames. The system should not be scaled to a complete character until those frames preserve identity, silhouette and equipment.