FOnline Engine — AI Maintainer Guide

This is the AI entry point for the reusable FOnline engine repository. For the human entry point, start with README.md. For the documentation map, start with Docs/README.md.

Scope

• This repository is the reusable engine submodule used by games such as Last Frontier.
• Engine-owned code lives under Source/, BuildTools/, Resources/, and engine tests under Source/Tests/.
• Game-specific content, scripts, native extensions, CI glue, and launch presets live in the embedding project and should not be moved into the engine unless the behavior is genuinely reusable.

Before Changing Anything

1. Check whether the change belongs to the engine or to the embedding game project.
2. Read the nearest existing code and follow its style; do not introduce parallel conventions.
3. Verify before editing: docs may drift, and when a doc and the live source disagree, the source wins — fix the doc in the same change.
4. If behavior changes, update the owning engine doc in Docs/ in the same worktree change.
5. Do not commit or push unless explicitly asked by the repository owner.
6. Treat published branch history as immutable. Once the branch has a remote tip, do not rebase, reset, amend, or force-push it; merge upstream and the published tip so every publication is a fast-forward. Verify with git merge-base --is-ancestor <remote-tip> HEAD before pushing, and stop instead of rewriting history when that check fails.

Documentation Map

The full maintained index is Docs/README.md; use it when a topic is not listed here. Convention-critical docs for maintainers:

• Docs/Architecture.md - engine layer map and where a behavior belongs.
• Docs/SourceTree.md - source-tree navigation.
• Docs/Essentials.md - low-level platform, logging, memory, filesystem, serialization, sockets, and utilities.
• Docs/ConfigurationAndDataSources.md - config parsing, settings, data sources, file lookup, and caches.
• Docs/Testing.md - test-suite inventory, generated test targets, coverage, and validation routing.
• Docs/DocumentationMaintenance.md - source-grounded docs maintenance workflow.
• Docs/ThirdPartyMaintenance.md - vendored dependency update, pruning, version pin, and (FOnline Patch) workflow.
• Docs/ClientUpdater.md - client host/runtime split, ABI, updater protocol, and UpdaterBackend.
• Docs/Debugging.md - stack traces, debugger helpers, native debugging, and validation notes.
• Docs/Nullability.md - T? script / ptr<T>·nptr<T> native boundary contract.
• Docs/SmartPointers.md - native smart-pointer vocabulary (ptr<T>/nptr<T> borrows, unique_*/refcount_* owners, engine-own shared_ptr/weak_ptr), raw-pointer allowlist, and audit expectations.
• Docs/ExceptionSafety.md - engine-invariant stability under exceptions: terminate-on-OOM allocation model, entity-lifecycle throw-as-signal contract, and the FO_STRONG_ASSERT disposition rules.
• Docs/ThreadSafetyAnalysis.md - FO_TSA_* Clang Thread Safety Analysis annotations, locking primitives, and -Werror=thread-safety enforcement.
• Docs/MapperTools.md - mapper automation and native mapper helper integration points.
• Docs/WebDebugging.md - web target build/debug workflow.
• Docs/AndroidDebugging.md - Android target build/debug workflow.
• PUBLIC_API.md - public API notes.
• TUTORIAL.md - engine tutorial.
• Source/README.md - source-tree overview.
• Source/Tests/README.md - engine unit-test suites.
• BuildTools/README.md - build-tooling notes.

Validation Routing

• Zero tolerance for warnings. Engine C++ builds and codegen must finish clean; there is no acceptable warning backlog (Clang thread-safety analysis already runs as -Werror=thread-safety). Never introduce a new warning; if a change surfaces one, resolve it at the root in the same change rather than suppressing it.
• Engine C++ changes: build and run the engine unit-test target used by the embedding project (LF_UnitTests / RunUnitTests in Last Frontier).
• Build-system changes: validate the affected CMake preset or BuildTools command in the embedding project that exercises it.
• Platform-packaging changes: validate the relevant package path (Raw, Raw+WebServer, Android package, etc.) and update the platform doc.
• Script/native API boundary changes: update nullability/API docs and run the smallest test target that covers the changed binding.
• When a serialized contract changes (entity properties, network messages, save data), update the relevant ///@ MigrationRule metadata.

• Engine changes that affect network interaction or are otherwise substantial enough to matter for client/server runtime compatibility must force a compatibility-version change by bumping the central marker in Source/Common/Common.h:

  // Force change of compatability version
  ///@ MigrationRule Version 0 0 5
  

