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 | An empty target scans every registered extension; a targeted missing, unsupported, or BakeChecker-skipped path returns without output. | 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 |
image-format.baking.output-path |
Output path and NewName | The baked resource normally keeps its source path; loaders may set NewName, which replaces that output path for legacy normalization. | FRM/FRx critter normalization and split-direction aggregation require deterministic renamed resources. | Source/Tools/ImageBaker.cpp |
image-format.baking.container-header |
Private container header | The private baked stream starts with SpriteResource magic 43 and version 2, then uint16 frame count, uint16 whole animation ticks, and uint8 direction count, and ends with magic 43. | 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 |
image-format.baking.direction-record |
Direction records | Each of one or GameSettings::MAP_DIR_COUNT directions stores exactly the common frame count; the resolved logical root offset is serialized on every concrete frame after mesh padding and cropping. | 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 | Each frame starts with a shared flag; a concrete record stores signed int16 draw offset, uint16 cropped dimensions, signed int16 NextX/NextY, exact RGBA8 pixels, a mesh kind, and mesh vertices and indices plus logical source size and origin when the kind is Mesh. A shared record stores one earlier-frame index. | 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 |
image-format.baking.sprite-info-index |
Per-pack SpriteInfo index | Image baking maintains SpriteInfo/<PackName>.foinfo version 1 with duration, direction, frame bounds, offsets, and shared-frame metadata for every current image source in that resource pack. | Common EngineMetadata can answer 2D animation queries on server and client without decoding RGBA payloads; losing or introducing the aggregate index requires a full rebake. | Source/Tools/ImageBaker.cpp, 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 | Selected files bake asynchronously; each exception is logged, and any nonzero error count ends the Image baker with ImageBakerException. | A full scan reports all independently failing image resources in one run without silently succeeding. | Source/Tools/ImageBaker.cpp |