Документация Docs/ru/how-to/tools/mapper.md

Инструменты Mapper

Документация движка по переиспользуемым API жизненного цикла Mapper, авторинга, предпросмотра частиц и внеэкранного захвата. Конкретные карты, прототипы маркеров, генераторы превью, потребители UI и профили запуска принадлежат встраивающему проекту.

Mapper является одновременно интерактивным редактором и скриптуемым хостом обработки карт. AngelScript на стороне Mapper может создавать и загружать карты, добавлять сущности, управлять видом редактора, захватывать отрендеренный кадр, проверять геометрию атласов, просматривать частицы и завершать процесс без подключения к игровому серверу.

Меню, окна, ручное редактирование, историю, дисциплину сохранения и видимые свидетельства UI описывает интерактивное руководство по Mapper. Эта страница владеет скриптовой и нативной поверхностью интеграции.

Решение по автоматизации

Сначала защищайте авторские карты: наблюдайте dirty marker и History, используйте Ctrl+S только для намеренного сохранения, проверяйте text diff, затем валидируйте runtime scene. Воспроизводимый headless batch запускается в Game.OnStart, выполняет ограниченные warmup loops из Game.OnLoop, вызывает Game.SaveMapperScreenshot и завершается через Game.RequestQuit.

Выбирайте маршрут захвата осознанно. SaveMapperScreenshot синхронно записывает render карты как PNG; прогрейте только что показанную карту до вызова, а после resize или crop ожидайте non-uniform размеры. Метод не включает окна ImGui уровня приложения. Если свидетельство ревью должно содержать UI Mapper, захватите видимое окно приложения platform screenshot tool. Встраивающий проект владеет batch plan, выбором карт, именованием результатов, конвертацией, retries и валидацией generated assets.

Dirty marker и History являются интерактивными свидетельствами; в текущем Mapper script API нет запроса Game.GetDirtyMap(). Фиксированные camera и overlay inputs делают captures сравнимыми, но не обещают byte-identical pixels между ревизиями renderer, driver, font или assets.

Граница владения

Движок владеет:

загрузкой, отображением, обработкой, сохранением и завершением карт в MapperEngine;
скриптовыми методами Game.* на стороне Mapper;
внеэкранным режимом хоста Render.HeadlessWindow;
управлением камерой, оверлеями, видимостью и прокруткой для автоматизации;
чтением PNG-снимков и PNG-диагностикой атласов из render target Mapper;
независимым от подсистемы предпросмотром частиц и редактором исходников SPARK.

Встраивающий проект владеет:

стартовой подконфигурацией и скриптовой точкой входа Mapper;
выбором карт и прототипов-маркеров для включения или скрытия;
именованием результатов, повторами, обрезкой, конвертацией, метаданными и последующим UI;
проектными настройками передачи пакетного плана в скрипт;
проверкой авторских контейнеров карт и сгенерированных материалов.

Поэтому страница движка описывает переиспользуемые примитивы и схему интеграции, а не конвейер превью конкретной игры.

API жизненного цикла карты

Методы только для Mapper экспортируются в Source/Scripting/MapperGlobalScriptMethods.cpp:

Метод	Назначение
`Game.NewMap(name, width, height)`	Создать пустую карту с синтезированным заголовком `[ProtoMap]` и рабочим гексом в центре.
`Game.NewMapFromText(name, text)`	Создать карту из написанного вызывающей стороной текста заголовка `[ProtoMap]`.
`Game.LoadMap(mapName)`	Загрузить объявленную карту по имени из настроенных источников данных прототипов.
`Game.ShowMap(map)`	Сделать загруженную карту текущей и видимой.
`Game.UnloadMap(map)`	Удалить загруженную карту из Mapper.
`Game.GetLoadedMaps(index)`	Перечислить загруженные карты через индексный API Mapper.
`Game.GetMapFileNames(dir, recursive)`	Перечислить объявленные имена карт ниже каталога данных карт.
`Game.ResizeMap(width, height)`	Изменить размер текущей карты.
`Game.SaveMap(map, customName)`	Сохранить через штатное разрешение пути Mapper.
`Game.SaveMapToPath(map, subDir, name)`	Сохранить в `<MapsRoot>/<subDir>/<name>.<prototype-extension>`; разделители пути в `name` и обход через `..` запрещены.

