FOnline Engine
Current master GitHub
Документация Docs/ru/how-to/tools/animation-particle-viewers.md

Просмотр анимации и частиц

Документация движка по специализированным инструментам AnimationViewer и ParticleViewer. Каталоги ресурсов проекта, критерии визуальной приёмки, пресеты сборки, состав пакетов и сохраняемые материалы ревью принадлежат проекту игры.

Назначение

Используйте специализированные viewer-инструменты, чтобы проверить одного криттера или один запечённый эффект частиц без запуска сервера, входа на карту и навигации по игровому клиенту. Оба инструмента используют те же клиентские сервисы прототипов, ресурсов, спрайтов, моделей, эффектов, шрифтов и рендера, что и игра, но выполняют минимальный собственный цикл кадров.

Инструменты отвечают на отдельные вопросы о содержимом:

Вопрос Инструмент
Какие пары анимаций доступны этому криттеру и корректны ли его масштаб, направление, корень, кадр, иерархия и вложения? AnimationViewer
Загружается ли запечённый эффект частиц выбранным runtime и как на него влияют seed, prewarm, направление, масштаб, кадр и непосредственное рисование в сцене? ParticleViewer
Правильно ли ресурс размещён по глубине и позиции карты? Mapper
Правильно ли ресурс ведёт себя с игровыми таймингами, вложениями, видимостью, сетью и нагрузкой? Репрезентативная сцена клиента

Для запроса сфокусированной проверки принимайте решение в таком порядке:

  1. Выбирайте AnimationViewer для clips криттера, масштаба 1.00x, Angle, Root, one-shot в сравнении с Loop, hierarchy, layers и attachments. Выбирайте ParticleViewer для baked particle identity, backend, Seed, Prewarm, Direction, scale, frame и direct-scene route.
  2. Записывайте точные ревизии Engine/project, конфигурацию, prototype или resource, renderer, controls и logs. Для частиц закрепляйте Seed, Prewarm и Direction, после изменения используйте Replay и сравнивайте atlas/frame drawing с Draw in scene.
  3. Считайте process-start smoke и pixels focused viewer только сфокусированным свидетельством. Продолжайте проверку в Mapper для placement, depth и composition и в репрезентативной client scene для timing, attachments, visibility, networking, renderer behavior и load.
  4. Сохраняйте captures и provenance каждого уровня раздельно; один screenshot viewer не может сделать ресурс production-ready.

Когда нужна команда запуска, копируйте полный platform block из раздела Сборка и запуск, включая смену working directory и точное написание --config. Не синтезируйте сокращённый cross-platform path из имени project target.

Специализированные viewer-инструменты предназначены для проверки, а не для редактирования. Mapper редактирует карты и исходники SPARK. Внешний Effekseer Editor редактирует исходники .efkproj. В текущем движке нет универсального приложения Editor, приложения AssetExplorer или реализации Source/Tools/AssetExplorer.*.

Контракт производственной проверки

Производственный ресурс проходит через отдельные слои доказательств. Не сводите их к одному снимку viewer-инструмента:

  1. проверьте авторский исходник и результат запекания средствами владеющего формата;
  2. используйте специализированный viewer, чтобы изолировать дефекты идентификатора, анимации или seed, направления, масштаба, границ, иерархии и маршрута рендера;
  3. используйте Mapper для проверки размещения, глубины и композиции карты;
  4. используйте репрезентативную сцену клиента для проверки игровых таймингов, владения вложением, видимости, сети, рендера и нагрузки;
  5. сохраните точные ревизии, конфигурацию, значения управления, логи и снимки, необходимые для воспроизведения принятого случая.

Проверка запуска процесса доказывает только достижение цикла кадров. Пустое окно MinimalMultiplayer доказывает наличие цели и путь без ресурсов, но не качество содержимого. Снимок специализированного viewer доказывает только изолированное состояние, видимое на снимке. Явно указывайте эти ограничения в ревью и отчётах автоматизации.