Behavioral Rules

• Script callers own the complete native entity cover. Before an ordinary server FO_SCRIPT_API call, AngelScript must acquire every existing entity the native call graph can read or mutate, including transitive map/location, holder, controlled-critter, and group dependencies. A native path reachable from that call may validate the prepared package with ValidateEntityAccess() and may call EnsureEntitySynced() freely and repeatedly to retain the own lock of an entity already covered by the current context. Both operations are idempotent no-ops once their condition is satisfied, so loops, repeated same-target calls, catch handlers, and recursion carry no call-count restriction. Each actual EnsureEntitySynced() acquisition never releases/reacquires the caller cover and never parks on a lock: it only ADDS the target’s own lock plus the intermediate ancestor marks, as one all-or-nothing state-mutex transaction. Because the covering ancestor is held exclusively, any block it meets is a foreign thread mid-flight through its own non-blocking pass (releasing marks by lock address rather than hierarchy, or rolling back an ascending-address try-prefix), which clears in microseconds — so the acquisition is MANDATORY and retries the whole batch with bounded back-off until it lands, retaining nothing across the back-off. It throws only when the target is not actually covered or the covered-cover invariant is corrupt, never for ordinary transient contention, and a failure leaves the caller cover intact. It cannot repair an omitted unrelated existing dependency. Fresh parentless entities are captured only by the private trusted registration boundary before publication; that boundary never authorizes discovery or acquisition of pre-existing dependencies. Native code must not call SyncEntity() / SyncEntities() or otherwise obtain missing existing cover on the script’s behalf. The explicit synchronization primitives Game.Sync, Game.SyncRelease, Game.Lock, and Game.Unlock are the exceptions because changing synchronization state is their script-visible purpose.
• Fix the source, never mask. When a lower layer returns a wrong result, swallows an error, or silently coerces bad input into “looks fine”, fix it at the source (throw / validate / propagate) instead of papering over it from the caller with pre-checks, try/catch that fabricates a “good” value, default substitutes, or other workarounds. If you find yourself adding a guard that compensates for a bug elsewhere, stop and fix the bug instead.
• No legacy compatibility in the reusable engine. When an engine API, configuration key, data format, or internal contract is replaced, remove the old surface completely. Do not retain deprecated aliases, fallback parsing, detection of removed keys, migration shims, compatibility branches, tests, or documentation for the removed contract. Compatibility-version markers may reject incompatible builds or data, but must not implement the old behavior. Migration of database-persisted game data belongs to the embedding project and must not leak into Engine.
• Keep engine invariants stable under exceptions. An exception thrown partway through a multi-step engine mutation (entity create/register/destroy/invalidate, cross-entity links) must never leave a half-mutated, restart-only state. Engine allocation terminates on OOM (SafeAlloc/SafeAllocator), so bad_alloc is not a recoverable error and never a reason to build a rollback. A post-mutation invariant that “can only be false if the world is already corrupt” is a FO_STRONG_ASSERT (always-on, deterministic exit), not a swallowable FO_VERIFY_AND_THROW. Entity create/destroy is throw-as-signal, not transactional rollback (events may legitimately destroy or relocate the entity; the function throws but the entity is left in a valid state) — pinned by Source/Tests/Test_EntityLifecycle.cpp and Test_ServerMapOperations.cpp, so do not add a blanket create-time rollback. Full rules: Docs/ExceptionSafety.md.
• No singletons. No hidden global / static state for engine-semantic data. State with per-engine semantics (lock sets, entity registries, ticket allocators tied to one engine’s wait queues, mutable runtime caches that could be mixed across engines) lives on an owning instance reachable through the engine object graph — typically ServerEngine (managers), ServerEntity (per-entity locks, properties, parent), or BaseEngine (ScriptSystem, settings). Do not introduce file-scope mutable statics, static data members on engine classes, function-local statics that cache cross-call state, or unnamed-namespace mutable variables. Multiple engine instances may coexist in one process (embedding projects run parallel test suites this way), so hidden globals silently share state across engines, hide cross-test pollution, and turn lifetime-ordering bugs into timing windows.
• static thread_local is OK only when threads are partitioned by engine ownership and the slot can never observe values from a foreign engine on the same thread. The current example is SyncContext* CurrentContext in Source/Server/EntitySync.cpp: every thread that touches it belongs to exactly one engine, so the thread-local slot is implicitly per-engine. The same logic permits a static std::atomic whose value has no per-engine semantics (e.g. a monotonic ticket counter only ever compared inside one lock’s wait queue). When in doubt, prefer instance ownership — but do not pay a mutex-plus-map lookup just to satisfy the rule when a thread_local T* is already correctly isolated.
• static is otherwise acceptable only for compile-time constants (static constexpr), file-local pure helper functions (static void Helper(...)), and static_assert. An existing static that holds per-engine state is a bug to migrate to instance ownership, not a precedent to copy.

