FOnline Engine

FOnline is an open-source (MIT) C++20 engine for building online multiplayer RPGs in the classic isometric style of Fallout 1/2/Tactics and Arcanum. One codebase gives you the authoritative server, the game client, the map editor, the content pipeline, and packaging for desktop, mobile, and the browser — you bring the game: content, scripts, and rules live in your own repository that embeds the engine.

In continuous development since 2006, the engine powers community multiplayer RPGs; a current example is Last Frontier, a post-apocalyptic MMO built on it.

Why FOnline?

• Multiplayer first. Not a single-player engine with networking bolted on: an authoritative server, replicated entity state, and client/server separation are the core design, all the way down to the entity model.
• Complete vertical. Server, client, mapper, editor, resource baker, script compiler, test runner, auto-updater — all built from the same sources by one CMake pipeline.
• Engine/game split that stays clean. The engine is a reusable submodule; your game owns content, scripts, configuration, branding, and release policy. Engine updates don’t drag game policy with them.
• Data-driven content. Prototypes, maps, dialogs, localization, and GUI are authored as plain-text assets and baked into runtime packs — friendly to diffs, reviews, and tooling.
• Runs where players are. Native Windows/Linux/macOS, Android and iOS, and a WebAssembly client that plays in the browser over WebSockets.

Feature highlights

Multiplayer core

• Authoritative server runtime with entity managers, client validation, and hardened parsing of untrusted client input.
• Shared entity/property/prototype model with generated type-safe property wrappers and automatic property replication to clients.
• Pluggable network transports: TCP sockets (including an Asio-based server), WebSockets for browser play, an ordered-UDP channel, and an in-process transport for tests and embedded clients.
• Pluggable persistence backends — JSON files, SQLite, MongoDB, or in-memory — behind one database facade with an async commit queue and recovery logs.
• Built-in client auto-updater: a thin client host plus a replaceable runtime, resumable file transfer, and a server-side update backend.

Scripting

• AngelScript and Managed C# gameplay scripting over a backend-neutral script system; Native scripting remains a reserved placeholder.
• The native API is exported to scripts by code generation from ///@ annotations — methods, properties, events, remote calls, and enums stay in sync with the C++ source automatically.
• Nullability is enforced across the script/native boundary: script T? maps to native ptr<T>/nptr<T> contracts, checked by analyzers and runtime asserts.
• Script debugging support alongside native debugging.

Rendering and presentation

• Renderer backends: OpenGL, Direct3D, Vulkan, and SDL_GPU, plus headless/null modes for servers and CI.
• Effects are written once in GLSL and compiled through glslang to SPIR-V, then translated to each backend via SPIRV-Cross.
• Sprite-based isometric worlds with 3D character models (FBX), particle effects, video playback, and audio in both modern (Ogg/Vorbis) and classic Fallout formats.
• Windowed, borderless-fullscreen, and multi-client virtual-window modes with a consistent resolution/letterbox model; ImGui-powered developer overlay.

World and maps

• Hexagonal and square grid geometry modes with shared helpers for distance, direction, and neighborhoods.
• Path finding, line tracing, movement contexts, and a blocking model designed for multiplayer server authority.

Content pipeline and tools

• A baking pipeline turns authored sources — prototypes, maps, dialogs, localized texts, effects, images, models, scripts — into versioned runtime resource packs.
• Imports classic 2D asset formats (Fallout FRM, Arcanum ART, and other legacy formats) alongside PNG/TGA.
• Interactive tools built on the engine itself: Mapper with map/content windows and SPARK editing, plus focused animation and baked-particle viewers.

Engineering quality

• Unit tests (Catch2) with generated per-suite targets, sanitizer runs, and code coverage.
• Clang Thread Safety Analysis enforced as -Werror on every Clang toolchain; strict smart-pointer and nullability vocabularies audited across the codebase.
• Always-on stack traces, deterministic exception-safety rules, and a terminate-on-OOM allocation model instead of half-mutated states.
• Tracy profiler integration for client and server captures.

Architecture at a glance

Your game repository                      FOnline engine (this repo, embedded as Engine/)
────────────────────                      ────────────────────────────────────────────────
content: protos, maps,            ┌──►    Applications — client/server/tool entry points
dialogs, texts, GUI               │       Client & Server runtimes — views vs. authority
AngelScript / C# game logic embeds │      Common model — entities, properties, protos,
.fomain configuration      ───────┤                      maps, networking, config
native extensions                 │       Frontend — windows, input, audio, renderers
CMake presets, CI,                │       Scripting — AngelScript + Managed C# bridges + generated API
release policy                    └──►    Tools & BuildTools — bakers, mapper, editor,
                                                     CMake stages, codegen, packaging

The engine owns reusable technology; the game owns the product. A game repository adds the engine as an Engine/ submodule, points the engine’s staged CMake pipeline at its own configuration, and gets project-named build targets for every application. The full layer map is in Engine Architecture, and the embedding contract in Embedding FOnline in a Game Project:

