xpTURN.Klotho (Godot)

Deterministic Multiplayer Simulation Framework for Godot (.NET)

A deterministic-simulation framework supporting Client-Side Prediction (CSP), Rollback, Frame Synchronization, Server-Driven mode, and Replay. The simulation core is engine-agnostic pure C# with a Godot (.NET) adapter on top. By excluding floating-point and building the simulation solely on 32.32 fixed-point (FP64) and a deterministic RNG (Xorshift128+), it guarantees full reproducibility across platforms and compilers.

Klotho weaves the simulation, one frame at a time.

How synchronization works, in one paragraph: determinism is the keystone — given the same ordered inputs, every peer computes byte-identical state, so the network carries inputs only and verification reduces to comparing a hash. On that foundation each peer keeps two timelines over the same tick axis: a Verified chain (ticks where every player's real input is known — immutable) and a Predicted chain (ticks run ahead using guessed remote input — provisional). Like CPU branch prediction, the simulation advances immediately on predicted input instead of waiting; when a real input contradicts a guess, the engine restores a snapshot and re-simulates (rollback), which is cheap precisely because state is a pure function of inputs. Input delay and adaptive timing buffers minimize how often that happens, and when determinism genuinely breaks, a graded recovery ladder (hash check → rollback → full-state resync → corrective reset) restores agreement. The same machinery serves both P2P lockstep (peers hold equal authority) and Server-Driven (the server owns the verified chain). Full rationale: Docs/SynchronizationDesign.md.

Suitable Genres

Genres that benefit most from Klotho's deterministic simulation features.

Best Fit (core targets)

• Fighting games — frame-perfect inputs + rollback netcode
• Platform fighters / arena brawlers
• 2–4 player PvP action — optimal for small-roster P2P rollback
• Tactics / turn-based SRPG — determinism + replay + sync verification
• Real-time strategy (RTS) — lockstep frame sync
• MOBA / top-down arena — ECS, physics, and navigation all included
• Twin-stick shooters / co-op shooters — deterministic physics + ORCA avoidance
• Auto-battlers — deterministic simulation + shareable replays

Good Fit (structurally well-suited)

• Roguelike / roguelite (PvE co-op) — deterministic RNG (Xorshift128+) for shared seeds and replays
• Card / board / deckbuilder PvP — low input volume, strong verification and replay
• Puzzle PvP / falling-block versus
• Racing (small scale) — fixed-point physics guarantees determinism for small grids
• Top-down survival action

Architecture

Three-layer separation:

• Klotho engine layer — Pure C#, engine-independent (no Godot references). The same binary runs under the Godot (.NET) adapter and on the server side (.NET console / ASP.NET).
• Simulation transport layer — UDP transport over the INetworkTransport abstraction (Input / InputAck / SyncCheck / Handshake). LiteNetLib is provided as the default reference implementation; replaceable with any other library.
• Game service layer — Lobby / matchmaking / authentication (external gRPC, etc.; integrated outside this project).

Tech Stack

• Godot 4.4+ (mono / .NET, net8.0) — the Godot adapter ships as addons/klotho/ (prebuilt core DLL + adapter source).
• C# language level — net8.0 / LangVersion latest; native init / required, no polyfill required.
• Task — async uses the standard library Task (no UniTask dependency).
• xpTURN.Klotho.Logging (IKLogger) — in-house structured logging (no external logging dependency).
• LiteNetLib — default reference implementation for UDP transport (MIT, pure C#); arrives as the NuGet package LiteNetLib 2.1.4. The transport layer is abstracted via INetworkTransport and is replaceable.
• Newtonsoft.Json — DataAsset JSON serialization (NuGet Newtonsoft.Json 13.0.3).

Details: Docs/BaseLibraries.md

Installation

Requires Godot 4.4+ (mono / .NET). Install the client addon first, then (optionally) wire a dedicated server — both share the same engine-agnostic core.

Client (.NET addon)

The Godot adapter ships as a self-contained addons/klotho/ folder — a prebuilt engine-agnostic core DLL + the Godot adapter source (compiled against your own GodotSharp) + the source generator.

1. Copy the klotho/ folder into your project's res://addons/.
2. Add one line to your game .csproj:

   <Import Project="addons/klotho/Klotho.props" />
   

   No .csproj yet? Generate one via Project ▸ Tools ▸ C# ▸ Create C# solution, then add the line above.

3. Build (dotnet build or the Godot editor's Build button).

Klotho.props references the prebuilt core DLL, adds the generator analyzer, and declares the managed runtime dependencies as NuGet PackageReferences (Newtonsoft.Json 13.0.3, LiteNetLib 2.1.4). The adapter sources under addons/klotho/Adapters/** are picked up automatically by the Godot.NET.Sdk default compile glob — do not add an explicit <Compile Include>. The adapter is net8.0, so no Polyfill step is needed (native init / required). Input is captured with Godot's built-in Input API; deterministic navigation data is loaded from a pre-baked .bytes asset.

Keep any dedicated-server project outside the game project folder (a sibling — see below) so the Godot.NET.Sdk default glob never compiles its Program.cs / server callbacks into the client. If you must nest it, exclude it explicitly: <Compile Remove="Server\**\*.cs" />.

Dedicated server (optional)

The dedicated server is engine-agnostic — a plain net8.0 console host on Microsoft.NET.Sdk that uses the core, never the Godot adapter, so the host ships with zero Godot runtime. The same addons/klotho/ you imported for the client also ships a server props file. Add one line to your server .csproj:

<Import Project="addons/klotho/Klotho.Server.props" />

Klotho.Server.props references the prebuilt xpTURN.Klotho.Runtime.dll + KlothoServer.dll, adds the generator analyzer, declares the NuGet deps, and Removes the Godot adapter sources from the compile. Then compile your shared deterministic sim into the exe and copy the data asset + config next to the output. Keep the server as a sibling of the game project so the paths reach back into the client folder for the shared addon / sim / data, and at startup call KlothoServerBootstrap.Initialize("YourGamePrefix") so the cross-assembly [ModuleInitializer] registrations complete before the first room.

Full step-by-step walkthrough (folder contents, plugin.cfg, server .csproj, config files, run commands): Installation.Godot.md.

Quick Start

The four-step path — define a component → implement a system → wire callbacks → create & drive a session — runs the same shape everywhere; the session-driving and view layers are Godot-specific:

• Controller — a Node controller with GodotSessionDriver pumped from _Process.
• Config — Resource-based configs (GodotSimulationConfig / GodotSessionConfig).
• Joins — standard Task-based entry points.
• View — EntityViewNode / EntityViewUpdaterNode authored in .tscn.

Steps 1–3 (component / system / callbacks) are engine-agnostic core; KlothoSessionFlow exposes the same entry points (StartHostAndListen / JoinP2PAsync / JoinServerDrivenAsync / ReconnectAsync / SpectateAsync / StartReplayFromFile). Session creation is observed through the single IKlothoSessionObserver.OnSessionCreated(session, SessionEntryKind kind) — branch on kind, not simCfg.Mode.

Full step-by-step walkthrough (component / system / callbacks, session driving, view binding, Godot-specific wiring): QuickStart.Godot.md.

Samples

• Samples/GodotP2pSample — minimal P2P (Godot)
• Samples/GodotSdSample — minimal Server-Driven (Godot)

Each covers session driving, view binding, and Godot-specific wiring (Node controller, Resource configs, .tscn view layer).

Documentation Map

Design Principles

• Determinism first — no float; all simulation state is FP64 / integer / bool
• Zero-GC oriented — ref struct, object pools, cached fields, no LINQ
• Engine independence — the core is pure C# (no Godot references); engine integration lives in an adapter layer on top of the shared core
• Minimal bandwidth — only inputs (commands) are sent; no state synchronization (only hash verification)
• Layer separation — strict separation between simulation callbacks (deterministic) and view callbacks (non-deterministic)