Проектам следует предоставить стабильные задачи сборки и запуска обоих viewer-инструментов и помещать бинарные файлы только в пакет разработчика, уже содержащий совместимые ресурсы. Закрепляйте проект на точной ревизии Engine, после изменения привязки пересобирайте или повторно запекайте ресурсы и заново проверяйте каждый затронутый слой. Last Frontier следует этой схеме через именованные проектом цели viewer-инструментов, задачи запуска VS Code, пакет только для разработчиков, проверку моделей в CharacterGenerator.md и приёмку частиц в Particles.md. Эти имена, ресурсы и политики проекта служат примерами, но не контрактами движка. FOnline TLA сейчас не предоставляет эквивалентный процесс специализированной проверки и не является нормативным доказательством для этих инструментов.

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

  • Source/Tools/AnimationViewer.h
  • Source/Tools/AnimationViewer.cpp
  • Source/Tools/ParticleViewer.h
  • Source/Tools/ParticleViewer.cpp
  • Source/Tools/Mapper.h
  • Source/Tools/Mapper.cpp
  • Source/Applications/AnimationViewerApp.cpp
  • Source/Applications/ParticleViewerApp.cpp
  • Source/Common/SettingsStorage.h
  • Source/Common/SettingsStorage.cpp
  • Source/Client/ResourceManager.cpp
  • Source/Client/ParticleSprites.h
  • Source/Client/ParticleSprites.cpp
  • BuildTools/cmake/stages/Init.cmake
  • BuildTools/cmake/stages/EngineSources.cmake
  • BuildTools/cmake/stages/CoreLibs.cmake
  • BuildTools/cmake/stages/Applications.cmake
  • BuildTools/cmake/ProjectInterface.json
  • BuildTools/PackageInterface.json
  • Examples/MinimalMultiplayer/CMakeLists.txt
  • Examples/MinimalMultiplayer/CMakePresets.json
  • Examples/MinimalMultiplayer/FOnlineMinimalMultiplayer.fomain

Граница приложения и владения

FO_BUILD_MAPPER=ON создаёт три приложения с именем проекта:

  • <DevName>_Mapper;
  • <DevName>_AnimationViewer;
  • <DevName>_ParticleViewer.

Цели viewer-инструментов компонуют AppFrontend, библиотеку конкретного viewer, ClientLib и BakerLib. Они не запускают Mapper, соединение с сервером, вход в игру, карты или ClientEngine::MainLoop(). Их hosts создают ClientEngine, продвигают время и менеджеры рендера, рисуют один полноэкранный инструмент ImGui и сохраняют пользовательские настройки viewer при завершении.

Приложения намеренно не вызывают игровой ClientStartupSettingsHook: здесь нет учётной записи, сетевой сессии, индекса встроенного клиента или игровой политики запуска, которую следовало бы настраивать.

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

Переиспользуемый интерфейс пакетов предоставляет AnimationViewer и ParticleViewer только как нативные цели Windows/Linux. Обе требуют NoRes: пакет содержит бинарный файл инструмента, но не вторую копию игровых ресурсов. Проект должен расположить инструмент рядом с совместимыми настроенными источниками данных либо включить его в пакет разработчика, уже владеющий этими ресурсами.

Сборка и запуск

Принадлежащий движку проект MinimalMultiplayer предоставляет конкретные имена целей и выходных каталогов. При конфигурации включите семейство целей Mapper.

В Windows:

Set-Location Examples\MinimalMultiplayer
cmake --preset windows -DFO_BUILD_MAPPER=ON
cmake --build Build\windows --config RelWithDebInfo --target BakeResources FOMM_AnimationViewer FOMM_ParticleViewer

Запускайте из сгенерированного рабочего каталога, чтобы относительные пути источников данных и запекания разрешались относительно FO_OUTPUT_PATH:

Set-Location Build\windows
.\Binaries\AnimationViewer-Windows-win64\FOMM_AnimationViewer.exe -ApplyConfig ..\..\FOnlineMinimalMultiplayer.fomain