NewMapFromText требует секцию [ProtoMap]. Используйте метод, когда автоматизация должна определить Size, WorkHex, ScrollAxialArea, Outside или FixedTime до размещения сущностей.

Движок не требует фиксированного расширения контейнеров карт. Mapper сканирует файлы с расширениями из Baking.ProtoFileExtensions, перечисляет каждую метку [ProtoMap] и обращается к карте по объявленному имени. Один контейнер может содержать несколько карт с секциями [$Name/Item] и [$Name/Critter]. Сохранение карты из многокарточного контейнера сохраняет соседние блоки карт.

LoadMap принимает объявленное имя карты либо путь/основу с каталогом. Файл-кандидат принимается только если MapLoader::EnumerateMaps находит нужное объявление или основу пути. Поэтому одноимённый сосед Area.foloc не может затенить Area.fomap только потому, что его расширение встречается раньше в Baking.ProtoFileExtensions.

Для сгенерированного или изолированного авторинга предпочитайте SaveMapToPath: его назначение явно и ограничено корнем источника карт. Метод наследует расширение существующего контейнера. SaveMap предназначен для штатного сохранения Mapper и может получить каталог из существующего состояния карты.

MapperEngine::Shutdown() выгружает все карты, оставшиеся в LoadedMaps, до вызова ClientEngine::Shutdown(). Это важно, поскольку завершение MapView требует освобождать сущности, предметы и render target карты через DestroySelf(). Закрытие Mapper с несколькими открытыми вкладками должно следовать тому же жизненному циклу, что и явные вызовы Game.UnloadMap.

API авторинга сущностей

Группа методов	Назначение
`Game.AddItem`, `Game.AddCritter`, `Game.AddTile`	Разместить сущность или тайл и вернуть живое представление Mapper.
`Game.GetItemOnHex`, `Game.GetItemsOnHex`	Проверить предметы на гексе карты.
`Game.GetCritterOnHex`, `Game.GetCrittersOnHex`	Проверить криттеров на гексе с `CritterFindType`.
`Game.MoveEntity`	Переместить сущность Mapper на другой гекс.
`Game.DeleteEntity`, `Game.DeleteEntities`	Удалить авторские сущности.
`Game.SelectEntity`, `Game.SelectEntities`	Изменить выделение редактора.
`Game.GetSelectedEntity`, `Game.GetSelectedEntities`	Прочитать выделение редактора.
`Game.FindEntityById`	Найти загруженную сущность Mapper по id.
`Game.SetEntityProperty`	Применить свойство по имени и тексту через тот же путь разбора и обновления, что использует Inspector.

Размещение возвращает живое представление, чтобы скрипт мог сразу назначить направление и поля экземпляра. SetEntityProperty является универсальным маршрутом для инструмента без сгенерированного типизированного доступа; метод возвращает false, когда имя или значение свойства применить невозможно.

Не помещайте авторитетную игровую политику в автоматизацию Mapper. Mapper создаёт сериализованные входные данные, а авторитет времени выполнения и персистентность остаются на сервере. См. серверное время выполнения, модель сущностей и персистентность.

Инструменты частиц

Интерактивный предпросмотр частиц

Откройте Windows -> Particle preview, чтобы проверить запечённые ресурсы частиц на текущей карте. Предпросмотр запрашивает поддерживаемые расширения у зарегистрированной фабрики спрайтов частиц, поэтому сам Mapper не зависит от SPARK или Effekseer. Исходники SPARK .spark и Effekseer .efkproj запекаются в .spk и .efk; код предпросмотра загружает только запечённые ресурсы.

Каталог обновляется, когда Mapper возвращает фокус. Изменение исходника или зависимости инвалидирует затронутый запечённый спрайт и кэш текстуры, сохраняя положение предпросмотра, seed, масштаб, смещение и prewarm. Refresh принудительно выполняет тот же путь переиндексации и перезагрузки. Контракты исходников, запекания, зависимостей и времени выполнения описаны в формате частиц.

Mouse position размещает эффект в последней допустимой позиции курсора карты. View center находит текущий центр области просмотра при начале воспроизведения. Play создаёт временный спрайт карты DrawOrderType::Particles; Restart пересоздаёт его с текущими параметрами, а Remove отсоединяет. Временный спрайт не является сериализованной сущностью карты и не входит в отслеживание изменений или историю отмены.

