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 | ReadSpriteResource rejects unsupported versions, malformed durations/counts, invalid backward shared references, truncated pixels/mesh and trailing data. DefaultSpriteFactory creates an atlas image for one frame/one direction or a SpriteSheet with per-direction timelines; shared copies override their own placement and movement. | Source decoders are baker-only and are not deployed as runtime image parsers. | Source/Client/DefaultSprites.cpp, Source/Common/SpriteResource.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 Motion remains metadata because there is no SpriteSheet frame-displacement surface. | Motion matters only when a sheet consumer selects and interprets animation frames. | Source/Client/DefaultSprites.cpp |
image-format.runtime.sprite-sheet |
Direction and playback state | SpriteSheet durations/ends and GetDuration/GetFrameDurations use timespan; wire values are positive uint32 ms. Directions preserve phase; direction0 is independent. Copies retain timing and reset playback. Uniform constructors split ns; AdvanceTime keeps sub-ms time with continuous forward/reverse phase. Explicit native/script-created zero-duration sequences retain manual normalized frame selection and do not play automatically; each timeline is entirely zero or entirely positive. | 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 Motion 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 |