Documentation Docs/en/reference/image-format/validation.md

Image Format Validation

Generated reference. Do not edit directly. Update BuildTools/ImageFormatInterface.json, then run python BuildTools/docs_image_format.py --write.

Index

Formats

Stable ID	Rule	Requirement	Why	Source
`image-format.validation.fofrm-count`	Nonempty FOFRM references	A recipe uses exactly one nonempty root Source or nonempty Frame/Frames composition. Source is root-only and excludes Frame/Frames in every section. All modes validate names, offsets and sizes before producing an output.	A descriptor must resolve at least one source reference before a runtime frame table can exist.	Source/Tools/ImageBaker-Fofrm.cpp, Source/Tools/ImageRecipe.cpp
`image-format.validation.fofrm-directions`	Complete direction tables	Frame/Frames composition requires one unnamed sequence or the complete active-geometry indexed direction table; even a later section without direction1 fails before resolution. Source permits overrides of existing directions without repeated references. Final direction counts and durations may differ, but every timeline must be valid.	Every direction sheet shares one frame-count and timing header.	Source/Tools/ImageRecipe.cpp, Source/Tools/ImageBaker-Fofrm.cpp
`image-format.validation.fofrm-nested-shared`	Safe nested shared-frame materialization	Resolve shared pixel chains before composition, rejecting invalid indices and cycles. Materialization copies pixels/dimensions/pixel-preservation flags while retaining the logical slot placement, motion and duration. Legacy SPR explicitly copies its former aliased metadata when constructing slots.	Shared slots own placement, movement and time; materialization copies concrete pixels without replacing that metadata.	Source/Tools/ImageBaker-Fofrm.cpp
`image-format.validation.rgba-payload`	Exact RGBA payload size	Reject every concrete frame whose byte payload is not exactly width times height times four.	The client reads a fixed RGBA8 byte count without a separate payload-length field.	Source/Tools/ImageBaker.cpp
`image-format.validation.tga-subset`	Supported TGA subset	Use no image ID, bottom-left orientation, TrueColor type 2 or 10, and 24 or 32 bpp; indexed/grayscale/other inputs are rejected or outside the implemented orientation assumptions.	The loader consumes the fixed header directly, then always flips rows and does not branch on descriptor origin.	Source/Tools/ImageBaker-Tga.cpp, Source/Tests/Test_ImageBaker.cpp
`image-format.validation.malformed-inputs`	Malformed decoder inputs	Keep focused failure coverage for corrupt PNG, TGA, FRM/FRx/RIX/ART/ZAR/TIL/MOS/BAM, SPR, and nested FOFRM inputs.	Legacy binary parsers must fail deterministically instead of emitting truncated runtime containers.	Source/Tests/Test_ImageBaker.cpp
`image-format.validation.runtime-container`	Runtime container guards	Require v3 magic/version, positive per-direction counts/times, positive slot durations with checked sum, positive uint16 concrete dimensions, valid backward pixel references, valid mesh/pixel bounds and exact footer/end. SpriteInfo requires schema2 and matching flat array sizes.	Corrupt baked bytes must not reach atlas allocation or animation updates.	Source/Common/SpriteResource.cpp
`image-format.validation.playback-timing`	Nonzero per-frame duration	Positive logical-frame durations and checked uint32 totals eliminate division by zero for short animations. Explicit Duration below final frame count fails. Raw legacy zero clocks normalize to 10 fps; positive sub-ms periods normalize to 1 ms. Source preserves imported timelines; normalized phase drives forward/reverse/loop playback and direction switches.	SpriteSheet advances normalized phase by elapsed/whole duration and selects frames using cumulative positive duration boundaries.	Source/Tools/ImageImport.cpp, Source/Client/DefaultSprites.cpp, Source/Tests/Test_SpriteSheet.cpp
`image-format.validation.project-visible`	Embedding-project visual gate	After native and documentation checks, rebake the embedding project and inspect changed dimensions, alpha edges, mirrors, directions, cadence, offsets, hit masks, and relevant client profiles in a visible scene.	Parser and container tests cannot prove art framing, filtering, gait, or project resource-pack selection.	Source/Tests/Test_ImageBaker.cpp, Source/Tests/Test_TextureAtlas.cpp
`image-format.validation.numeric-boundaries`	Signed quantities and checked format boundaries	Use int32_t for imported dimensions and shared-frame indices, and typed per-frame durations with checked uint32 millisecond totals for sprite v3. Validate final signed ranges and exact RGBA byte counts after FOFRM transformations and before serialization; retain checked uint16/uint8 wire conversions and backward shared-frame references. Decode TGA uint16 dimensions into signed int32_t; reject truncated payloads and oversized run packets while preserving complete final raw-packet clipping. Internal arithmetic uses fixed-width integers; reserve size_t for actual target container, buffer or external APIs and use numeric_cast for transitions between different numeric types.	Consistent signed types remove intermediate narrowing while preventing negative sizes, duration wrapping and high-bit wire dimensions from reaching allocation or indexing incorrectly.	Source/Tools/ImageImport.h, Source/Tools/ImageBaker.cpp, Source/Tools/ImageBaker-Tga.cpp
`image-format.validation.fofrm-names`	Canonical FOFRM names	Before source resolution, validate the unnamed root (direction 0), active-geometry nonzero HexDir/SquareDir sections, exact PascalCase keys and field applicability. Source and Fps are root-only. Alias and Effect are refused with dated migration markers. Old Dir forms, named zero, Count, old frame/delta keys and unknown names fail; there is no fallback.	Unmigrated names and misspellings must fail baking instead of silently applying defaults or bypassing checks through Source.	Source/Tools/ImageBaker-Fofrm.cpp, Source/Tools/ImageRecipe.cpp, Source/Tests/Test_ImageBaker.cpp

Validation commands

python BuildTools\docs_image_format.py --check
python -m unittest BuildTools.tests.test_docs_image_format
cmake --build <build-dir> --config RelWithDebInfo --target RunUnitTests

An embedding project must also rebake affected resources and inspect every changed animation, direction, alpha edge, hit mask, and supported client profile.