Либо запустите viewer частиц:

Set-Location Build\windows
.\Binaries\ParticleViewer-Windows-win64\FOMM_ParticleViewer.exe -ApplyConfig ..\..\FOnlineMinimalMultiplayer.fomain

В Linux:

cd Examples/MinimalMultiplayer
cmake --preset linux -DFO_BUILD_MAPPER=ON
cmake --build Build/linux --config RelWithDebInfo --target BakeResources FOMM_AnimationViewer FOMM_ParticleViewer
cd Build/linux
./Binaries/AnimationViewer-Linux-x64/FOMM_AnimationViewer -ApplyConfig ../../FOnlineMinimalMultiplayer.fomain

Для второго viewer используйте Binaries/ParticleViewer-Linux-x64/FOMM_ParticleViewer. В проекте замените FOMM на FO_DEV_NAME и используйте пресет, выходной каталог, основную конфигурацию, включённые возможности содержимого и архитектуру платформы этого проекта.

MinimalMultiplayer намеренно не содержит проектных изображений, моделей и эффектов частиц, а оба particle backend в нём отключены. Он доказывает цели, запуск приложений, конфигурацию, renderer и пути пустого состояния без ресурсов. Для содержательной визуальной проверки нужен проект с ресурсами:

  • AnimationViewer требует хотя бы один ProtoCritter с загружаемым ModelName; проверка 3D также требует FO_ENABLE_3D.
  • ParticleViewer требует FO_SPARK_PARTICLES и/или FO_EFFEKSEER_PARTICLES, авторский исходник в запекаемом пакете частиц и полученный .spk или .efk.

Процесс проверки анимации

AnimationViewer размещает фильтр и список криттеров, фиксированное окно предпросмотра 512 на 512, список анимаций и иерархию 3D-модели.

  1. Перед проверкой запеките актуальные прототипы, изображения, модели и скрипты.
  2. Отфильтруйте список по ID прототипа и выберите точный ProtoCritter.
  3. Убедитесь, что показанный путь модели соответствует нужному ModelName и ошибка загрузки отсутствует.
  4. Установите Zoom в 1.00x для проверки игрового масштаба. Другие значения масштаба служат для исследования.
  5. Проверьте нужные направления через Angle или горизонтальное перетаскивание с удержанием левой кнопки. 2D-криттер переключается между направленными кадрами, а 3D-модель поворачивается непрерывно.
  6. Выберите Idle, затем каждую требуемую пару состояния и действия. Отключите Loop, чтобы доказать завершение одноразовой анимации и возврат в idle.
  7. По необходимости включите Root, Name level, Draw rect и View rect для проверки привязок и авторских границ.
  8. Для 3D-модели сравните рендер атласного спрайта с Direct draw, затем проверьте иерархию. Отметьте нужные кости и вложения, чтобы спроецировать их маркеры в окно предпросмотра.
  9. Сравните принятый ресурс в репрезентативной сцене клиента с теми же направлением, масштабом, состоянием слоёв и анимацией.

Левая кнопка вращает, правая перемещает, а колесо меняет масштаб, пока указатель находится над предпросмотром. Масштаб ограничен диапазоном от 0.25x до 8.00x. Выбор другого криттера сбрасывает перемещение, активную анимацию и маркеры иерархии.

Обнаружение анимаций

Для 3D-моделей viewer перечисляет точные пары (CritterStateAnim, CritterActionAnim), сообщённые ModelInformation. У 2D-криттеров нет авторской таблицы клипов, поэтому viewer проверяет через менеджер ресурсов разрешимые наборы кадров состояния и действия для текущего направления.

Визуальные слои модели определяются проектом. Viewer читает записи Render.ModelLayerProperties в форме <PropertyName>=<LayerIndex> и передаёт значения свойств выбранного прототипа в воспроизведение 3D-анимации. Отсутствующие или отключённые свойства игнорируются, а некорректные сопоставления записываются в лог приложения.

