Документация Docs/ru/reference/map-format/validation.md

Правила валидации карт

Сгенерированный справочник. Не редактируйте напрямую. Обновите BuildTools/MapFormatInterface.json или владеющие метаданные движка, затем запустите python BuildTools/docs_map_format.py --write.

Индекс

Синтаксис

Свойства

Запекание

Валидация

Каноническая JSON-модель

Руководство по авторингу

Эти стабильные ID правил позволяют CI документации классифицировать изменения формата относительно более ранней ревизии движка.

Стабильный ID	Правило	Требование	Примечания	Авторитетный источник
`map-format.rule.config-syntax`	Синтаксис конфигурации	Используйте повторяющиеся INI-подобные секции, присваивания key = value, комментарии #, продолжение обратной косой чертой и добавление key += value там, где его поддерживает парсер свойства.	.fomap использует общий парсер ConfigFile.	Source/Common/ConfigFile.cpp
`map-format.rule.closed-section-set`	Закрытый набор секций	Используйте только якоря ProtoMap верхнего уровня и вложенные секции <owner>/Critter или <owner>/Item.	[$Name/…] привязывается к предыдущему якорю. Явный владелец обязан именовать объявленную карту; контекстная вложенная секция перед первым якорем отклоняется.	Source/Common/MapLoader.cpp
`map-format.rule.map-identity`	Идентичность карты	Задавайте каждой карте в контейнере с несколькими картами уникальное $Name ProtoMap; одиночный безымянный якорь наследует базовое имя исходника.	Идентичность карты, целевой поиск при запекании и имена запечённых output берутся из объявленных ID карт, а не имён контейнеров.	Source/Tools/MapBaker.cpp
`map-format.rule.shared-placement-ids`	Общие ID размещений	Используйте явные положительные ID, уникальные для всех секций Critter и Item одной карты.	Загрузчик исправляет пропущенные, неположительные и повторяющиеся ID, но исправленные значения могут нарушить написанные вручную ссылки на владельцев.	Source/Common/MapLoader.cpp
`map-format.rule.prototype-resolution`	Разрешение прототипа	Каждая секция Critter и Item обязана именовать существующий прототип через $Proto.	Отсутствующие и неразрешённые прототипы накапливаются как ошибки загрузки карты.	Source/Common/MapLoader.cpp
`map-format.rule.property-overrides`	Переопределения свойств	Используйте свойства, допустимые для получателя секции и стороны запекания; значения переопределяют разрешённый базовый прототип.	MapBaker копирует свойства прототипа, применяет текст секции, проверяет ресурсы и сериализует данные стороны.	Source/Tools/MapBaker.cpp
`map-format.rule.normalized-order`	Нормализованный порядок сущностей	Не используйте текстовое чередование как контракт порядка.	Загрузчик обрабатывает все секции Critter до секций Item, а Mapper записывает криттеров с предметами инвентаря перед предметами карты с непосредственными дочерними предметами.	Source/Client/MapView.cpp
`map-format.rule.ownership-references`	Ссылки владения	Размещения CritterInventory и ItemContainer обязаны через CritterId или ContainerId ссылаться на ID материализуемого владельца.	Несопоставленные ID владельцев пропускают создание дочернего предмета; поддерживаемая форма Mapper или runtime - непосредственные дети размещённых криттеров и нестатических предметов карты.	Source/Server/MapManager.cpp
`map-format.rule.static-items`	Размещение статического предмета	Предмет Static обязан использовать владение MapHex.	Статические предметы становятся неизменяемыми записями сетки и влияют на движение, стрельбу, триггеры и multihex-состояние.	Source/Server/StaticMap.cpp
`map-format.rule.bounds`	Границы карты	Значения Hex криттеров и предметов MapHex обязаны находиться внутри ProtoMap Size до runtime-загрузки.	Сервер отклоняет неверные позиции. Команды редактирования Mapper могут ограничивать позиции, но не заменяют валидацию исходника.	Source/Server/MapManager.cpp
`map-format.rule.side-specific-bake`	Запекание для сторон	Считайте серверный и клиентский бинарные файлы карты связанным output и пересоздавайте оба после изменений исходника или связанного прототипа.	Сервер получает криттеров и все предметы; клиент получает видимые статические предметы и все авторские строки серверной карты, без записей server entities или properties.	Source/Tools/MapBaker.cpp
`map-format.rule.hidden-static-items`	Скрытые статические предметы	Не ожидайте сущность скрытого статического предмета в клиентских данных карты.	Строки его клиентских свойств всё равно хешируются, но запись предмета не создаётся.	Source/Tools/MapBaker.cpp
`map-format.rule.runtime-materialization`	Runtime-материализация	Используйте Static только для неизменяемых объектов на гексах карты; нестатические размещения - для создаваемых криттеров, предметов карты, инвентарей и контейнеров.	Сервер переназначает авторские ID созданных криттеров и нестатических предметов карты перед присоединением непосредственных дочерних предметов.	Source/Server/MapManager.cpp
`map-format.rule.mapper-round-trip`	Цикл Mapper	Проверяйте сохранённые Mapper diff как нормализованный output, а не побайтовую сериализацию.	Mapper выпускает $Name и нормализованные секции [$Name/…] изменённой карты, сохраняет поля $Text, разворачивает унаследованные свойства карты и побайтно сохраняет соседние блоки в контейнере с несколькими картами.	Source/Tools/Mapper.cpp
`map-format.rule.multihex-mesh`	Сериализация multihex-сетки	MultihexMesh обязан содержать пары координат x/y; Mapper нормализует его в пары с продолжением обратной косой чертой.	Нечётное число координат вызывает ошибку сериализации Mapper.	Source/Client/MapView.cpp
`map-format.rule.multihex-lines-runtime`	Runtime-контур multihex-линий	Считайте MultihexLines частью полного runtime-контура предмета вокруг его якоря и каждой допустимой ячейки MultihexMesh.	Серверная материализация статических и динамических предметов индексирует каждую развёрнутую ячейку линии на тот же предмет и пересчитывает его флаги блокировки и взаимодействия.	Source/Server/Map.cpp
`map-format.rule.error-aggregation`	Агрегация ошибок	Считайте любую накопленную ошибку загрузки сущности или проверки свойства или ресурса ошибкой запекания карты.	Диагностика отдельных сущностей записывается до того, как MapLoader или MapBaker выбросит общую ошибку.	Source/Tools/MapBaker.cpp

Последовательность авторской валидации

Объявите каждую карту через [ProtoMap]; именуйте каждый якорь контейнера с несколькими картами.
Адресуйте размещения после якоря через [$Name/Critter] / [$Name/Item] либо используйте явный объявленный ID карты.
Назначьте явные уникальные положительные ID размещений внутри каждой карты и разрешите каждый $Proto и ссылку владения.
Проверьте свойства получателей, ресурсы, границы карты и владение статическими предметами.
Запеките output обеих сторон; считайте предупреждения с последующей агрегированной ошибкой карты ошибкой сборки.
После сохранения в Mapper проверьте нормализацию изменённой карты и убедитесь, что соседние блоки карт не изменились.