spriteforge/docs/incremental-builds.md

Incremental builds and cache

SpriteForge uses two immutable content-addressed cache layers under .sfcache/:

• raw/<input_hash>.npz stores expensive backend RGBA output;
• artifacts/<artifact_hash>.sfa stores palette-dependent postprocessed output.

The input hash covers the normalized asset specification, every dependency file reported by the backend, the backend version, and the raw-cache format version. The artifact hash additionally covers the shared palette and postprocess version. Cache writes use a temporary file followed by an atomic replace.

This split is intentional: changing a palette may require cheap requantization, but must never rerun a future multi-hour Blender render.

sf build assets.yaml --jobs 8
sf build assets.yaml --asset changed_actor --jobs 8
sf build assets.yaml --rebuild-palette

--jobs N runs independent backend tasks in a process pool on Windows and Linux. The CLI reports counts for newly generated raw assets, raw-cache hits, and final artifact-cache hits.

An existing palettes.sfp is stable across ordinary incremental builds. Use --rebuild-palette only with an unfiltered full build; SpriteForge rejects a filtered palette rebuild because it would invalidate unchanged indexed assets.

The cache is disposable and never a source of truth. Manifests and source files remain authoritative.