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

Это руководство объясняет, откуда начинать навигацию по Source/. Оно дополняет краткий Source README.

Быстрая маршрутизация

• Изменение запуска executable или target entrypoints: Source/Applications/ и Applications.
• Изменение низкоуровневой platform/utilities: Source/Essentials/.
• Изменение общих entity/property/map/config/network primitives: Source/Common/.
• Изменение client-side runtime или views: Source/Client/.
• Изменение authoritative world/server behavior: Source/Server/.
• Изменение scripting integration или видимых скриптам native methods: Source/Scripting/.
• Изменение developer tools, baking, Mapper или editors: Source/Tools/.
• Изменение абстракции application/window/rendering: Source/Frontend/.
• Поиск примеров поведения или regression coverage: Source/Tests/.

Сначала переходите в каталог-владелец. Перед указанием конкретного файла, helper или target проверяйте его точное написание в текущем inventory исходного кода: соседние имена backend и сгенерированные проектом executable нельзя использовать как шаблоны.

Для developer tools различайте реализацию baker в Source/Tools/ и управление его сборкой. Восстановление отсутствующих сгенерированных файлов и зависимостей codegen принадлежит BuildTools/cmake/stages/Codegen.cmake и BuildTools/cmake/helpers/EnsureCodegenOutputs.cmake.in, а не runtime baker или Mapper. Для этой границы используйте BuildTools pipeline; при изменении поведения bake меняйте владельца самого native tool.

Оформление нативных модулей

Публичный native-модуль, чей заголовок используется другими единицами трансляции, оформляется соседней парой Name.h + Name.cpp. Оба файла регистрируются у владельца в EngineSources.cmake, CoreLibs.cmake или у целевого приложения в Applications.cmake. Общие пассивные данные и константы сохраняют опорный .cpp, как в паре ResourceDefaults.h + ResourceDefaults.cpp. Вспомогательные шаблонные, constexpr и агрегирующие заголовки допускают рассмотренные header-only исключения.

Единицам реализации без внешнего интерфейса заголовок не нужен. Удаляйте заголовки, подключаемые только собственным .cpp; не создавайте пустые файлы, обёртки над общим заголовком или повторные объявления generated script API ради формальной пары. Реализации рендереров, транспортов, script bindings и точек входа могут состоять только из .cpp. Списки исходников внутри владеющей цели сохраняются безусловными, а числовые feature guards размещаются внутри опциональных модулей.

