Source Tree Guide

This guide explains where to start when navigating Source/. It complements the shorter Source README.

Quick routing

• Changing executable startup or target entry points: Source/Applications/ and Applications.
• Changing low-level platform/utilities: Source/Essentials/.
• Changing shared entity/property/map/config/network primitives: Source/Common/.
• Changing client-side runtime or views: Source/Client/.
• Changing authoritative world/server behavior: Source/Server/.
• Changing scripting integration or script-visible native methods: Source/Scripting/.
• Changing developer tools, baking, mapper, or editors: Source/Tools/.
• Changing application/window/rendering abstraction: Source/Frontend/.
• Looking for behavior examples or regression coverage: Source/Tests/.

Route to the owning directory first. Before naming a concrete file, helper, or target, verify its exact spelling in the current source inventory; adjacent backend names and project-generated executable names are not safe templates.

For developer tools, distinguish a baker implementation in Source/Tools/ from its build orchestration. Missing generated files and codegen dependency repair belong to BuildTools/cmake/stages/Codegen.cmake and BuildTools/cmake/helpers/EnsureCodegenOutputs.cmake.in, not the baker or Mapper runtime. Follow the BuildTools pipeline for that boundary; change the native tool owner when its baked behavior changes.

Source/Applications/

Contains app and library entry points. Examples include client, server variants, mapper, editor, baker, AngelScript compiler, Managed script baker, and testing app wrappers. Build target wiring is in BuildTools/cmake/stages/Applications.cmake.

See Applications.

Source/Essentials/

Low-level reusable primitives. Current files include logging, core helpers, compression, containers, serialization, filesystem, exception handling, memory system, sockets, platform helpers, stack traces, string utilities, strong types, time helpers, and worker threads.

This layer should not grow game-specific rules. It should remain usable by every runtime side.

Source/Common/

Shared runtime code used by client/server/tools/scripts. Key areas include:

• Engine base and shared setup: EngineBase.*, Common.*.
• Entities/properties/prototypes: Entity.*, EntityProperties.*, EntityProtos.*, Properties.*, ProtoManager.*.
• Maps and movement: MapLoader.*, Geometry.*, Movement.*, PathFinding.*, LineTracer.*.
• Networking primitives: NetBuffer.*, NetworkUdp.*, and the shared updater file-list parser UpdateDescriptor.*.
• Config/data access: ConfigFile.*, DataSource.*, ResourcePack.*, ResourceIndex.*, FileSystem.*, CacheStorage.*.
• Shared presentation metadata and resources: AnimationInfo.*, ModelBounds.*, SpriteResource.*.
• Script bridge: ScriptSystem.*.

If a change is reusable and shared by both client and server, it likely starts here.

Source/Client/

Client-side runtime and presentation-facing state. It includes client startup/composition, connection handling, resource management, views for critters/items/maps/locations/player state, sprite/model/effect/font managers, render targets, and network-client transport variants. Polygonal sprite submission is owned by DefaultSprites.*; automatic model frame/view projection is isolated in ModelSpriteLayout.*. Font descriptor parsing, slot binding, measurement, wrapping, and glyph drawing are routed through FontManager.* and Font Format.

Keep authoritative game-state decisions out of the client unless the server contract and validation are documented.

Source/Server/

Authoritative runtime. It includes server startup/composition, players, critters, items, maps, locations, entity managers, data validation, database backends, network-server transport variants, server connections, and updater backend support.

Server behavior is usually where persistence, validation, and authoritative entity lifecycle questions start.

Source/Scripting/

Script integration and script-visible native method registration. AngelScript/ and Managed/ are implemented backends; Managed/ also owns C# CoreScripts, analyzers, runtime hosting, and backend tests. Native/ is only a reserved source-root placeholder in the current tree, and the obsolete Mono/ prototype no longer exists. Registration files are grouped by runtime side and entity type, such as common/client/server global methods and critter/item/map/player methods. Start with Scripting and use Managed C# Scripting or AngelScript Style and Refactoring for the selected backend.

Use Nullability when changing nullable script/native signatures.

Source/Tools/

Developer and build-time tools. Current tool files include baker classes, config/effect/image/map/model/proto/text bakers, Mapper, AnimationViewer, ParticleViewer, and the Mapper-hosted SPARK particle editor. The current tree has no generic Editor or AssetExplorer implementation.

Cross-baker reporting is owned by BakingReport.*. Polygonal 2D geometry is isolated in SpriteMeshing.*, while model animation bounds are calculated by ModelBoundsCalculator.*; their container integration remains in the owning image/model bakers.

Build/resource pipeline docs should cite these files and the CMake stage that invokes them rather than guessing from app names. Particle authoring has a dedicated ParticleBaker: route .spark/.spk, .efkproj/.efk, backend options, SPARK registry/editor, Effekseer compilation, measured bounds, runtime framing, and client integration work through Particle Format. Focused critter-animation and baked-particle inspection routes through Viewer Tools. Font descriptors likewise have no dedicated baker: route raw-copy settings through RawCopyBaker, referenced textures through ImageBaker, and .fofnt/.fnt parsing plus text layout through Font Format.

Source/Frontend/

Application and rendering abstraction. It contains Application*.cpp variants and rendering backends such as Direct3D, OpenGL, null rendering, and shared rendering interfaces.

This layer is relevant for native client startup, headless modes, testing, Web, and Android platform notes.

Source/Tests/

The tests are the executable knowledge base for many engine subsystems. File names are grouped by subsystem (Test_Geometry.cpp, Test_NetBuffer.cpp, Test_DataBase.cpp, Test_AngelScript*.cpp, Test_ManagedScriptBaker.cpp, etc.). Expand the Source/Tests README when adding new test categories, and reconcile Testing against the current runner and generated targets.

Navigation anti-patterns

• Do not infer target names from one embedding project and document them as universal engine names.
• Do not put game-specific behavior into engine docs unless clearly labelled as an example.
• Do not document generated output as hand-authored source.
• Do not change source-tree READMEs into large manuals; use focused Docs/ pages and link to them.