Style Notes

• Prefer existing engine idioms over new local abstractions.
• Use struct only for passive data aggregates: no user-defined constructors, methods, or hidden invariants. When behavior or construction logic belongs on the type, make it a class and apply full encapsulation with private state and a deliberate public interface. Do not mark such structs final — a plain data aggregate needs no inheritance guard, the keyword only complicates it.
• The code is the documentation; a comment carries only what the code cannot. Names, types, and structure already state what happens, so a comment that re-tells them is deleted, not shortened — and the default state of a line of engine code is no comment. Write one only for what the reader cannot see: why the code sits here rather than elsewhere, why this approach instead of the obvious alternative, the gist of a genuinely dense block, or a contract that is not derivable from the code (sentinel meanings and units, threshold calibration, concurrency/ownership/lifetime requirements, edge-case exemptions, why a plausible alternative is unsafe). One line is the default and two is the ceiling — no multi-line essays. When the explanation genuinely needs more room, it belongs in the owning Docs/ page with a short link from the code; never link a temporary plan. Do not narrate the next statement, restate a signature or parameter list, enumerate steps the code already spells out, or record history, fixed-bug stories, or benchmark numbers (those belong in commit messages and docs). A comment points at code, never at bookkeeping: no task, ticket, issue, or PR numbers, no dates or “as of” wording, no version or release markers, no author names — that metadata lives in the commit and the tracker, and in code it only rots. Refer to a symbol, a function, a file, or the test that pins the behavior; the sole non-code target is the owning Docs/ page named above. Short structural headings are allowed when they materially improve navigation in long flat code. Only the concluding sentence of a comment drops its period (the single line of a one-line comment, the final line of a two-line block, or a trailing comment); every preceding sentence keeps its period. Capitalize prose, not symbols (a leading lowercase code identifier stays as written). Fixed-text banners such as the license header, and commented-out code, are exempt.
• Reuse the existing MIT source-file header and #pragma once; match the surrounding module-level layout.
• Module layout: put class definitions and static-function forward declarations near the top of the translation unit, then implementations ordered from high-level entry points down to low-level helpers, so a reader meets the public/orchestrating code first.
• Every standalone native module must be created as a complete .h + .cpp pair and both files must be registered in the owning build source list. A named subsystem/module must never be introduced as a lone header; keep the translation unit as the module anchor even when all current declarations are passive data and no out-of-line implementation is needed yet. Pure template/constexpr/umbrella headers are not standalone modules.
• Order code top-down by importance and abstraction level: high-level entry points and orchestration first, secondary helpers and low-level details below, unless a nearby file has a stronger established ordering.
• First statement of every .cpp method/function body: FO_STACK_TRACE_ENTRY() or FO_NO_STACK_TRACE_ENTRY(). If the body continues after the marker, keep one blank line after it. Do not put either macro in headers, inline header-defined bodies, or lambda bodies. Exception: FO_SCRIPT_API script-export functions (///@ ExportMethod, ///@ EngineHook, and the other script-bound exports) take no stack-trace marker at all — the body starts directly after the opening brace.
• Separate semantically distinct code blocks with a blank line. In particular, surround every control-flow statement (if/else, for, while/do, switch, try/catch, and similar constructs) with a blank line before and after the complete statement. Blank lines may be omitted only inside a consecutive run of the same construct (if + if, for + for, and so on).
• Treat preprocessor directives as transparent to the blank-line rule: do not add or remove blank lines merely because code is enclosed by #if/#else/#endif; apply spacing to the surrounding C++ blocks as if the directives were not there.
• Keep a comment attached to the code block it describes below: put a blank line before the comment, but no blank line between the comment and that block. For control-flow spacing, the comment is part of the following block.
• Prefer FO_VERIFY_AND_THROW over silently masking unexpected states.
• Throw engine exceptions with a fixed message plus context arguments, never a pre-formatted string. FO_DECLARE_EXCEPTION exception types and FO_VERIFY_AND_THROW take a constant string_view message followed by variadic context values; the base exception preserves the bare message and appends each value as its own - value line. Write throw SomeException("Fixed human-readable message", id, path, value); and FO_VERIFY_AND_THROW(cond, "Fixed message", ctx...);, not throw SomeException(strex("... {} ...", value));. A constant message keeps every occurrence of the same failure identical, so failures group and sort by message uniqueness while the variable parts travel in the arguments — the same rule the script-side verify macro follows. Do not build the message with strex / std::format / + from runtime values.
• Never throw anything that is not derived from std::exception, and treat catch (...) as a defect handler, not an error handler. Every exception the engine raises comes from the FO_DECLARE_EXCEPTION hierarchy or the standard library, so a non-std::exception type walks past every catch (const std::exception&) recovery path and arrives with nothing to report. Wherever a catch (...) sits beside a catch (const std::exception& ex), its entire body is FO_UNKNOWN_EXCEPTION(); — which raises StrongAssertationException, reports it, and terminates the process. Do not log it and continue, fabricate an "Unknown exception" message, count it as an ordinary failure, or rethrow it as a domain exception. The only places that may swallow instead are no-throw teardown/unwind paths (noexcept bodies, scope_exit/scope_fail bodies, safe_call targets, destructors, C-ABI callbacks) and the reporting/logging machinery itself, which must not re-enter while reporting. Full rule: Docs/ExceptionSafety.md §2.1.
• Write for exception safety. A throw must never escape a function leaving a broken invariant. As you write or change engine code, derive the exception-safety level the body provides (NoThrow / Strong / Basic / None) per Docs/ExceptionSafety.md (§5 disposition ladder, §8 levels): do fallible/validating work (throwing numeric_cast, duplicate/collision guards) before the first observable mutation, insert into the authoritative store before any derived cache, and undo an early flag/counter/lock/handle mutation on unwind with scope_fail (noexcept body) or RAII on raw OS/third-party resources. Never aim for None — it is a defect tier to fix, not to record. Allocation terminates on OOM (§1) so do not write allocation-only rollbacks, and entity create/destroy is throw-as-signal (Basic by design). Embedding projects track the per-function level in an audit baseline gated by CI (Last Frontier: Tools/ExceptionSafetyAudit/); update it in the same change.
• Use numeric_cast for numeric conversions; do not use static_cast for numeric narrowing/widening unless the surrounding code has a specific established reason.
• Use fixed-width types (int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, float32_t, float64_t, size_t) instead of bare int / float in new engine code.
• Do not use auto for primitive values or simple obvious types such as string, hstring, size_t, and the fixed-width aliases.
• Use the engine smart-pointer vocabulary from Source/Essentials/SmartPointers.h — ptr<T>/nptr<T> for borrows, unique_*/refcount_* for owners, engine-own shared_ptr/weak_ptr via SafeAlloc::MakeShared() — instead of std:: smart pointers or bare raw T*. Raw pointers remain only at the documented ABI/low-level allowlist boundaries; inside a function, bind them to wrappers before ordinary engine work and unwrap with .get() only at the final handoff. See Docs/SmartPointers.md; embedding projects may gate this with an audit tool (Last Frontier: Tools/SmartPointerAudit/).
• Use the engine container aliases from Source/Essentials/Containers.h, never their std:: originals — string, wstring, vector, map, unordered_map, set, list, deque, stringstream, small_vector. Each is the standard container instantiated on SafeAllocator, so it follows the terminate-on-OOM contract instead of throwing std::bad_alloc. For allocation that cannot be expressed as a C++ container, use SafeAlloc: the Make* family for typed objects, and the raw tier (MallocRaw/CallocRaw/ReallocRaw/FreeRaw, MallocAlignedRaw/FreeAlignedRaw) for third-party C-ABI hooks. Do not reach for bare malloc/free, and do not use std::format/std::vformat/std::to_string, which materialise a std::allocator string — format into an existing buffer with std::format_to/std::vformat_to instead. Exceptions are limited to foreign ABI boundaries, the Essentials modules above MemorySystem in the include order, and standard types with no allocator parameter; each one is recorded with a written reason. See Docs/Essentials.md; embedding projects may gate this with an audit tool (Last Frontier: Tools/AllocatorAudit/).
• Use the engine callable wrappers from Source/Essentials/FunctionObjects.h, never std::function — function<Sig> (an alias of move_only_function<Sig>) is the default, and copyable_function<Sig> is for a stored callable that is genuinely copied, such as one snapshotted during dispatch or handed to several owners. Both keep a small nothrow-movable target inside the wrapper, so an ordinary closure allocates nothing. When a function member no longer compiles because something copies it, first check whether the copy should be a std::move; reach for copyable_function only when the copy is the actual contract. The sole remaining std::function is the StackTrace.h script-provider hook, which sits above the callable module in the Essentials order. See Docs/Essentials.md.
• Task-language definition: in requirements, reviews, and conversation about engine code, informal wording such as “pointer”, “raw pointer”, “borrowed pointer”, “указатель”, or “сырой указатель” means a non-owning engine borrow, not permission to write a bare C++ T*. Use ptr<T> when presence is guaranteed and nptr<T> when absence is valid. A bare T* is authorized only when the request explicitly requires the literal C++ T* type and identifies a documented ABI/low-level boundary; if either condition is missing, the wrapper rule wins.
• For Entity and derived types use pointers, not references.
• Prefer static free functions for file-local helpers instead of unnamed namespaces.
• Do not add static variables for hidden state or caches; see the Behavioral Rules above for the narrow allowed uses of static.
• Add const and noexcept where they express the semantic contract; do not add them mechanically everywhere possible. For noexcept specifically: a NoThrow exception-safety classification alone never justifies the keyword — the ES baseline records the current fact, while noexcept is a contract that blocks future legitimate validating throws. Reserve it for move operations/swap, teardown/unwind-path callables (scope_exit/scope_fail bodies, safe_call targets), C-ABI callbacks, and documented no-throw primitives; see Docs/ExceptionSafety.md §8.
• Use ignore_unused(...) only for variables/objects; for an intentionally ignored function-call result, write (void)FunctionCall(...).
• For C++ string/text construction and parsing, prefer existing engine helpers such as strex and strvex when they make formatting or token handling clearer. If the helper surface is missing a repeated string-formatting operation, add a reusable helper in the appropriate engine utility layer instead of open-coding ad hoc parsing/formatting at call sites.
• Gate conditional compilation on our own (FO_* / project) macros with #if FOO / #if !FOO, never #ifdef / #ifndef: every such macro is mandatorily #defined to 0 or 1, so its definedness must never carry meaning — only its value does.
• Keep engine-owned source inventories unconditional. Add every engine-owned .h / .cpp pair to its normal CMake source list even when the feature is optional; the files themselves own the #if FO_* guard. Do not mirror a feature toggle around AppendList(...), and do not create a second feature-only AppendList for the guarded module. Likewise, do not wrap #include directives for self-guarded engine headers in a standalone feature conditional: include them normally and keep the feature guard around declarations/definitions that need it. Conditional third-party targets, link dependencies, and third-party headers whose include paths only exist with the feature may remain gated.
• Include layering: non-Essentials engine code must consume Essentials modules through Common.h, not by including individual Source/Essentials/*.h headers directly. STL headers are centralized through BasicCore.h; add or adjust standard-library includes there instead of including <...> headers from higher layers.
• Essentials layering is strict. The Source/Essentials/Essentials.h aggregate lists Essentials headers in include order — each Essentials header (and its .cpp) may only depend on headers listed above it in that block. This is a compile- and link-time rule: declaring a function in an early header but defining it in a later module is still a forbidden reverse dependency, even when no downward #include appears. Public declarations are implemented in their owning module (or an earlier one), and BuildTools/tests/test_essentials_layering.py enforces both direct-include direction and definition ownership for namespace-level extern APIs. If a low-layer module needs information that physically lives in a higher layer, expose only what the lower layer can produce on its own or take the higher-layer value as a parameter — do not back-channel the include and do not reorder the block to work around it.
• Iterating server-side entities while events may fire: any script-visible event (e.g. OnItemOnMapAppeared.Fire(...), OnCritterDisappeared.Fire(...)) can re-enter scripts and mutate world state — including destroying the very entity being iterated. The convention is: (1) snapshot the iteration set with copy_hold_ref(...) so each element is held by ref-count for the duration of the loop; (2) re-validate inside the loop with if (cr->IsDestroyed()) continue; (and after each event for any other entity you keep working with); (3) fire scripted events at the end of the unit of work, after non-revocable state changes are committed.
• Keep edited source files ending with exactly one trailing blank line.
• Keep docs reusable: describe engine behavior first; mention Last Frontier only as an embedding-project example, never as an engine-doc dependency or validation owner.
• Keep README.md human-oriented and AGENTS.md AI-oriented. CLAUDE.md is intentionally only a pointer to @AGENTS.md.