Необязательные настройки Mapper.ParticlePreviewEffect, Mapper.ParticlePreviewSeed, Mapper.ParticlePreviewScale и Mapper.ParticlePreviewPrewarm выполняют тот же путь при запуске. Они полезны для воспроизводимых smoke-тестов, не превращая проектный профиль запуска в контракт движка.

Редактор исходников SPARK

Откройте Windows -> SPARK particle editor, чтобы просматривать исходники .spark и открывать отдельное окно графа/предпросмотра для каждого ассета. Сохранение записывает через файловую систему сырых ресурсов, переиндексирует запечённые ресурсы и инвалидирует кэш спрайта .spk сохранённого ассета. При закрытии изменённого окна предлагаются Save, Discard и Cancel.

Задайте Mapper.SparkEditorSource равным raw asset path, например Documentation.spark, когда профиль запуска должен детерминированно открыть один редактор. При запуске путь проверяется по проиндексированным raw-исходникам .spark; при ошибке Mapper явно сообщает об отсутствующем исходнике, а не показывает пустой редактор.

Авторинг Effekseer остаётся внешним. Соберите его редактор командой BuildTools/buildtools.py build-auxiliary effekseer-editor <Config>, отредактируйте отслеживаемый .efkproj, затем проверьте запечённый .efk через Particle preview.

Специализированные просмотрщики

Просмотрщик анимации

Откройте Windows -> Animation viewer в Mapper или запустите автономную цель <DevName>_AnimationViewer, создаваемую при FO_BUILD_MAPPER. Просмотрщик перечисляет загруженные прототипы криттеров и доступные пары 2D/3D-анимаций, воспроизводит одноразовые клипы с возвратом к idle и предоставляет направление, масштаб, оверлеи root/render/view, слои модели и иерархию. Он использует те же клиентские сервисы спрайтов и моделей, что и игра, но не имеет карты или сетевой сессии.

Точные команды сборки и запуска, элементы управления, поведение слоёв и иерархии модели, сохраняемое состояние, диагностику ошибок, захват доказательств и обязательную последующую проверку в клиентской сцене описывает руководство по AnimationViewer и ParticleViewer.

Просмотрщик частиц

Откройте Windows -> Particle viewer в Mapper или запустите автономную цель <DevName>_ParticleViewer. Это внеэкранный просмотрщик запечённых ресурсов .spk и .efk, известных ParticleSpriteFactory. Он использует штатный путь ParticleSystem и предоставляет seed, loop, prewarm, direction, zoom/pan, root, draw-frame и wireframe. Частицы прямой сцены показываются через авторский маршрут, включая снимок фона, когда эффект запрашивает искажение сцены.

Интерактивный предпросмотр выше нужен, когда важны размещение и глубина карты. Специализированный просмотрщик ускоряет проверку геометрии и кадров. Ни один из них не заменяет репрезентативную клиентскую сцену для проверки времени жизни вложений, игровых таймингов или производительности.

Полный процесс проверки частиц и границу между просмотром запечённого ресурса, размещением в Mapper и игровой проверкой описывает руководство по AnimationViewer и ParticleViewer.

API вида и захвата

Метод	Назначение
`Game.GetCurMapHexSize()`	Вернуть гексовые размеры текущей карты.
`Game.GetCurMapPixelSize()`	Вернуть полные пиксельные границы карты.
`Game.SetMapperViewSize(size)`	Изменить размер render view Mapper.
`Game.CenterMapperOnPlayableArea()`	Центрировать по правилам игровой области текущей карты.
`Game.CenterMapperOnHex(hex)`	Центрировать по проверенному гексу карты.
`Game.CenterMapperOnRawHex(rawHex)`	Центрировать по сырым координатам, включая точку вне авторского прямоугольника.
`Game.SetMapperZoom(zoom)`	Немедленно применить масштаб камеры.
`Game.CalcMapperFitZoom(viewport)`	Рассчитать масштаб для размещения игровой области в области просмотра.
`Game.SetMapperOverlayVisible(visible)`	Одновременно переключить только mapper-оверлеи треков и границы прокрутки.
`Game.SetMapperHexOverlayVisible(visible)`	Переключить оверлей гексовой сетки.
`Game.SetMapperHiddenSpritesVisible(visible)`	Включить или скрыть спрайты, помеченные как скрытые при обычном клиентском рендере.
`Game.AddMapperIgnoredItemPids(pids)`	Добавить id прототипов предметов в список игнорирования текущей карты и пересобрать её.
`Game.SetMapperScrollCheckEnabled(enabled)`	Включить или выключить ограничение камеры авторскими границами прокрутки.
`Game.SaveMapperScreenshot(path)`	Перерисовать и синхронно сохранить render target карты в PNG через тот же encoder движка, который используется для клиентских снимков; окна ImGui уровня приложения не включаются.
`Game.DumpAtlases()`	Сохранить диагностические PNG-копии живых атласов текстур с оверлеями размещения и мешей спрайтов.