Direct draw влияет только на 3D-модели:

  • в выключенном состоянии рисуется обычный кэшированный атласный спрайт, а viewer увеличивает его пиксели;
  • во включённом состоянии геометрия рисуется прямо в предпросмотр, а zoom применяется как масштаб модели.

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

Процесс проверки частиц

ParticleViewer перечисляет запечённые расширения, объявленные активным ParticleSpriteFactory. При включённом SPARK список обычно содержит .spk, при включённом Effekseer - .efk. Авторские .spark и .efkproj не являются runtime-записями viewer.

  1. Включите нужный particle backend, запеките исходник и его зависимости, затем запустите viewer на этом точном результате.
  2. Отфильтруйте список по пути запечённого ресурса и выберите эффект. Ошибка загрузки остаётся видимой в окне и записывается в лог приложения.
  3. Задайте фиксированный Seed, отключите Loop и несколько раз нажмите Replay. Одинаковые сборка, backend, ресурс, seed, направление и последовательность обновлений должны воспроизводить одинаковый случай.
  4. Сравните выключенный и включённый Prewarm. Выключенное состояние показывает начальную эмиссию, включённое продвигает систему до первого показанного кадра.
  5. Поворачивайте эффект через Direction или перетаскивание с удержанием левой кнопки. Это воспроизводит направление, которое вложение криттера может передать эффекту.
  6. Перемещайте эффект удержанием правой кнопки и меняйте масштаб колесом. Перемещение перебазирует частицы в мировых координатах, поэтому проверка ведёт себя как движущийся emitter, а не как сдвиг неизменной картинки.
  7. Включите Root, Draw rect и Show wireframe, чтобы проверить опору на землю, атласный кадр и particle quads.
  8. Сравните авторский маршрут Draw in scene с альтернативным. Флажок меняет только живой объект предпросмотра и не редактирует и не сохраняет исходник.
  9. Проверьте принятый эффект в Mapper для размещения и глубины, затем в репрезентативной сцене клиента для игровых таймингов, времени жизни вложения, видимости, поведения renderer и производительности.

New seed увеличивает текущий seed и сразу перезапускает эффект. Replay перезапускает с текущим seed. Loop перезапускает конечный эффект после его остановки. Масштаб ограничен диапазоном от 0.25x до 8.00x.

Интерпретация атласа и прямого рисования в сцене

Атласный эффект растеризуется в авторский спрайтовый кадр при масштабе 1.0, после чего viewer увеличивает этот кадр. Эффект с прямым рисованием в сцене выводит реальную геометрию частиц в предпросмотр и применяет viewer zoom к системе частиц. Прямое рисование может показать quads или trails за пределами атласного кадра, тогда как атласный путь выявляет обрезку и фактическое поведение кэшированных пикселей.

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

Сохраняемые настройки

Viewer-инструменты сохраняют компоновку и состояние проверки при чистом завершении:

AnimationViewer ParticleViewer
Компоновка ImGui Компоновка ImGui
zoom и направление zoom и направление
флажки direct-draw и loop seed, loop и prewarm
overlays корня, уровня имени, render rect и view rect overlays корня, draw rect и wireframe
последний допустимый прототип последний допустимый путь ресурса

Текст фильтра, перемещение, активный клип, включённые маркеры иерархии и временное переопределение particle Draw in scene не сохраняются.

SettingsStorage размещает записи в области AnimationViewer или ParticleViewer. Windows использует HKCU\Software\FOnline\<application-name>. Другие платформы используют пользовательское хранилище движка. Сохранение выполняется по возможности: ошибки backend записываются в лог и не должны завершать инструмент.

Если содержимое изменилось после последнего запуска, удалённый прототип или ресурс не выбирается повторно. При диагностике неожиданного состояния сначала воспроизведите его с записанными сохранёнными выбором и флажками; очищайте только хранилище владеющего viewer, когда нужно сравнение с чистым состоянием.

Диагностика отказов

