Engine Architecture

This document gives a source-grounded map of the FOnline engine layers. Use it when deciding where a behavior belongs before opening subsystem-specific docs.

Big picture

FOnline is organized around a reusable engine embedded by a game project. The game project owns content, scripts, product configuration, and release policy; the engine owns reusable runtime systems, tools, generated API infrastructure, platform frontends, and build composition.

The main layers are:

• Applications — executable and library entry points in Source/Applications/.
• Essentials — low-level platform, memory, filesystem, logging, serialization, sockets, and utilities in Source/Essentials/.
• Common runtime — shared engine model in Source/Common/: entities, properties, prototypes, maps, networking primitives, config, scripts, and engine base services.
• Client runtime — presentation/resource/network-client side in Source/Client/.
• Server runtime — authoritative world, managers, database backends, network-server side, and updater backend in Source/Server/.
• Frontend — application/window/rendering abstraction in Source/Frontend/.
• Scripting — AngelScript, Native, Mono, and script method registration in Source/Scripting/.
• Tools — baker, mapper, editors, asset processors, and related developer tooling in Source/Tools/.
• BuildTools — CMake stages, helpers, toolchains, platform project generation, package layout, and validation support in BuildTools/.

Application layer

Source/Applications/ is the practical entry-point directory. It contains app wrappers such as:

• ClientApp.cpp and ClientLib.cpp for client host/runtime flows.
• ServerApp.cpp, ServerDaemonApp.cpp, ServerHeadlessApp.cpp, and ServerServiceApp.cpp for server variants.
• MapperApp.cpp and EditorApp.cpp for developer-facing tools.
• BakerApp.cpp and ASCompilerApp.cpp for generation/build support.
• TestingApp.cpp for test execution.

BuildTools/cmake/stages/Applications.cmake wires these files into project-specific targets based on build options such as client/server/tool/platform/library modes. Avoid hard-coding target names in engine docs: target names are often derived from the embedding project’s FO_DEV_NAME and presets.

See Applications.md for the application map.

Source paths inspected

• Source/Applications/
• Source/Common/EngineBase.h
• Source/Common/EngineBase.cpp
• Source/Common/Entity.h
• Source/Common/Entity.cpp
• Source/Common/ScriptSystem.h
• Source/Common/ScriptSystem.cpp
• Source/Client/Client.h
• Source/Server/Server.h
• Source/Frontend/Application.h
• Source/Frontend/ApplicationInit.cpp
• BuildTools/cmake/stages/Applications.cmake

Common runtime layer

Source/Common/ holds shared concepts used by client, server, tools, and scripts. Important entry points include:

• EngineBase.h / EngineBase.cpp — base engine services and shared runtime state.
• Entity.h / Entity.cpp — exported entity concepts shared across runtime sides.
• Properties.h, EntityProperties.h, EntityProtos.h, ProtoManager.h — property/prototype model.
• ScriptSystem.h / ScriptSystem.cpp — script engine abstraction used by runtime sides and tools.
• Geometry.h, Movement.h, PathFinding.h, MapLoader.h — reusable map and movement primitives.
• NetBuffer.h, NetCommand.h, NetworkUdp.h — common networking primitives.
• ConfigFile.h, DataSource.h, FileSystem.h, CacheStorage.h — config and data access support.

This layer should stay reusable. Game rules should generally be expressed through content/scripts or project-native extensions, not by embedding one project’s policy into common engine code.

Client and server layers

Source/Client/Client.h includes the client-side composition points: application integration, resource/cache access, views for critters/items/locations/maps, effects, rendering-facing structures, and client connection code.

Source/Server/Server.h includes authoritative runtime pieces: entities, managers, database, geometry, scripting-facing server objects, client validation, networking, and updater backend support.

Treat client and server docs as separate because their ownership differs:

• The client presents local views, resources, UI-facing objects, and network-client behavior.
• The server owns authoritative world state, persistence, entity managers, validation, and network-server behavior.

Frontend layer

Source/Frontend/Application.h and the related Application*.cpp / Rendering*.cpp files abstract platform app startup and rendering backends. This layer is where headless/stub/native frontend differences belong, not in game docs.

Platform workflow docs:

• WebDebugging.md
• AndroidDebugging.md
• Debugging.md

Scripting layer

Source/Common/ScriptSystem.* defines the common script-system abstraction. Source/Scripting/ provides runtime-specific method registration and integration folders:

• Source/Scripting/AngelScript/
• Source/Scripting/Native/
• Source/Scripting/Mono/
• Source/Scripting/*ScriptMethods.cpp

The engine owns the reusable script/native bridge. A game project owns concrete game script modules and gameplay logic.

Build and generation layer

BuildTools/cmake/stages/ is the staged CMake pipeline. Current stage files include:

• Init.cmake
• ProjectOptions.cmake
• CoreLibs.cmake
• ThirdParty.cmake
• EngineSources.cmake
• Codegen.cmake
• Applications.cmake
• ScriptsAndBaking.cmake
• Packages.cmake
• Finalize.cmake

These stages compose engine code with embedding-project configuration. Read BuildWorkflow.md before changing build behavior.

Typical runtime flow

A normal embedding-project workflow looks like this:

1. The game repository configures CMake from the project root.
2. BuildTools loads project options and engine sources.
3. Codegen and baking steps prepare generated API/resources/scripts.
4. Applications are built from Source/Applications/ entry points.
5. Runtime starts through the selected app: client, server, mapper, baker, test app, or platform package.
6. Client/server/tools use common runtime services and call into game-owned scripts/content where appropriate.

Where to document changes

• Architecture-wide behavior: this file.
• Source navigation: SourceTree.md.
• App entry points: Applications.md.
• Build workflow: BuildWorkflow.md and BuildToolsPipeline.md.
• Script/native boundary: Nullability.md and Scripting.md.
• Platform debugging: WebDebugging.md, AndroidDebugging.md, Debugging.md.