CalcMapperFitZoom использует ScrollAxialArea, если она задана, иначе границы карты. Пакетный инструмент может применить дополнительный проектный коэффициент отступа, когда высокие спрайты, тени или эффекты выходят за игровую область.

CenterMapperOnRawHex и отключённая проверка прокрутки полезны, когда проект намеренно снимает overscan-кадр. Интерактивные инструменты Mapper обычно должны сохранять проверку включённой, чтобы камера соблюдала авторские границы. В штатном UI Ctrl+D переключает проверку прокрутки текущей карты, а Ctrl+B размечает заблокированные гексы.

Интерактивная команда Dump atlases и Game.DumpAtlases() используют один и тот же неразрушающий диагностический путь. Считанная копия отмечает рёбра и вершины полигонов, неявные квады и явно пустые кадры, не меняя текстуру runtime-атласа. Точные цвета и правила времени жизни описаны во frontend и рендеринге.

Текущие ограничения: известная область

В режиме Mapper каждый анимированный предмет карты намеренно заморожен в моменте 0.0. ItemHexView::RefreshAnim() останавливает загруженный спрайт и выбирает первый кадр вместо запуска обычного воспроизведения. Поэтому интерактивные виды Mapper и headless-снимки остаются детерминированными для дверей, контейнеров и других многокадровых предметов карты.

Это правило авторинга и захвата, а не гарантия runtime-представления. Проверяйте тайминги анимации, переходы и итоговое визуальное состояние в клиентской сцене. Интерактивная проверка анимации криттеров является отдельным инструментом Mapper и не заморожена этим правилом предметов карты.

Интеграция headless-захвата

Render.HeadlessWindow=True создаёт скрытое окно render host, сохраняя графический путь для внеэкранного рисования. Настройка не определяет пакетный протокол; этой оркестрацией владеет mapper-скрипт встраивающего проекта.

Переиспользуемый пакетный драйвер выполняет последовательность:

Подписывает mapper-функции на Game.OnStart и Game.OnLoop.
Читает проектное описание пакета из конфигурации или файла данных.
Загружает и показывает одну карту.
Настраивает размер вида, оверлеи, игнорируемые id прототипов, видимость скрытых спрайтов, проверку прокрутки, центр и масштаб.
Ожидает достаточно циклов для стабилизации обработки и рисования карты.
При необходимости выгружает диагностику атласов, затем вызывает Game.SaveMapperScreenshot с выходным путём PNG.
Выгружает карту и переходит к следующему элементу пакета.
После завершения пакета вызывает общий Game.RequestQuit().

Game.OnLoop вызывается до MapperEngine::DrawMapperFrame(). SaveMapperScreenshot явно рисует кадр перед чтением главного render target, но только что показанной карте всё равно могут потребоваться прогревочные циклы для стабилизации ресурсов и вида. Их количество является политикой проекта и должно проверяться на самых тяжёлых ассетах его карт.

Для множества карт с общим набором ресурсов предпочтительна пакетная обработка в одном процессе: запуск Mapper, загрузка скриптов и инициализация графики выполняются один раз.

Контракт снимка

SaveMapperScreenshot является синхронным маршрутом снимка только карты:

отклоняет пустой выходной путь;
требует текущую карту;
вызывает DrawMapperFrame() для обновления промежуточного главного render target;
считывает RGBA-пиксели из этой цели;
переворачивает строки, если render texture сообщает инвертированную высоту;
нормализует относительный выходной путь внутри Common.UserWritablePath и записывает через общий для движка помощник ImageWriter::WritePng.

