Documentation
Docs/en/reference/image-format/baking.md
Image Baking Contract
Generated reference. Do not edit directly. Update
BuildTools/ImageFormatInterface.json, then runpython BuildTools/docs_image_format.py --write.
| Index | Formats | FOFRM | Options | Baking | Runtime | Validation | Canonical JSON | Guide |
| Stable ID | Rule | Requirement | Why | Source |
|---|---|---|---|---|
image-format.baking.discovery |
Scan and targeted modes | Full scans and targeted requests share the image dependency catalog. Master and on-demand baking retain standalone candidates in the full local cache, including consumed inputs; package export is selected separately by Resources.usage.json. Output discovery and fingerprint cache hits still register actual output names. | Incremental project builds and one-file rebakes share one baker without treating a skipped target as failure. | Source/Tools/ImageBaker.cpp |
image-format.baking.extension-case |
Case-insensitive extension dispatch | Source and runtime extension lookup uses get_file_extension(), which returns the extension without its dot and lowercases it. | Mixed-case extensions resolve to the same registered loader, though projects should still use canonical lowercase paths. | Source/Tools/ImageBaker.cpp, Source/Essentials/StringUtils.h |
image-format.baking.source-options |
Dollar option dispatch | LoadAny strips text after ‘$’ from the physical filename, passes that suffix to the selected loader, and resolves the source inside the same FileCollection. | One source file can produce selected or transformed variants through FOFRM references without duplicate binaries. | Source/Tools/ImageBaker.cpp, Source/Tools/ImageBaker.cpp |
image-format.baking.output-path |
Output path and NewName | A loader ResolveOutput declaration determines its real published resource path before conversion. A nonempty NewName must agree with that declaration. RawCopy yields an identical output path to Image and cannot republish a consumed source. | FRM/FRx critter normalization and split-direction aggregation require deterministic renamed resources. | Source/Tools/ImageBaker.cpp |
image-format.baking.container-header |
Private container header | Sprite resource v3 begins with uint8 magic43, uint8 version3 and uint8 direction count. Each direction then writes uint16 frame count and uint32 total milliseconds; footer magic43 terminates the exact byte span. Runtime rejects older versions; rebuild baker, clients and metadata together and force-rebake all images. MigrationRule Version advances74→75. | The shared SpriteResource decoder validates the versioned framing before any client or tool consumes pixels or mesh data. | Source/Common/SpriteResource.h, Source/Common/SpriteResource.cpp, Source/Common/Common.h |
image-format.baking.direction-record |
Direction records | Each direction owns 1..65535 frames and a positive uint32 total equal to its frame-duration sum. Counts and durations may differ by direction. Sequence anchor plus logical frame offset becomes an int32 X/Y baked placement; root motion stays int16 and independent. | Per-frame offsets preserve screen placement when polygon geometry changes the serialized canvas independently for each direction and animation frame. | Source/Tools/ImageBaker.cpp |
image-format.baking.frame-record |
Concrete and shared frame records | Slots write positive uint32 whole-ms duration, int32 X/Y placement, int16 X/Y motion and uint8 shared flag. Shared: backward uint16 pixel index. Concrete: uint16 W/H, RGBA8, mesh. Sharing keeps only pixels/size/geometry; placement/motion/time stay local. FrameShot Size/Motion/Offset are signed32 pairs; output checks Size >=0 and uint16, Motion int16. | The record preserves logical placement and lighting coordinates while avoiding transparent texture rows and submitting indexed silhouettes; repeated frames still reuse the original payload. | Source/Tools/ImageBaker.cpp, Source/Common/SpriteResource.cpp, Source/Tools/ImageImport.h |
image-format.baking.sprite-info-index |
Per-pack SpriteInfo index | SpriteInfo/<PackName>.foinfo version2 describes published root outputs only. DirectionFrameCounts and flattened FrameDurationsMs replace global frame count/duration. Positive durations and uint32 sum are checked per direction; shared slots require equal pixel dimensions while own placement/motion/timing may differ. Private successful-output snapshots retain complete entries for full/lazy index recovery without decoding current pixels. A pack without roots publishes an empty index before dependent bakers run; stale metadata must not survive removal of its last root. | Common EngineMetadata answers animation queries without decoding pixels; full and on-demand baking maintain the same root metadata. | Source/Common/AnimationInfo.h, Source/Common/AnimationInfo.cpp |
image-format.baking.sprite-mesh |
Optional polygonal sprite mesh | Resolve and validate the complete SpriteMesh setting group for every image bake, including when SpriteMesh.Enabled is false: AlphaThreshold is 0..254, MaxTriangles is positive, and AreaSavingsWeight is finite and non-negative. When enabled, build deterministic alpha-thresholded candidates within that triangle budget, score saved original-frame area against submitted triangles, retain only validated coverage, crop selected mesh canvases to exact geometry bounds, and preserve the logical root through the serialized frame offset. | The opt-in path reduces transparent overdraw and texture area without clipping visible pixels or changing gameplay placement; unsafe or unprofitable candidates remain quads and empty masks remain explicit empty geometry. | Source/Common/Settings.inc, Source/Tools/SpriteMeshing.cpp, Source/Tools/ImageBaker.cpp |
image-format.baking.error-aggregation |
Per-file work and aggregate failure | Graph validation fails before conversion with the root and dependency chain. Import failures preserve source path, filename options, input size and original exception. Selected asynchronous conversions are reported individually and any error prevents new dependency snapshots for that batch. | A full scan reports all independently failing image resources in one run without silently succeeding. | Source/Tools/ImageBaker.cpp |
image-format.baking.fofrm-resampling |
FOFRM physical resampling | Size/FrameSizes resample RGBA by pixel-center bilinear filtering in premultiplied-alpha space before meshing and atlas upload. The identity path preserves every pixel; an empty source yields a transparent target. Offset, FrameOffsets, child frame offsets and imported Motion keep their pixel units. Missing size keys preserve existing bytes, timing and frame order. Transparent resampled pixels have zero RGB; identity keeps hidden RGB. | Transparent RGB must not bleed into visible edges; resizing does not rewrite authored anchors or root motion. | Source/Tools/ImageTransforms.cpp, Source/Tests/Test_ImageBaker.cpp |
image-format.baking.source-graph |
Mounted source dependency graph | Build one graph from explicitly mounted sources before IncludePatterns/ExcludePatterns filter output candidates. Relative Frame/Frames/Source references share the native ImageRecipe parser; filename options belong to an edge. Later mounted pack winners resolve logical paths. Reject missing dependencies, cycles and chains deeper than 64 FOFRM nodes. Track FRM palettes and FRX directions, including absent optional inputs. | Source availability and publication are different decisions; the same immutable graph serves full, discovery and lazy baking. | Source/Tools/ImageDependencyGraph.cpp |
image-format.baking.root-outputs |
Only recipe roots are published | FOFRM inputs remain readable for composition. The dependency graph suppresses consumed standalone candidates in its root-only plan; the complete local cache also exposes them for independent Resource references and model textures. Flattened outputs have no runtime export edge to their inputs: unreferenced copies are excluded from Resources.usage.json. | Intermediate assets must not increase shipped size or bypass a declared resize/transformation recipe. | Source/Tools/ImageDependencyGraph.cpp |
image-format.baking.fingerprints |
Transitive content fingerprints | Hash each reachable input once per graph snapshot with BLAKE2b-512. Include mount identity, canonical path, input bytes, child digests, optional-input absence, recipe options, build/baking contract and SpriteMesh settings. Detect byte changes with unchanged size/mtime. Publish a private per-output snapshot and metadata entry only after successful output writes; missing/corrupt snapshots rebuild. Cache hits avoid pixel conversion and remain in the expected-output manifest. Reindex/lazy also validate fingerprints and the declaring output pack. | Editing a source does not require touching its FOFRM descriptor or forcing a full bake. | Source/Tools/ImageDependencyGraph.cpp |