Конфигурация игрового проекта

Руководство показывает, как embedding project должен создавать .fomain, resource packs и именованные sub-configs. Точная runtime model описана в Конфигурация и источники данных, а актуальные имена встроенных settings приведены в generated settings reference.

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

• Source/Common/Settings.h
• Source/Common/Settings.cpp
• Source/Common/Settings.inc
• Source/Frontend/ApplicationInit.cpp
• Source/Tests/Test_Settings.cpp
• BuildTools/cmake/stages/ScriptsAndBaking.cmake
• Examples/MinimalProject/CMakeLists.txt
• Examples/MinimalProject/FOnlineStarter.fomain
• Examples/MinimalMultiplayer/CMakeLists.txt
• Examples/MinimalMultiplayer/FOnlineMinimalMultiplayer.fomain

Начните с исполняемого baseline

Для первого headless-запуска используйте структуру MinimalProject, для client/server игры: MinimalMultiplayer. Сохраняйте игровой репозиторий корнем CMake и явно задавайте master config:

include(Engine/BuildTools/Init.cmake)

SetOption(FO_MAIN_CONFIG "MyGame.fomain")
SetOption(FO_DEV_NAME "MYGAME")
SetOption(FO_NICE_NAME "My Game")

FO_MAIN_CONFIG является configure-time project option. Содержимое .fomain задает runtime и baking settings. Не переносите product values в defaults движка только ради отказа от сопровождения project file.

Common.ResourcesPath задаёт runtime-каталог ресурсов, default Resources. Серверная клиентская раздача находится в его дочернем Client. CMake-параметров каталога ресурсов нет. Packaged bootstrap читает только эту зашитую строку до выбора одного полного профиля; CLI overrides сохраняются.

Порядок приоритетов

Для unpackaged application settings применяются в таком порядке:

1. выбранный .fomain, найденный через -ApplyConfig или подъем по каталогам до FO_MAIN_CONFIG;
2. каждый явно выбранный -ApplySubConfig в порядке command line;
3. local config установленного клиента в writable cache, если он существует;
4. обычные command-line setting overrides;
5. platform/build auto-settings.

Packaged-запуск выбирает ресурсный профиль либо бинарный при отсутствии optional ресурсов и применяет только его к нулевому объекту. Defaults перед ним не применяются. Фиксированная область binary patch равна 40000 байт и проверяется при упаковке. Профили содержат все ненулевые объявленные значения вместо metadata deltas; пропущенные типизированные значения остаются нулём после загрузки metadata. Затем следуют local config, CLI и auto settings. Packaged -ApplySubConfig сообщается через FO_VERIFY_AND_CONTINUE; профиль выбирается при упаковке.

В авторском конфиге задавайте все обязательные настройки, включая намеренные нули. Фильтрация принадлежит baker. Baking.BootstrapGameSettings сохраняет проверку имён; все ненулевые game settings уже доступны в ApplicationInitHook.

В authored files и operational commands используйте fully qualified names, например Server.DbStorage. Parser принимает короткие имена встроенных settings, но qualified names делают ownership и review однозначными.

Корневые settings

Записывайте по одному намеренному значению в строке:

Common.GameName = My Game
Common.GameVersion = 0.1.0

Network.ServerPort = 4000
Network.WebSocketPort = 4001

Server.DbStorage = Memory
ServerNetwork.DisableNetworking = False

Baking.BakeLanguages = engl russ
Baking.BakeOutput = Baking
Common.ResourcesPath = Resources
Common.PlatformBinariesPath = PlatformBinaries
Common.CachePath = Cache

ManagedScript.Assemblies = MyGame
ManagedScript.ProjectName = MyGame
ManagedScript.TargetFramework = net10.0
ManagedScript.MsBuild = dotnet msbuild
ManagedScript.Dirs = Engine/Source/Scripting/Managed/CoreScripts Scripts
ManagedScript.Analyzers = Engine/Source/Scripting/Managed/Analyzers/FOnline.Analyzers.csproj

Неизвестные имена становятся project custom settings и доступны через GetCustomSetting / FindCustomSetting. Это намеренное поведение для game-owned configuration, но опечатка в имени built-in setting поэтому может выглядеть допустимой. Добавляйте focused project test для каждого content ID, port/profile, prototype name, path или custom setting, влияющего на startup или gameplay.

Значения с начальным + накапливаются вместо замены. Strings добавляются через пробел, vectors получают новые elements, числовые значения складываются, booleans используют logical OR, а enums: bitwise OR. Используйте это осознанно и проверяйте итоговое значение, не предполагая list-only behavior. $ENV{NAME} и $FILE{path} разрешаются при чтении authored config, в том числе во время baking, поэтому конкретные значения могут попасть в generated internal configs. $TARGET_ENV{NAME} и $TARGET_FILE{path} остаются directives во время baking и разрешаются только тогда, когда их читает target application; текущий packager не предоставляет общий resolver target directives. Не храните credentials в tracked config, используйте target forms для runtime secrets и следуйте Security and Secrets для command-line, logging, signing, CI, rotation и artifact boundaries.

Определение resource packs

Resource pack выбирает inputs, bakers и runtime recipients:

[ResourcePack]
Name = Protos
InputDirs = Content Maps
IncludePatterns = **
ExcludePatterns = **/Draft/**
Bakers = Proto

[ResourcePack]
Name = Maps
InputDirs = Maps
IncludePatterns = **/*.fomap
Bakers = Map