Метод захватывает рисование скриптового интерфейса Mapper, уже находящееся в цели карты, но не более поздние меню и окна ImGui уровня приложения.

В Engine script API нет метода захвата полного окна. Синхронный метод подходит для детерминированных пакетных кадров карт. Для руководств, отчётов об ошибках и доказательств регрессии UI запустите воспроизводимый видимый профиль и захватите окно приложения platform screenshot tool. Исполняемый рецепт минимального примера приведён в интерактивном руководстве по Mapper.

Script method непосредственно создаёт PNG. Конвейер снимков документации движка может регистрировать внешний visible-window capture, после чего закрепляет точный исходник, размеры, хэш изображения, окружение и триггеры повторного захвата в BuildTools/DocumentationScreenshots.json. Конвертация, обрезка, ограничения размера, анализ alpha-bound и регистрация ассета конкретного проекта остаются его ответственностью, пока переиспользуемый помощник не будет сознательно перенесён в движок.

Если подсистема рендера не предоставляет читаемый главный render target, метод выбрасывает исключение вместо создания пустого изображения. Заявленную поддержку подсистемы следует проверять на неоднородной тестовой карте с проверкой пикселей, а не только по наличию файла.

Помощники вкладок и оверлеев

Тот же файл экспорта предоставляет управление вкладками Mapper (TabGet*Pids, TabSet*Pids, TabDelete, TabSelect, TabSetName), сообщения редактора, выделение и проверку оверлеев. Они полезны для пользовательских UI-скриптов Mapper, но не зависят от headless-захвата.

Полную карту поверхности привязок на стороне Mapper предоставляет карта скриптовых методов. Впоследствии сгенерированный справочник API заменит списки методов, поддерживаемые вручную.

Проверенные пути исходников

Source/Tools/Mapper.cpp
Source/Tools/ParticleEditor.h
Source/Tools/ParticleEditor.cpp
Source/Tools/SparkParticleEditor.h
Source/Tools/SparkParticleEditor.cpp
Source/Scripting/MapperGlobalScriptMethods.cpp
Source/Scripting/ClientGlobalScriptMethods.cpp
Source/Scripting/CommonGlobalScriptMethods.cpp
Source/Common/Settings.inc
Source/Common/Geometry.cpp
Source/Client/MapView.cpp
Source/Client/TextureAtlas.cpp
Source/Client/ParticleSprites.h
Source/Client/VisualParticles.h

Контрольный список проверки

Соберите цель Mapper встраивающего проекта после изменения экспортов.
Скомпилируйте минимальный mapper-скрипт, который загружает, показывает, снимает, выгружает карту и завершает процесс.
Выполните один видимый интерактивный smoke-тест Mapper, чтобы подтвердить неизменность поведения редактора.
Выполните один захват с Render.HeadlessWindow=True и проверьте размеры и неоднородность пикселей.
Захватите одно видимое окно приложения platform screenshot tool и проверьте наличие требуемых меню и окон инструмента.
Просмотрите один запечённый эффект каждой включённой подсистемы частиц; для изменений редактора SPARK сохраните и повторно загрузите один исходник .spark.
После изменения диагностики атласов выгрузите один прогретый атлас и проверьте маркеры мешей, квадов и пустых кадров.
Подтвердите, что SaveMapToPath отклоняет обход пути и записывает только ниже корня источника карт.
Не переносите на эту страницу проектные настройки пакета, id прототипов, форматы результатов и последующие инструменты.

См. также

Инструменты для владения приложениями Mapper и editor.
Интерактивное руководство по Mapper для штатного рабочего процесса человека.
Инструменты создания частиц для работы Particle Preview и редактора исходников.
AnimationViewer и ParticleViewer для специализированных просмотрщиков.
Формат карт для синтаксиса контейнеров, размещения, владения, round-trip Mapper и запекания карт.
Формат частиц для исходников, запекания и runtime-поведения частиц.
Карты и перемещение для координат и геометрии игровой области.
Frontend и рендеринг для владения render target, атласами, мешами спрайтов и frontend.
Скриптовая среда для регистрации скриптов и событий на стороне Mapper.