Документация
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 | ReadSpriteResource отвергает неподдерживаемые версии, неверные длительности/число кадров, ошибочные обратные shared-ссылки, усечённые pixels/mesh и лишние данные. DefaultSpriteFactory создаёт atlas image для одного кадра/направления либо SpriteSheet с таймлайном каждого направления; shared-копии получают собственные размещение и движение. | Source decoders принадлежат только baker и не поставляются как runtime image parsers. | Source/Client/DefaultSprites.cpp, Source/Common/SpriteResource.cpp |
image-format.runtime.static-frame |
Поведение одного кадра | Ресурс с одним кадром и направлением становится AtlasSprite и применяет разрешённый draw offset concrete frame; сериализованные Motion остаются metadata, потому что поверхности frame displacement SpriteSheet нет. | Дельты движения используются только потребителем, который выбирает и интерпретирует кадры последовательности. | Source/Client/DefaultSprites.cpp |
image-format.runtime.sprite-sheet |
Состояние направления и playback | Длительности/границы SpriteSheet и GetDuration/GetFrameDurations используют timespan; в файлах остаются положительные uint32 мс. Направления сохраняют фазу; направление0 независимо. Копии сохраняют тайминг и сбрасывают проигрывание. Равномерные конструкторы делят нс; AdvanceTime сохраняет доли мс и непрерывную прямую/обратную фазу. Явные native/script-последовательности с нулевой длительностью сохраняют ручной нормализованный выбор кадра и не проигрываются автоматически; таймлайн целиком нулевой или целиком положительный. | Animation state является клиентским presentation state, а каждое направление владеет параллельным frame sheet. | Source/Client/DefaultSprites.cpp, Source/Tests/Test_SpriteSheet.cpp |
image-format.runtime.frame-offset |
Смещения спрайтов и покадровый motion | Конкретные кадры и кадры с общими пикселями хранят обычные смещения спрайта относительно корня в SpriteSheet::_sprOffset, а покадровые визуальные дельты Motion — в _sprMotion. SetFrame(offset, motion) записывает входы в соответствующие поля. CreateSpriteSequence сохраняет исходные общие atlas-спрайты с независимыми массивами offsets и motions в этом порядке. GetSpriteFrameOffset читает обычные смещения; GetSpriteFrameMotion — дельты. CritterHexView вычисляет накопленный перенос, выбор кадра по расстоянию, фазу цикла и визуальную компенсацию _offsAnim из дельт движения относительно логического HexOffset и независимого дополнительного переноса. Эти значения представления не управляют перемещением сущности. Проект задаёт выбор первого/последнего кадра, накопление переноса, правила имён и склейки последовательностей. | Визуальное покадровое смещение должно оставаться независимым от опор изображения и авторитетного движения сущности. | 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 |