[ResourcePack]
Name = ServerScripts
InputDirs = Scripts
IncludePatterns = **/*.fos
Bakers = AngelScript
ServerOnly = True

[ResourcePack]
Name = ManagedScripts
InputDirs = Engine/Source/Scripting/Managed/CoreScripts Scripts
IncludePatterns = *
Bakers = Managed

Выбирайте backend явно. Pack AngelScript запекает модули .fos через AngelScriptBaker; pack Managed компилирует настроенные top-level исходники .cs и generated API в target-specific assemblies. Managed pack должен включать Engine CoreScripts и проектные исходники из ManagedScript.Dirs; согласуйте с той же сборкой настройки assemblies, analyzers, extra sources/references и generated directory. Полный контракт backend описан в Скриптах Managed C#.

Допустимые fields:

Не более одного side-only flag может быть true. Без flags pack поставляется server и client. Mapper-only packs отделены. RecursiveInput встречается в старых project files, но не является текущим field ResourcePackInfo; рекурсию задавайте через IncludePatterns = **.

Разделяйте packs, если различаются ownership, release cadence, side visibility или update policy. Не используйте pack order как скрытую систему gameplay overrides: duplicate resource identities требуют явной project policy и test.

Добавление именованных sub-configs

Sub-configs являются reviewed overlays для launch mode:

[SubConfig]
Name = LocalDev
Server.DbStorage = Memory
ServerNetwork.DisableNetworking = False
Render.RenderDebug = True

[SubConfig]
Name = TutorialSmoke
Parent = LocalDev
Tutorial.Automation = True
Render.HeadlessWindow = True
Render.NullRenderer = True
Audio.DisableAudio = True

Имена Parent должны ссылаться на более ранние sub-config sections. Несколько parents применяются слева направо: поздние parents переопределяют ранние по key, затем побеждает дочерняя section. Launch может передать несколько -ApplySubConfig, они применяются в command-line order.

Используйте -ApplySubConfig NONE для generation/baking commands, которые должны читать только master config. BuildTools делает это для CompileAngelScript, CompileManagedScripts, BakeResources и ForceBakeResources.

Держите sub-configs узкими:

• environment modes выбирают infrastructure и diagnostics;
• tests выбирают deterministic fixtures и headless behavior;
• scenes выбирают startup content;
• release modes выбирают product-safe settings;
• secrets не находятся в sub-configs.

Проверка изменения конфигурации

1. Повторите configure embedding project, если изменились CMake options или main config path.
2. Выполните CompileAngelScript и/или CompileManagedScripts для каждого включённого backend, чьи script inputs, generated API, analyzers или metadata изменились.
3. Выполните BakeResources; используйте ForceBakeResources после изменения pack membership, baker selection, include/exclude patterns, language sets или migration rules.
4. Запустите самый узкий sub-config, использующий измененный setting.
5. Проверьте startup logs на Apply config, Apply sub config, unknown/missing files, skipped languages, missing bakers и side resource entries.
6. Выполните project test, разрешающий custom settings и content-backed references.
7. Один раз выполните build/package, если изменилась internal config или composition runtime resource entries.

Два примера движка служат исполняемыми configuration fixtures:

(cd Examples/MinimalProject && python3 validate.py)
(cd Examples/MinimalMultiplayer && python3 validate.py)

В Windows используйте варианты с win64-.

Частые ошибки

Дисциплина обновлений

При обновлении Engine или embedding project проверяйте изменения Settings.inc, Settings.cpp, ApplicationInit.cpp, BuildTools project options, baking stages и диапазона project .fomain. В том же change обновляйте руководство, project config, tests и generated references, если изменились precedence, fields, defaults, pack routing или launch profiles.

Опциональные native-компоненты

Перечислите используемые компоненты через SetOptionValues до StartProjectGeneration. Каждая опция — BOOL, по умолчанию OFF, с числовым дефайном 0/1. Общего списка выбора нет. Исходники и Engine-заголовки регистрируются и подключаются всегда; опциональное содержимое закрыто guards внутри файлов.

SetOptionValues(
    FO_DATABASE_SQLITE ON
    FO_DATA_SOURCE_DAT ON
    FO_IMAGE_FRM ON)

Memory обязательна в Server; для Baker обязательны PNG/TGA/FOFRM и libpng, а для аудио — WAV/Ogg и Vorbis/Ogg. Embedded/APK сохраняют minizip при внешнем ZIP OFF. Stock client читает baked sprites и Vorbis-аудио без импортёров исходников и драйверов БД.

Старые FO_DISABLE_MONGO/FO_DISABLE_SQLITE завершаются ошибкой; удалите их из кеша/окружения и выберите положительные опции.

Отпечаток конфигурации бейкинга

Объявление опции регистрирует её тип и влияние на бейкинг. BAKING в DeclareBoolOption/DeclareValueOption или в начале группы Declare*Options включает опции в FO_BAKING_CONFIG_HASH. Опции без отметки исключаются; справочник опций показывает каждое решение.

Хеш учитывает идентичность проекта и выбор конфига, геометрию, лимиты моделей/эффектов, 3D, частицы, scripting backend и импортеры архивов/изображений/аудио. Провайдеры БД, диагностика, allocator, пути вывода и выбор native-целей не инвалидируют ресурсы.

CMake считает SHA-256 непосредственно перед генерацией кода, после предыдущих стадий и Codegen Pre hook. Имена сортируются, BOOL нормализуются в 0/1, границы строк сохраняются. Новые отмеченные проектные опции включаются автоматически; завершите их настройку до потребления значений в SetupCodeGeneration.

Baker пишет Resources.baking-config-hash и поле отчёта bakingConfigHash. Отсутствие/изменение отпечатка очищает устаревшие outputs и требует full bake независимо от FO_BUILD_HASH; прежние значения допускают incremental bake. Оба маркера удаляются до работы и записываются лишь после успешного запекания ресурсов. До упаковки повторите configure/build/bake.