Документация
Docs/ru/reference/image-format/runtime.md
Контракт runtime спрайтов
Сгенерированный справочник. Не редактируйте его напрямую. Обновите
BuildTools/ImageFormatInterface.json, затем выполнитеpython BuildTools/docs_image_format.py --write.
| Индекс | Форматы | FOFRM | Параметры | Запекание | Runtime | Проверка | Канонический JSON | Руководство |
| Стабильный ID | Правило | Требование | Причина | Источник |
|---|---|---|---|---|
image-format.runtime.factory-coverage |
Граница расширений штатной factory | DefaultSpriteFactory регистрирует все встроенные расширения ImageBaker, кроме spr; прямым путям .spr нужна custom factory или, обычно, авторская .fofrm-обёртка. | Поддержка запекания и поддержка штатного runtime path являются разными registry расширений. | Source/Client/DefaultSprites.h |
image-format.runtime.decode |
Декодирование baked container | Штатный runtime читает только запечённый контейнер через ReadSpriteResource, проверяет magic, version, числа кадров/направлений, полные frame/mesh records, footer и trailing data, затем создаёт AtlasSprite либо SpriteSheet. | Source decoders принадлежат только baker и не поставляются как runtime image parsers. | Source/Common/SpriteResource.cpp, Source/Client/DefaultSprites.cpp |
image-format.runtime.static-frame |
Поведение одного кадра | Ресурс с одним кадром и направлением становится AtlasSprite и применяет разрешённый draw offset concrete frame; сериализованные NextX/NextY остаются metadata, потому что поверхности frame displacement SpriteSheet нет. | NextX/NextY имеют значение только когда consumer sheet выбирает и интерпретирует animation frames. | Source/Client/DefaultSprites.cpp |
image-format.runtime.sprite-sheet |
Состояние направления и playback | SpriteSheet принимает одно или все направления карты, random prewarm, normalized time и loop/reverse playback; один кадр или нулевые ticks не проигрываются. Копии начинают с нулевого кадра/направления, корректного размера/привязки и сохраняют state/action tags. | Animation state является клиентским presentation state, а каждое направление владеет параллельным frame sheet. | Source/Client/DefaultSprites.cpp, Source/Tests/Test_SpriteSheet.cpp |
image-format.runtime.frame-offset |
Смещения спрайтов и покадровый motion | Concrete/shared кадры сохраняют обычные смещения спрайтов до рута в SpriteSheet::_sprOffset, а покадровые дельты визуального переноса NextX/NextY — в _sprMotion. SetFrame(offset, motion) записывает каждый вход в соответствующее поле. CreateSpriteSequence удерживает исходные общие atlas sprites с независимыми массивами offsets и motions, именно в таком порядке. GetSpriteFrameOffset читает обычные offsets, GetSpriteFrameMotion — дельты. CritterHexView вычисляет по дельтам motion накопленный перенос, выбор кадра по расстоянию, фазу цикла и визуальную компенсацию _offsAnim относительно логического HexOffset и независимого дополнительного смещения. Эти значения представления не управляют движением сущности. Выбор first/last, накопленный перенос, правила имён файлов и склейки принадлежат проекту. | Визуальное покадровое смещение должно оставаться независимым от опор изображения и авторитетного движения сущности. | 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, polygon draw, border и hit mask | RGBA frames положительного размера размещаются в запрошенном AtlasType, загружаются с продублированными однопиксельными краями filtering и преобразуются в hit mask SpriteHitValue. Обычные полноразмерные draws отправляют запечённый indexed silhouette, когда он есть; crops, tiled/padded draws, fonts, blits, model sprites и particles сохраняют прямоугольные пути. | Mesh geometry меняет fill/submission cost, не меняя pixels атласа, picking, logical scaling или специализированные прямоугольные render-контракты. | Source/Client/DefaultSprites.cpp, Source/Client/SpriteManager.cpp |
image-format.runtime.cache |
Идентичность cache копируемых спрайтов | Копируемые спрайты кэшируются по hashed path вместе с AtlasType; каждая загрузка, включая первую, возвращает MakeCopy. Clock и таблицы кадров SpriteSheet независимы; AtlasSprite сохраняет общие atlas pixels/geometry. | Независимое animation state не должно изменять cached prototype, а разные классы atlas нельзя безусловно размещать совместно. | Source/Client/ResourceManager.cpp, Source/Tests/Test_SpriteSheet.cpp |
image-format.runtime.missing-cache |
Мемоизация отсутствующего пути | Отсутствующие paths/extensions, неизвестные factories и ошибки factory load мемоизируются по пути в _nonFoundSprites; CleanupSpriteCache не очищает этот набор. | ResourceManager сохраняет ошибки при обычной очистке; ForgetFailedSprite или InvalidateSpriteResource явно разрешает повторную попытку после обновления подключённых источников. | Source/Client/ResourceManager.cpp, Source/Client/ResourceManager.h |