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

Процесс сборки

Этот документ объясняет, как работать со сборками FOnline, не перенося предположения одного проекта в другой.

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

  • ../BuildTools/README.md
  • ../BuildTools/Init.cmake
  • ../BuildTools/validate.sh
  • ../BuildTools/validate.cmd
  • ../BuildTools/buildtools.py
  • ../BuildTools/docs_cli.py
  • Docs/ru/reference/buildtools/index.md
  • ../BuildTools/PackageInterface.json
  • ../BuildTools/docs_package.py
  • ru/reference/packages/index.md
  • ../Examples/MinimalProject/
  • ../Examples/MinimalMultiplayer/
  • ../BuildTools/cmake/stages/Init.cmake
  • ../BuildTools/cmake/stages/ProjectOptions.cmake
  • ../BuildTools/cmake/stages/EngineSources.cmake
  • ../BuildTools/cmake/stages/Codegen.cmake
  • ../BuildTools/cmake/stages/ScriptsAndBaking.cmake
  • ../BuildTools/cmake/stages/Applications.cmake
  • ../BuildTools/cmake/stages/Packages.cmake
  • ../BuildTools/cmake/stages/Finalize.cmake
  • ../BuildTools/cmake/helpers/*.cmake
  • ../Source/Applications/TestingApp.cpp
  • ../Source/Tests/README.md

Используйте игровой проект как корень сборки

Обычно FOnline собирается через репозиторий игры, в который движок подключен как Engine/. Выполняйте configure и build из корня игры, если конкретная engine-only команда не требует иного.

Причины:

  • имена targets задает проект;
  • .fomain управляет конфигурацией конкретной игры;
  • generated scripting API зависит от проекта;
  • имена пакетов, signing, ресурсы и deployment settings принадлежат продукту;
  • platform presets обычно находятся в CMakePresets.json игрового проекта.

Обычный процесс

  1. Откройте корень репозитория игры.
  2. Проверьте доступные presets через CMake или IDE-интеграцию проекта.
  3. Настройте самый узкий preset, покрывающий изменение.
  4. Соберите минимальный подходящий target.
  5. Выполните соответствующий test, package или launch target.
  6. Обновите документацию, если процесс или поведение изменились.

Первая сборка, принадлежащая движку

В репозитории есть одно стабильное исключение из проектных имен targets: Examples/MinimalProject. Пример доказывает чистый headless-путь встраивания без Last Frontier, TLA или другого игрового checkout.

Из корня движка выполните validation target своей host-платформы:

cd Examples\MinimalProject
python validate.py

cd Examples/MinimalProject
python3 validate.py

Оба маршрута настраивают и собирают baker и headless server, выполняют baking минимального AngelScript-проекта, запускают сервер без networking с in-memory database и требуют lifecycle markers из руководства Первый headless-проект FOnline. Закрепленные Windows- и Linux-lanes проверены в CI.

Следующий маршрут движка собирает desktop client, headless client, headless server и baker, затем проверяет metadata, content, login, загрузку карты, локализованный текст, remote calls и replicated state:

cd Examples\MinimalMultiplayer
python validate.py

cd Examples/MinimalMultiplayer
python3 validate.py

Исходники и ручной запуск описаны в Minimal Multiplayer и Первом игровом клиенте.

Предварительные требования

Перед тем как превращать build profile в заявление о поддержке релиза, проверьте матрицу поддержки. Generated matrix различает обязательную компиляцию, исполняемое smoke evidence и source-only profiles; приемка device, renderer, package, service и store остается ответственностью проекта.

Точный набор зависит от host OS и целевой платформы, но обычно нужны:

  • Git;
  • CMake;
  • Python 3;
  • compiler/toolchain с поддержкой C++20;
  • platform SDK для собираемых targets;
  • Visual Studio или Build Tools для Windows-процессов;
  • Emscripten и Node.js для Web;
  • JDK и Android NDK для Android.

Предпочитайте инструкции игрового проекта: он может закреплять конкретные версии SDK и инструментов.

Контур совместимости с Windows 7

Build-platform keys win32-win7 и win64-win7 являются native Windows MSVC lanes с toolset v143,version=14.44; на не-Windows host они завершаются сразу. FO_BINARY_OUTPUT_POSTFIX задает независимую identity сборки и не следует из суффикса -win7 в имени платформы. Если проект собирается, например, с Win7, соответствующая package declaration должна использовать то же значение только в этой записи: BINARY Client Windows win32-win7 Raw+Zip+Wix POSTFIX Win7.

До packaging или публикации проверьте каждый связанный EXE и DLL:

python BuildTools/check_windows7_imports.py --require-large-address-aware <client.exe> <client-runtime.dll>

Проверка разбирает PE imports и отклоняет перечисленные в разделе Тестирование экспорты Windows 8+, отсутствующие библиотеки и неподдерживаемые API-set contracts. Это относится и к статически связанному managed runtime. Успешная статическая проверка не заменяет запуск на настоящей Windows 7 SP1. Установка toolset, пути к binary, package matrix, CI gate и приёмка на живом хосте принадлежат игровому проекту.

Адресное пространство Windows x86

AddExecutableApplication в BuildTools/cmake/helpers/Build.cmake добавляет /LARGEADDRESSAWARE всем 32-битным Windows executables движка: client hosts, headless applications, servers и tools. Решение зависит от платформы и размера указателя, а не имени project target или binary postfix; shared libraries не задают предел процесса.

На 64-битной Windows флаг позволяет x86-процессу использовать до 4 GB пользовательского адресного пространства вместо 2 GB. На 32-битной Windows 7 стандартный предел остаётся 2 GB; физическую RAM флаг не увеличивает. check_windows7_imports.py --require-large-address-aware проверяет PE flag готового EXE вместе с совместимостью imports и не требует этот flag от DLL. Обе проверки не доказывают загрузку реальных карт, устойчивое потребление памяти или приёмку на настоящей Windows 7.

Загрузка через собственное зеркало

prepare-workspace скачивает toolset, Android SDK/NDK, MSVC SDK и исходники LLVM у тех, кто их публикует. Каждая из этих машин вам не принадлежит, и оборванное соединение стоит времени задаче, которая его ждёт. Встраивающий проект может поставить перед ними собственный host; движку нужно лишь сообщить, где он, поэтому про этот host ничего не вкомпилировано и всё едет в переменных окружения:

переменная что настраивает
FO_DOWNLOAD_MIRROR Базовый URL pull-through зеркала. https://host/path скачивается как <mirror>/host/path.
FO_WORKSPACE_CACHE Базовый URL для подготовленных workspace. Emscripten получает ключ из версии SDK, host OS и architecture; дерево MSVC SDK — из версии xwin и набора architectures. Каждое полное дерево собирается один раз и дальше скачивается целиком.
FO_CI_TOKEN Bearer-токен для двух адресов выше. Он отправляется только на их собственные scheme и host, никогда на вышестоящий.
FO_CI_CA Дополнительные корни доверия, добавляемые к системному хранилищу, а не заменяющие его, для машины, чьё хранилище починить нельзя.

Если переменная не задана, путь загрузки остаётся ровно прежним.

Два поведения выбраны намеренно. Загрузка сверяется с Content-Length источника, потому что оборванное соединение завершает чтение, а не бросает исключение, и обрезанный пополам архив распаковывается в ошибку далеко от своей причины. А пустой, недоступный или отказывающий кэш workspace — это только промах: он существует, чтобы ускорить сборку и снять её зависимость от чужих серверов, а не чтобы стать ещё одним способом её уронить.

emsdk и xwin сами скачивают свои пакеты, поэтому зеркалирование прямых загрузок движка их не покрывает. Кэш workspace хранит их полностью подготовленные результаты. Повреждённый или неполный объект Emscripten отбрасывается и пересобирается локально; создание и upload кэша остаются best-effort. Cached trees распаковываются через стандартный data-only tar filter после проверки границ paths. Распаковка сначала идёт во временный соседний каталог, и только ожидаемое полное SDK directory продвигается на рабочее место, поэтому archive не может перезаписать другое подготовленное workspace tree. Кэш xwin следует тому же правилу restore.

Где находится логика сборки

Точные основные команды, arguments, defaults, choices и исполняемый help приведены в generated справочник BuildTools CLI.

Generated package interface reference определяет grammar DefinePackage, допустимые targets/platforms/architectures, совместимость pack tokens, payload layouts и output artifacts. Порядок build/bake/package, platform procedures, artifact evidence, signing, acceptance и recovery boundaries описаны в упаковке и выпуске. Конкретная package matrix игры остается в документации этой игры.

Для library, SDK, framework или runtime payload, принадлежащего игровому репозиторию, следуйте Project-Local Dependencies. Создайте project CMake target, добавьте его в самый узкий потребляемый список FO_*_LIBS, поддерживаемый закреплённой ревизией, и проверьте и compiled feature state, и packaged runtime state.

  • Обзор BuildTools.
  • конвейер BuildTools описывает staged CMake pipeline и маршрутизацию изменений.
  • ../BuildTools/cmake/ содержит reusable CMake modules и staged generation/build/package logic.
  • ../BuildTools/Init.cmake является project-facing CMake entry point и строгим stage dispatcher.
  • Корень игрового проекта владеет product presets, configuration и выбором targets.

Проверка по типу изменения

Если меняется BuildTools/buildtools.py::create_parser(), сначала перегенерируйте и проверьте CLI model/pages, затем проверяйте затронутую команду в реальном игровом проекте.

Если меняются package declarations или payload behavior, обновите BuildTools/PackageInterface.json, перегенерируйте и проверьте model/pages, запустите validate_package_interface.cmake и test_packaging_matrix.py, затем соберите RunPackagingChecks, RunTutorialPackageChecks или более узкий product package target из владеющего примера или проекта. Эти example targets являются необязательными и не входят в обязательный реестр проверок Engine. Engine fixtures доказывают native raw/archive/config/updater mechanics, но не заменяют signing, install, deployment или rollback lane игры.

Поддерживаемость документации сборки

Не копируйте полный список presets в документацию движка. Presets меняются между играми и branches. Объясняйте ownership и ссылайтесь на проектный документ, которому принадлежат точные команды.

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

  1. До публикации точного имени убедитесь, что command или preset принадлежит игровому проекту.
  2. Для BuildTools changes повторите configure самого узкого preset и выполните generated target, использующий измененный stage.
  3. Для runtime changes сначала выполните focused tests, затем project RunUnitTests, когда это практично.
  4. Для package/platform changes обновите владеющий package/debug document в том же изменении.
  5. При изменении самого build workflow обновите конвейер BuildTools, Тестирование или platform docs.
  6. Если BuildTools, baking, scripting, application startup или embedding boundary могут затронуть минимальный проект, запустите соответствующий starter smoke.
  7. Перегенерируйте затронутые contract models и выполните aggregate generated contract diff для изменений project-facing API, CMake, CLI или package.
Введите запрос.