Документация
Docs/ru/reference/image-format/baking.md
Контракт запекания изображений
Сгенерированный справочник. Не редактируйте его напрямую. Обновите
BuildTools/ImageFormatInterface.json, затем выполнитеpython BuildTools/docs_image_format.py --write.
| Индекс | Форматы | FOFRM | Параметры | Запекание | Runtime | Проверка | Канонический JSON | Руководство |
| Стабильный ID | Правило | Требование | Причина | Источник |
|---|---|---|---|---|
image-format.baking.discovery |
Scan и targeted modes | Полная и целевая выпечка используют общий каталог зависимостей изображений. Master и on-demand сохраняют самостоятельных кандидатов в полном локальном кеше, включая поглощённые входы; поставку отдельно выбирает Resources.usage.json. Discovery и попадание в fingerprint-кеш регистрируют фактические имена выходов. | Incremental build проекта и перезапекание одного файла используют один baker, не считая пропущенную цель ошибкой. | Source/Tools/ImageBaker.cpp |
image-format.baking.extension-case |
Диспетчеризация расширения без учёта регистра | Lookup расширений source и runtime использует get_file_extension(), который возвращает расширение без точки и в нижнем регистре. | Расширения в смешанном регистре разрешаются одним зарегистрированным loader, хотя проекты всё равно должны использовать канонические lowercase paths. | Source/Tools/ImageBaker.cpp, Source/Essentials/StringUtils.h |
image-format.baking.source-options |
Диспетчеризация параметров после $ | LoadAny удаляет из физического имени текст после $, передаёт suffix выбранному loader и разрешает источник внутри того же FileCollection. | Один исходный файл может давать выбранные или преобразованные варианты через ссылки FOFRM без дублирования binaries. | Source/Tools/ImageBaker.cpp, Source/Tools/ImageBaker.cpp |
image-format.baking.output-path |
Путь выхода и NewName | ResolveOutput загрузчика заранее определяет фактический путь публикуемого ресурса. Непустой NewName должен совпадать с объявленным путём. RawCopy уступает совпадающий путь Image и не выпускает поглощённый исходник повторно. | Нормализация critter FRM/FRx и агрегация разделённых направлений требуют детерминированно переименованных ресурсов. | Source/Tools/ImageBaker.cpp |
image-format.baking.container-header |
Заголовок частного контейнера | Ресурс спрайта v3 начинается uint8 magic43, uint8 version3 и uint8 числом направлений. Далее каждое направление записывает uint16 число кадров и uint32 общее время в миллисекундах; завершающий magic43 ограничивает точный диапазон байтов. Runtime отвергает прежние версии; пересобрать baker, клиентов и metadata вместе, полностью перезапечь изображения. MigrationRule Version повышен74→75. | Общий decoder SpriteResource проверяет версионированное обрамление до потребления pixels или mesh-данных клиентом либо tool. | Source/Common/SpriteResource.h, Source/Common/SpriteResource.cpp, Source/Common/Common.h |
image-format.baking.direction-record |
Записи направлений | Каждое направление содержит1..65535 кадров и положительное общее uint32 время, равное сумме длительностей. Число кадров и время могут различаться по направлениям. Привязка последовательности плюс размещение кадра образуют запечённые int32 X/Y; движение остаётся независимым int16. | Per-frame offsets сохраняют экранное размещение, когда polygon geometry независимо меняет сериализованный canvas каждого направления и кадра анимации. | Source/Tools/ImageBaker.cpp |
image-format.baking.frame-record |
Concrete и shared frame records | Запись слота: положительная длительность uint32 в целых мс, размещение int32 X/Y, движение int16 X/Y, флаг shared uint8. Shared добавляет обратный индекс пикселей uint16; concrete — uint16 W/H, RGBA8 и mesh. Общими остаются только пиксели/размер/геометрия; размещение/движение/время локальны. FrameShot Size/Motion/Offset — пары signed32; на записи проверяются Size >=0 и uint16, Motion int16. | Record сохраняет логическое размещение и координаты освещения, устраняя прозрачные texture rows и отправляя indexed silhouettes; повторные кадры переиспользуют исходный payload. | Source/Tools/ImageBaker.cpp, Source/Common/SpriteResource.cpp, Source/Tools/ImageImport.h |
image-format.baking.sprite-info-index |
Индекс SpriteInfo каждого pack | SpriteInfo/<PackName>.foinfo версии2 описывает только публикуемые корни. DirectionFrameCounts и плоский FrameDurationsMs заменяют общие число кадров/время. Положительность и сумму uint32 проверяют по направлениям; shared-слоты требуют равных размеров пикселей при собственных размещении/движении/времени. Приватные snapshots успешных выходов сохраняют полные записи для восстановления full/lazy индекса без декодирования актуальных пикселей. Пак без корней публикует пустой индекс до запуска зависимых bakers; удаление последнего корня не оставляет устаревшие метаданные. | Общая EngineMetadata отвечает на запросы анимации без декодирования пикселей; полная и отложенная выпечка поддерживают одинаковые метаданные корней. | Source/Common/AnimationInfo.h, Source/Common/AnimationInfo.cpp |
image-format.baking.sprite-mesh |
Необязательный polygonal sprite mesh | Разрешайте и проверяйте всю группу settings SpriteMesh при каждом image bake, в том числе когда SpriteMesh.Enabled равен false: AlphaThreshold находится в 0..254, MaxTriangles положителен, а AreaSavingsWeight конечен и неотрицателен. При включении стройте детерминированные alpha-thresholded candidates в пределах triangle budget, оценивайте saved original-frame area относительно submitted triangles, оставляйте только проверенное покрытие, обрезайте выбранные mesh canvases точно по geometry bounds и сохраняйте logical root через сериализованный frame offset. | Opt-in путь уменьшает transparent overdraw и texture area без обрезания видимых pixels или изменения gameplay placement; небезопасные/невыгодные кандидаты остаются quads, пустые masks — явной пустой geometry. | Source/Common/Settings.inc, Source/Tools/SpriteMeshing.cpp, Source/Tools/ImageBaker.cpp |
image-format.baking.error-aggregation |
Работа каждого файла и агрегированный отказ | Проверка графа завершается до конвертации и сохраняет корень и цепочку зависимостей. Ошибка импорта содержит исходный путь, параметры имени, размер входа и исходное исключение. Ошибки выбранных асинхронных конвертаций сообщаются отдельно; любая ошибка запрещает новые snapshots зависимостей этой группы. | Полный scan сообщает обо всех независимо сломанных image resources за один запуск и не завершается молча. | Source/Tools/ImageBaker.cpp |
image-format.baking.fofrm-resampling |
Физическое изменение размера FOFRM | Size/FrameSizes изменяют RGBA билинейной фильтрацией по центрам пикселей с предварительным умножением цвета на alpha, до построения mesh и загрузки в atlas. При равных размерах каждый пиксель сохраняется; пустой источник даёт прозрачный целевой холст. Offset, FrameOffsets, дочерние покадровые смещения и импортированные Motion сохраняют пиксельные единицы. Без ключей размера прежние байты, тайминг и порядок кадров сохраняются. Прозрачные пиксели после ресайза имеют нулевой RGB; при равных размерах скрытый RGB сохраняется. | RGB прозрачных пикселей не должен загрязнять видимые края; изменение размера не переписывает авторские привязки или root motion. | Source/Tools/ImageTransforms.cpp, Source/Tests/Test_ImageBaker.cpp |
image-format.baking.source-graph |
Граф зависимостей смонтированных исходников | Общий граф строится из явно смонтированных исходников до фильтрации выходов IncludePatterns/ExcludePatterns. Относительные Frame/Frames/Source разбираются общим native-парсером ImageRecipe; параметры имени принадлежат ребру. Логические пути разрешаются через победителей позднее смонтированных пакетов. Отсутствующие входы, циклы и глубина более 64 FOFRM-узлов запрещены. Учитываются палитры FRM и направления FRX, включая отсутствие необязательных входов. | Доступность исходника и его публикация — отдельные решения; один неизменяемый граф обслуживает полную, отложенную выпечку и discovery. | Source/Tools/ImageDependencyGraph.cpp |
image-format.baking.root-outputs |
Публикуются только корни рецептов | Входы FOFRM доступны для композиции. План корней подавляет поглощённых самостоятельных кандидатов; полный локальный кеш также предоставляет их для отдельных Resource-ссылок и текстур моделей. У сплющенных выходов нет runtime-связи поставки с исходниками: копии без самостоятельной ссылки исключаются из Resources.usage.json. | Промежуточные ресурсы не должны увеличивать поставку или обходить объявленный рецепт изменения размера и других преобразований. | Source/Tools/ImageDependencyGraph.cpp |
image-format.baking.fingerprints |
Транзитивные отпечатки содержимого | Каждый достижимый вход хешируется BLAKE2b-512 один раз за snapshot графа. Учитываются mount, канонический путь, байты входа, дочерние отпечатки, отсутствие необязательных файлов, рецепт/options, версии сборки и baking-контракта и настройки SpriteMesh. Смена байтов определяется при прежних размере и mtime. Приватные snapshot и metadata entry публикуются только после успешной записи выхода; отсутствующие или повреждённые snapshots вызывают пересборку. Попадание в кэш исключает конвертацию пикселей и сохраняет регистрацию в expected-output manifest. Reindex/lazy также проверяют отпечатки и пакет, объявивший выход. | Правка исходника не требует touch его FOFRM-дескриптора или принудительной полной выпечки. | Source/Tools/ImageDependencyGraph.cpp |