После добавления или переноса модулей запускайте python3 BuildTools/check_native_modules.py. Он проверяет регистр имён пар и регистрацию у владельцев списков исходников, включая алиас каталога AngelScript и библиотечные цели приложений. .cpp без заголовка тоже обязан быть зарегистрирован. Комментарии и диагностические строки не регистрируют исходники. Рассмотренные header-only исключения и особые точки входа/шаблоны задаются точными путями и непустыми причинами в NativeModuleExceptions.json, версия схемы Version = 1. Устаревшие записи, шаблоны путей, повторные ключи и исключения для полных пар запрещены. Два Source/Common/*.template.cpp являются входными шаблонами генерации, а не компилируемыми модулями. Эффективную конфигурацию CMake проверяют сборки соответствующих платформ.

Первый include заголовка — #include "Common.h". .cpp начинает список include с соседнего одноимённого заголовка с точным регистром, если тот существует, иначе с Common.h. Этот include отделяется от следующего содержимого пустой строкой. Если он единственный и стоит в конце файла, дополнительная пустая строка не нужна. Лицензия и #pragma once могут предшествовать ему; условия препроцессора не меняют лексический порядок include. Bootstrap-заголовки не могут подключать Common.h: сам Source/Common/Common.h, заголовки непосредственно в Source/Essentials/ и Source/Common/ImGuiExt/ImGuiConfig.h сохраняют свой порядок зависимостей. ImGui подключает конфигурацию через IMGUI_USER_CONFIG; отсутствие буквального локального include не означает, что такой заголовок не используется.

Native-файл заканчивается ровно одним переводом строки: text\n или text\r\n. Отсутствие EOL, пробелы в конце и дополнительные пустые строки EOF запрещены. Formatter, layout-валидатор и обычная проверка Git whitespace следуют одной конвенции.

Вместе с проверкой модулей запускайте python3 BuildTools/check_native_source_layout.py. Он рекурсивно проверяет собственные .h/.cpp в Source/, кроме двух шаблонов генерации, и игнорирует ложные директивы в комментариях и строковых литералах. Ошибочная или пустая область возвращает ненулевой код. Расширения проекта проверяются с --root <project> --source-dir SourceExt --shallow, чтобы исключить вложенные импортированные библиотеки. Generated build output и ThirdParty/ не входят в authored scope. Оба валидатора и их регрессии обязательны в CI. Также проверяются --source-dir Examples и --source-dir BuildTools/validation-project.

Examples/NativeExtensionSample/SourceExt/NativeExtensionCore.h принадлежит самостоятельной C++-библиотеке, собираемой без заголовков Engine: он сохраняет стандартную библиотеку и не должен подключать Common.h. Её отдельный Tests/NativeExtensionCoreTest.cpp начинается с NativeExtensionCore.h. Эти точные границы проверяются явно; серверное расширение следует обычным правилам cpp-only.

Source/Applications/

Содержит точки входа приложений и библиотек. Примеры включают client, варианты server, Mapper, editor, baker, AngelScript compiler, Managed script baker и обёртки testing app. Wiring build targets находится в BuildTools/cmake/stages/Applications.cmake.

См. Applications.

Source/Essentials/

Низкоуровневые переиспользуемые primitives. Текущие файлы охватывают logging, core helpers, compression, containers, serialization, filesystem, exception handling, memory system, sockets, platform helpers, stack traces, string utilities, strong types, time helpers и worker threads.

Этот слой не должен получать game-specific rules. Он обязан оставаться пригодным для каждой runtime side.

Source/Common/

Общий runtime code для client/server/tools/scripts. Основные области:

• База движка и общая настройка: EngineBase.*, Common.*.
• Entities/properties/prototypes: Entity.*, EntityProperties.*, EntityProtos.*, Properties.*, ProtoManager.*.
• Карты и движение: MapLoader.*, Geometry.*, Movement.*, PathFinding.*, LineTracer.*.
• Сетевые примитивы: NetBuffer.*, NetworkUdp.* и общий для сервера/клиента разбор списка файлов updater в UpdateDescriptor.*.
• Конфигурация и данные: ConfigFile.*, DataSource.*, ResourcePack.*, ResourceIndex.*, FileSystem.*, CacheStorage.*.
• Общие presentation metadata и resources: AnimationInfo.*, ModelBounds.*, ResourceDefaults.*, SpriteResource.*.
• Script bridge: ScriptSystem.*.

Если изменение переиспользуемо и общее для client и server, оно, вероятно, начинается здесь.

Source/Client/

Client-side runtime и presentation-facing state. Он включает client startup/composition, connection handling, resource management, views для critters/items/maps/locations/player state, sprite/model/effect/font managers, render targets и варианты network-client transport. Polygonal sprite submission принадлежит DefaultSprites.*; автоматическая проекция model frame/view изолирована в ModelSpriteLayout.*. Parsing font descriptors, slot binding, measurement, wrapping и glyph drawing проходят через FontManager.* и Font Format.

Чистая математика накопления дельт, проекции цикла, переноса фазы, выбора кадра и визуальной компенсации находится в AnimationMovement.*; CritterHexView.* владеет выбранным листом, контекстом движения и жизненным циклом привязки.

Не помещайте authoritative решения game state в client без документированного server contract и validation.

Source/Server/

Authoritative runtime. Он включает server startup/composition, players, critters, items, maps, locations, entity managers, data validation, database backends, варианты network-server transport, server connections и поддержку updater backend.

Вопросы persistence, validation и authoritative entity lifecycle обычно начинаются с server behavior.

Source/Scripting/

Script integration и регистрация видимых скриптам native methods. AngelScript/ и Managed/ являются реализованными backend; Managed/ также владеет C# CoreScripts, analyzers, runtime hosting и backend tests. Native/ в текущем дереве только зарезервированный source-root placeholder, а устаревшего прототипа Mono/ больше нет. Файлы регистрации methods сгруппированы по runtime side и entity type: common/client/server global methods и critter/item/map/player methods. Начинайте с Scripting и переходите к Скриптам Managed C# или Стилю AngelScript и рефакторингу для выбранного backend.

При изменении nullable script/native signatures используйте Nullability.

Source/Tools/

Developer и build-time tools. Текущие tool files включают baker classes, config/effect/image/map/model/proto/text bakers, Mapper, AnimationViewer, ParticleViewer и размещённый в Mapper SPARK particle editor. В текущем дереве нет generic Editor или реализации AssetExplorer.

Cross-baker reporting принадлежит BakingReport.*. Polygonal 2D geometry изолирована в SpriteMeshing.*, а model animation bounds вычисляются ModelBoundsCalculator.*; их container integration остаётся в соответствующих image/model bakers.

Документация build/resource pipeline должна ссылаться на эти файлы и вызывающий их CMake stage, а не делать выводы из имён приложений. Particle authoring имеет отдельный ParticleBaker: работу с .spark/.spk, .efkproj/.efk, backend options, SPARK registry/editor, Effekseer compilation, measured bounds, runtime framing и client integration направляйте в Particle Format. Сфокусированная проверка critter animation и baked particles проходит через просмотр анимации и частиц. У font descriptors также нет отдельного baker: raw-copy settings направляйте через RawCopyBaker, ссылочные textures через ImageBaker, а parsing .fofnt/.fnt и text layout через Font Format.

Source/Frontend/

Абстракция application и rendering. Содержит варианты Application*.cpp и rendering backends, включая Direct3D, OpenGL, null rendering и общие rendering interfaces.

Этот слой относится к запуску native client, headless modes, testing, Web и Android platform notes.

Source/Tests/

Тесты являются исполняемой базой знаний для многих подсистем движка. Имена файлов сгруппированы по подсистеме (Test_Geometry.cpp, Test_NetBuffer.cpp, Test_DataBase.cpp, Test_AngelScript*.cpp, Test_ManagedScriptBaker.cpp и т. д.). При добавлении новых категорий расширяйте Source/Tests README и сверяйте Testing с текущим runner и generated targets.

Антипаттерны навигации

• Не выводите target names из одного встраивающего проекта и не документируйте их как универсальные имена движка.
• Не помещайте game-specific behavior в документацию движка, если оно явно не помечено как пример.
• Не описывайте generated output как hand-authored source.
• Не превращайте source-tree README в большие руководства; используйте тематические страницы Docs/ и ссылки на них.

Соседние опциональные модули

Common/DataSource-*, Server/DataBase-*, Tools/ImageBaker-* и Tools/AudioBaker-* — соседние .h/.cpp под внутренними числовыми guards, с безусловной регистрацией/includes. Координаторы сохраняют dispatch; ImageImport владеет frames/context, DataBaseSerialization — JSON/CBOR, Mongo — BSON. Выбор компонентов перечисляет модули, роли и зависимости.