GameProject/
├── Engine/                 # this repository as a git submodule
├── CMakeLists.txt          # project entry point that includes engine build logic
├── CMakePresets.json       # project presets and platform variants
├── GameName.fomain         # master project configuration
├── Scripts/                # game AngelScript or Managed C# modules
├── SourceExt/              # optional project-native C++ extensions
├── Critters/ Items/ Maps/  # game content and prototypes
└── Dialogs/ Texts/         # dialogs and localization

Getting started

• Run the first engine-owned project: First FOnline Headless Project - configure, build, bake, start, verify, and stop the minimal headless server.
• Inspect the canonical scaffold: Examples/MinimalProject/README.md - the complete project and CI smoke contract.
• Inspect the executable content gallery: Examples/ContentShowcase/README.md - source assets, baking, native/Web checks, provenance, budgets, and reproducible capture evidence.
• Build the first playable slice: first playable client, first content change, and first automated test - connect a client, change localized content, and extend executable checks.
• Configure and maintain a project: Project Configuration, Generated Content Workflow, and Engine Upgrade Guide - own .fomain, resource packs, generated outputs, migrations, and Engine updates.
• Choose release targets truthfully: Support Matrix and its generated matrix - distinguish source capability, required builds, process smoke tests, and project/device qualification.
• Plan and validate public examples: Public Example Repositories and its generated registry - ownership, exact Engine pins, compatibility lanes, repository template, support, and asset provenance.
• Browse the generated native API: Docs/en/reference/script-api/index.md - methods, properties, events, types, settings, migrations, and source links.
• Author prototypes: Prototype Format and its generated reference - exact syntax, inheritance, built-in properties, references, migrations, and validation.
• Author maps: Docs/en/how-to/content/map-format.md and its generated reference - .fomap sections, placement IDs, ownership, mapper normalization, side-specific baking, and runtime loading.
• Author localized text: Text and Localization and its generated reference - .fotxt syntax, language normalization, prototype $Text, runtime lookup, color tags, and the game-formatting boundary.
• Author images and sprite sheets: Image and sprite formats and the generated reference - PNG/TGA and legacy import, FOFRM composition, baking, runtime factories, atlases, caches, and validation.
• Author shader effects: Effect Format and its generated reference - .fofx sections, passes, render state, shader resources, backend outputs, runtime selection, and script values.
• Author particles: Particle Format And Runtime and its generated reference - optional SPARK/Effekseer selection, .spark/.efkproj authoring, .spk/.efk baking, Mapper tools, runtime routes, and model/script integration.
• Author bitmap fonts and lay out text: font formats and text layout and its generated reference - FOFNT/BMFont descriptors, slot binding, scaling, measurement, wrapping, rendering flags, colors, and validation.
• Inspect project integration contracts: CMake reference, BuildTools CLI reference, helper CLI reference, native-extension reference, package reference, and public-example registry - exact CMake, main/helper BuildTools, native-extension, packaging, and example-program surfaces.
• Add project-native C++ safely: Native Extensions - source roles, hooks, script exports, state ownership, compatibility, and executable validation.
• Browse the generated CMake interface: Docs/en/reference/cmake/index.md - project options, strict stages and hooks, selected helpers, defaults, and source links.
• Measure client and server performance: Profiling - Tracy build modes, isolated capture boundaries, reproducible workloads, and comparable result analysis.
• Publishing documentation: documentation site publication - generated navigation/search/route data, rolling version and locale policy, local Jekyll preview, rendered-route/accessibility validation, CI artifacts, and the existing fonline.ru GitHub Pages route.
• AI and offline documentation: llms.txt, llms-full.txt, and docs-manifest.json - generated routes, bounded context, canonical/source URLs, provenance, and content hashes from the same Markdown manifest.
• New to the engine: Getting Started - the first route: what to read, what to build, what belongs where.
• Starting or inspecting a game project: Embedding Project — expected repository shape and ownership rules.
• Building: Build Workflow — prerequisites, presets, and validation strategy. Builds are normally driven from the embedding game repository, not from the engine checkout.
• AI-maintainer instructions: AGENTS.md — read before changing engine code or docs.

FOnline has build profiles for Windows, Linux, macOS, Android, iOS, and WebAssembly, but support is evidence-scoped. Consult the support matrix; a cross-build or headless smoke does not qualify a renderer, device, package, service, or store route.

Repository layout

• Source/ — engine source: Applications/ entry points, Client/ and Server/ runtimes, Common/ shared model, Frontend/ platform/render layer, Scripting/ bridge, Tools/ bakers and editors, Essentials/ low-level core, Tests/ unit tests.
• BuildTools/ — staged CMake pipeline, code generation, platform toolchains, workspace and package preparation.
• Resources/ — engine-owned runtime and build resources.
• ThirdParty/ — vendored dependencies (SDL, AngelScript, Asio, ImGui, glslang, SPIRV-Cross, Tracy, and more); maintenance workflow in ThirdParty Maintenance.
• Docs/ — maintained engine documentation.

Documentation

The maintained index is Docs/en/index.md; the Russian mirror is Docs/ru/index.md. Deep dives by theme:

When behavior changes in a noticeable way, the owning document is updated in the same change — the docs are maintained as a source-grounded reference, not an afterthought.

Project and community

• Site: https://fonline.ru
• GitHub: https://github.com/cvet/fonline
• License: MIT