Симптом Что проверить
Цель viewer отсутствует Повторите конфигурацию с FO_BUILD_MAPPER=ON; viewer-инструменты входят в семейство целей Mapper.
Приложение не находит baker или ресурсы Запускайте из настроенного FO_OUTPUT_PATH и применяйте правильную конфигурацию проекта.
Список криттеров пуст Убедитесь, что пакеты прототипов смонтированы и запечены для стороны клиента/Mapper.
В прототипе не объявлена модель Задайте допустимый ProtoCritter.ModelName; игровые fallback-заглушки не создают авторский контракт анимации.
Модель не загружается Проверьте путь ресурса, результат запекания изображений/моделей, включённую поддержку 3D и лог приложения.
Нет записей анимаций Для 3D проверьте таблицу анимаций .fo3d; для 2D убедитесь, что направленные ресурсы кадров состояния и действия разрешаются.
Ожидаемая одежда или слои модели отсутствуют Проверьте Render.ModelLayerProperties, индексы слоёв и значения выбранного прототипа.
Список частиц пуст Включите хотя бы один particle backend, добавьте particle baker и убедитесь, что .spk/.efk присутствует в смонтированном результате.
Частица не загружается Проверьте видимую ошибку и лог, затем возможности backend, зависимости, границы атласа и запечённый формат/версию.
Сравнение seed расходится Зафиксируйте сборку, содержимое, backend, постоянный timestep/нагрузку, направление, prewarm, масштаб и число обновлений.
В viewer всё правильно, а в игре нет Воспроизведите в Mapper/клиенте; специализированные viewer не содержат глубину карты, игровое владение, сетевое состояние, жизненный цикл вложений и репрезентативную нагрузку.

Материалы ревью и снимки

Сохраняемая запись ревью должна указывать:

  • точные ревизии Engine и проекта вместе с состоянием dirty;
  • цель, конфигурацию, компилятор, платформу, архитектуру, renderer, драйвер, размер окна, масштаб DPI и ограничение кадров;
  • выбранный прототип или путь запечённой частицы и ревизию содержимого;
  • все нестандартные значения управления, пару анимаций или seed и backend;
  • исходный ресурс, лог запекания, лог приложения, снимок и последующий результат приёмки в Mapper/клиенте.

Снимайте всё окно viewer после загрузки ресурсов и появления стабильного состояния проверки. Не обрезайте выбранный ID/путь, элементы управления, overlays или диагностическую ошибку. Публичные снимки требуют лицензированного содержимого, описательного alt text, точного происхождения сборки/тега и условия повторного захвата при изменении UI, renderer, выбранной fixture или политики приёмки.

Сейчас viewer-инструменты не предоставляют script API, выбор из командной строки, создание снимков или headless API проверки. Не называйте ручной снимок автоматизированным доказательством регрессии. Для переиспользуемой автоматизации нужно намеренно добавить стабильный интерфейс выбора, управления и захвата, тесты и документацию.

Сопровождение

Обновляйте это руководство в том же изменении, когда меняются:

  • имена целей viewer, связь с FO_BUILD_MAPPER, выходные пути, связи приложений или роли пакетов;
  • монтирование источников данных viewer, startup hooks, жизненный цикл кадра или сохранение при завершении;
  • обнаружение AnimationViewer, сопоставление слоёв, прямое рисование, управление, иерархия, вложения, overlays или ввод;
  • обнаружение расширений ParticleViewer, поведение seed/prewarm/loop, направление, перемещение, прямое рисование в сцене, wireframe, overlays или ввод;
  • backend, область, ключи или обработка ошибок SettingsStorage;
  • встраивание, переименование или удаление одного из viewer в Mapper;
  • добавление стабильной автоматизации или интерфейса создания снимков.

Запустите специализированный тест документации, соберите обе цели viewer, запустите каждую с текущим проектом и выполните минимальный затронутый видимый процесс. Изменения particle backend также требуют тестов формата частиц и репрезентативной сцены клиента. Изменения модели или анимации также требуют формат модели, анимацию модели и владеющие тесты моделей.

См. также

Введите запрос.