Documentation
Docs/en/reference/image-format/runtime.md
Sprite Runtime 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.runtime.factory-coverage |
Default factory extension boundary | DefaultSpriteFactory registers every built-in ImageBaker extension except spr; direct .spr paths need a custom factory or, normally, an authored .fofrm wrapper. | Bake support and stock runtime path support are separate extension registries. | Source/Client/DefaultSprites.h |
image-format.runtime.decode |
Baked-container decoding | The stock runtime reads only the baked container through ReadSpriteResource, validates magic, version, frame and direction counts, complete frame/mesh records, footer, and trailing data, then constructs either AtlasSprite or SpriteSheet. | Source decoders are baker-only and are not deployed as runtime image parsers. | Source/Common/SpriteResource.cpp, Source/Client/DefaultSprites.cpp |
image-format.runtime.static-frame |
Single-frame behavior | A one-frame one-direction resource becomes AtlasSprite and applies the resolved concrete-frame draw offset; serialized NextX/NextY remains metadata because there is no SpriteSheet frame-displacement surface. | NextX/NextY matter only when a sheet consumer selects and interprets animation frames. | Source/Client/DefaultSprites.cpp |
image-format.runtime.sprite-sheet |
Direction and playback state | SpriteSheet accepts one/full map directions, random prewarm, normalized time and loop/reverse playback; one frame or zero ticks does not play. Copies start at frame/direction zero with valid size/anchor and retain state/action tags. | Animation state is client presentation state and each direction owns a parallel frame sheet. | Source/Client/DefaultSprites.cpp, Source/Tests/Test_SpriteSheet.cpp |
image-format.runtime.frame-offset |
Sprite offsets and frame motion | Concrete/shared frames retain ordinary sprite offsets to the root in SpriteSheet::_sprOffset and NextX/NextY per-frame visual motion deltas in _sprMotion. SetFrame(offset, motion) assigns each input to its matching field. CreateSpriteSequence retains original shared atlas sprites with independent offsets and motions arrays in that order. GetSpriteFrameOffset reads ordinary offsets; GetSpriteFrameMotion reads deltas. CritterHexView derives cumulative displacement, distance-driven frame selection, cycle phase and visual _offsAnim compensation from motion deltas against logical HexOffset and independent extra displacement. These presentation values do not drive entity movement. Projects own first/last selection, cumulative displacement, filename rules and sequence splices. | Per-frame visual displacement must remain separate from image anchors and authoritative world movement. | Source/Client/DefaultSprites.cpp, Source/Client/DefaultSprites.h, Source/Scripting/ClientGlobalScriptMethods.cpp, Source/Tests/Test_SpriteSheet.cpp, Source/Tests/Test_AngelScriptClientEngine.cpp |
image-format.runtime.atlas |
Atlas upload, polygon draw, border, and hit mask | Positive-size RGBA frames are placed in the requested AtlasType, uploaded with duplicated one-pixel filtering edges, and converted to a SpriteHitValue hit mask. Ordinary full-image draws submit the baked indexed silhouette when present; crops, tiled and padded draws, fonts, blits, model sprites, and particles retain rectangular paths. | Mesh geometry changes fill and submission cost without changing atlas pixels, picking, logical scaling, or specialized rectangular rendering contracts. | Source/Client/DefaultSprites.cpp, Source/Client/SpriteManager.cpp |
image-format.runtime.cache |
Copyable sprite cache identity | Copyable sprites are cached by hashed path plus AtlasType; every load, including the first, returns MakeCopy. SpriteSheet clocks and frame tables are independent; AtlasSprite retains shared atlas pixels/geometry. | Independent animation state must not mutate the cached prototype, and different atlas classes cannot share placement blindly. | Source/Client/ResourceManager.cpp, Source/Tests/Test_SpriteSheet.cpp |
image-format.runtime.missing-cache |
Missing-path memoization | Missing paths, absent extensions, unknown factories, and factory load failures are memoized by path in _nonFoundSprites; CleanupSpriteCache does not clear that set. | ResourceManager preserves failures during cleanup; ForgetFailedSprite or InvalidateSpriteResource explicitly enables a retry after mounted sources change. | Source/Client/ResourceManager.cpp, Source/Client/ResourceManager.h |