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

Это руководство объясняет, откуда начинать навигацию по 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.

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.*, 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.

Не помещайте 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/ и ссылки на них.