{"id":50665493,"url":"https://github.com/xpturn/klotho","last_synced_at":"2026-06-08T06:02:40.549Z","repository":{"id":354348406,"uuid":"1219568287","full_name":"xpTURN/Klotho","owner":"xpTURN","description":"Deterministic Unity \u0026 Godot framework for rollback, lockstep \u0026 server-authoritative multiplayer. Engine-agnostic pure C# core, FP64 fixed-point math, ECS, physics, navigation, and replays — frame-perfect, cross-platform reproducible.","archived":false,"fork":false,"pushed_at":"2026-06-07T10:08:42.000Z","size":46623,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T11:20:02.397Z","etag":null,"topics":["client-side-prediction","deterministic","ecs","fixed-point","frame-sync","godot-engine","lockstep","multiplayer","networking","replay","rollback","server-authoritative","simulation","unity-package","unity3d-plugin","upm"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xpTURN.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-24T02:19:36.000Z","updated_at":"2026-06-07T10:08:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xpTURN/Klotho","commit_stats":null,"previous_names":["xpturn/klotho"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/xpTURN/Klotho","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpTURN%2FKlotho","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpTURN%2FKlotho/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpTURN%2FKlotho/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpTURN%2FKlotho/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xpTURN","download_url":"https://codeload.github.com/xpTURN/Klotho/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xpTURN%2FKlotho/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34050224,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-side-prediction","deterministic","ecs","fixed-point","frame-sync","godot-engine","lockstep","multiplayer","networking","replay","rollback","server-authoritative","simulation","unity-package","unity3d-plugin","upm"],"created_at":"2026-06-08T06:02:39.111Z","updated_at":"2026-06-08T06:02:40.543Z","avatar_url":"https://github.com/xpTURN.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xpTURN.Klotho\n[![Unity 2022.3+](https://img.shields.io/badge/unity-2022.3%2B-blue.svg)](https://unity3d.com/get-unity/download)\n[![Godot 4.4+ (.NET)](https://img.shields.io/badge/godot-4.4%2B%20(.NET)-478cbf.svg)](https://godotengine.org/download)\n[![License: Apache License Version 2.0](https://img.shields.io/badge/License-Apache-brightgreen.svg)](https://github.com/xpTURN/Klotho/blob/main/LICENSE)\n\n**Deterministic Multiplayer Simulation Framework for Unity and Godot**\n\n\u003e ⚠️ **Experimental Release**\n\u003e This project is under active development and has not yet reached a stable stage. Public APIs, serialization formats, and network protocols may change without notice. Production use is not recommended.\n\nA 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 **Unity** and **Godot (.NET)** adapters 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.\n\n\u003e Klotho weaves the simulation, one frame at a time.\n\n**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](Docs/SynchronizationDesign.md).\n\n---\n\n## Key Features\n\n| Area | Contents |\n| ---- | ---- |\n| **Network Models** | P2P Lockstep · Rollback + Client Prediction · Server-Driven (Authoritative) · Dedicated Server · Spectator · Late Join · Reconnect |\n| **Deterministic Math** | `FP64` (32.32 fixed-point) · `FPVector2/3/4` · `FPQuaternion` · `FPMatrix` · LUT/CORDIC-based trigonometry · `DeterministicRandom` (Xorshift128+) |\n| **Physics** | `FPPhysicsWorld` · Broadphase (SpatialGrid) · Narrowphase · CCD (Sweep) · Constraint Solver · Joints · Triggers · Static BVH |\n| **Navigation** | `FPNavMesh` · A* (triangle graph) · Funnel (SSFA) · ORCA avoidance · ECS-integrated `NavAgentComponent` |\n| **ECS** | Sparse-set `ComponentStorage\u003cT\u003e` · `Frame` (single byte[] heap) · `FilterWithout/Filter\u003cT1..T5\u003e` · `FrameRingBuffer` · `SystemRunner` |\n| **Serialization / Source Generator** | `SpanWriter/Reader` (ref struct, GC-free) · automatic code generation via `[KlothoComponent]` / `[KlothoSerializable]` / `[KlothoDataAsset]` |\n| **Data Assets** | `IDataAsset` · `DataAssetRegistry` · `DataAssetRef` · JSON serialization (`xpTURN.Klotho.DataAsset.Json`) |\n| **Replay** | Record / playback / seek / variable speed · LZ4 compression (`K4os.Compression.LZ4`) |\n| **Verification Tools** | `SyncTestRunner` (GGPO-style determinism verification) · `DeterminismVerificationRunner` · benchmark suite |\n| **Unity Integration** | `USimulationConfig` · `USessionConfig` · View layer (`EntityViewFactory` / `EntityViewUpdater` / `EntityView`, `BindBehaviour` / `ViewFlags`, `VerifiedFrameInterpolator`) · `KlothoSessionDriver` (MonoBehaviour) · `KlothoConnectionAsync` (UniTask) |\n| **Godot Integration** | `GodotSimulationConfig` · `GodotSessionConfig` (Resource) · View layer (`EntityViewFactory` / `EntityViewUpdaterNode` / `EntityViewNode`, `VerifiedFrameInterpolator`) · `GodotSessionDriver` (Node) · `GodotConnectionAsync` (`Task`) · `GodotDebugSink` / `GodotLogSink` |\n\n---\n\n## Suitable Genres\n\nGenres that benefit most from Klotho's deterministic simulation features.\n\n### Best Fit (core targets)\n\n- **Fighting games** — frame-perfect inputs + rollback netcode\n- **Platform fighters / arena brawlers**\n- **2–4 player PvP action** — optimal for small-roster P2P rollback\n- **Tactics / turn-based SRPG** — determinism + replay + sync verification\n- **Real-time strategy (RTS)** — lockstep frame sync\n- **MOBA / top-down arena** — ECS, physics, and navigation all included\n- **Twin-stick shooters / co-op shooters** — deterministic physics + ORCA avoidance\n- **Auto-battlers** — deterministic simulation + shareable replays\n\n### Good Fit (structurally well-suited)\n\n- **Roguelike / roguelite (PvE co-op)** — deterministic RNG (Xorshift128+) for shared seeds and replays\n- **Card / board / deckbuilder PvP** — low input volume, strong verification and replay\n- **Puzzle PvP / falling-block versus**\n- **Racing (small scale)** — fixed-point physics guarantees determinism for small grids\n- **Top-down survival action**\n\n---\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Game Application                         │\n│   (ISimulation impl: EcsSimulation or custom Simulation)    │\n└───────────────────────────┬─────────────────────────────────┘\n                            │\n         ┌──────────────────┼──────────────────┐\n         ▼                  ▼                  ▼\n  ┌───────────────┐   ┌──────────────┐   ┌────────────────────┐\n  │ KlothoEngine  │   │ ReplaySystem │   │KlothoNetworkService│\n  │ (orchestrator)│◄  │ (record/play)│   │                    │\n  └──────┬────────┘   └──────────────┘   └─────────┬──────────┘\n         │                                         │\n    ┌────┴────┐                              ┌─────┴──────┐\n    ▼         ▼                              ▼            ▼\n ISimulation  InputBuffer               INetworkTransport  NetworkMessages\n    │\n    ├── (ECS) Frame — EntityManager + ComponentStorage[]\n    ├── SystemRunner — ISystem[]\n    ├── FrameRingBuffer (snapshots / rollback)\n    └── DataAssetRegistry\n```\n\nThree-layer separation:\n- **Klotho engine layer** — Pure C#, engine-independent (no `UnityEngine` / Godot references). The same binary runs under the Unity and Godot (.NET) adapters and on the server side (.NET console / ASP.NET).\n- **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.\n- **Game service layer** — Lobby / matchmaking / authentication (external gRPC, etc.; integrated outside this project).\n\n---\n\n## Tech Stack\n\n- **Unity 2022.3+** — scripting backends: Mono / IL2CPP (AOT-safe; serialization via source generation, no runtime codegen/reflection)\n- **Godot 4.4+ (mono / .NET, net8.0)** — the Godot adapter ships as `addons/klotho/` (prebuilt core DLL + adapter source).\n- **C# language level** — Unity targets **C# 8.0** with the `xpTURN.Polyfill` package supplying the runtime-attribute shims required by C# 11; the Godot adapter is **net8.0 / `LangVersion latest`** and needs no polyfill (native `init` / `required`).\n- **UniTask** — async on Unity only (Cysharp). The **Godot adapter uses the standard library `Task`** — no UniTask dependency.\n- **xpTURN.Klotho.Logging (IKLogger)** — in-house structured logging (no external logging dependency). Optional MEL interop via the `Plugins~/Logging.Mel` sample adapter (`Microsoft.Extensions.Logging.Abstractions` DLL is consumer-provided).\n- **LiteNetLib** — default reference implementation for UDP transport (MIT, pure C#). On Unity it is **vendored as source** under `Runtime/ThirdParty/LiteNetLib.v2.1.4`; on Godot it arrives as the **NuGet package `LiteNetLib 2.1.4`**. The transport layer is abstracted via `INetworkTransport` and is replaceable.\n- **Newtonsoft.Json** — DataAsset JSON serialization (Unity: `com.unity.nuget.newtonsoft-json` · Godot: NuGet `Newtonsoft.Json 13.0.3`)\n- **K4os.Compression.LZ4** — replay compression (Unity: vendored under `Runtime/ThirdParty/` · Godot: NuGet `K4os.Compression.LZ4 1.3.8`)\n\nDetails: [Docs/BaseLibraries.md](Docs/BaseLibraries.md)\n\n---\n\n## Installation\n\nKlotho installs differently per engine — follow the matching guide. Each covers the **client** first, then the optional **dedicated server** (a plain .NET host on the shared engine-agnostic core):\n\n- **[Installation — Unity](Docs/Installation.Unity.md)** — UPM git URLs + Polyfill activation, then `Server~` project references for a dedicated server.\n- **[Installation — Godot (.NET)](Docs/Installation.Godot.md)** — the `addons/klotho/` folder + a one-line `Klotho.props` import, then the (engine-agnostic) dedicated server.\n\nThe in-repo projects under [`Samples/`](Samples/) double as install references — see the [Documentation Map](#documentation-map) for per-sample walkthroughs.\n\n---\n\n## Repository Layout\n\nKlotho lives at the repository top level under `com.xpturn.klotho/`. Unity consumers install the package via UPM; Godot consumers use the `Godot~/` adapter packaged as an `addons/klotho/` folder (see [Installation](#installation)). The in-repo Unity samples consume the package through a `file:` manifest reference to the same top-level package.\n\n```\n\u003crepo root\u003e/\n├── README.md  ·  CHANGELOG.md  ·  LICENSE\n├── com.xpturn.klotho/             ← ★ framework package\n│   ├── package.json\n│   ├── Runtime/                   engine-agnostic core + Unity adapter\n│   │   ├── Core/                  engine · session · network\n│   │   ├── Logging/               IKLogger (in-house)\n│   │   ├── Gameplay/              built-in components / systems\n│   │   ├── Diagnostics/           fault injection · metrics\n│   │   ├── Input/                 input buffer / predictor\n│   │   ├── Network/               transport · server · spectator\n│   │   ├── State/                 snapshot manager\n│   │   ├── Serialization/         SpanWriter/Reader\n│   │   ├── Replay/                record / playback (LZ4)\n│   │   ├── ECS/                   Frame · components · systems\n│   │   ├── Deterministic/         FP64 · physics · navigation\n│   │   ├── Unity/                 Unity adapter\n│   │   ├── LiteNetLib/            UDP transport\n│   │   └── ThirdParty/            vendored deps\n│   ├── Godot~/                    Godot (.NET) adapter\n│   ├── Editor/                    Unity-only editor tools\n│   ├── Plugins/Analyzers/         source generator\n│   ├── Prefabs/                   debug prefabs (Unity)\n│   ├── Plugins~/Logging.Mel/      MEL interop sample\n│   └── Server~/                   dedicated-server projects\n│\n├── addons/klotho/                 ← Godot addon\n│\n├── Samples/                       ← standalone samples\n│   ├── Brawler/                   4-player fighter (Unity)\n│   ├── P2pSample/                 minimal P2P (Unity)\n│   ├── SdSample/                  minimal Server-Driven (Unity)\n│   ├── GodotP2pSample/            minimal P2P (Godot)\n│   ├── GodotSdSample/             minimal Server-Driven (Godot)\n│   └── LoggingMelConsole/         .NET logging sample\n│\n├── Docs/                          ← documentation\n└── Tools/                         ← .NET tooling (internal)\n    ├── KlothoGenerator/           source generator\n    ├── KlothoGenerator.Tests/     generator tests\n    ├── DeterminismVerification/   determinism verifier\n    ├── PhysicsDeterminismProbe/   FP determinism probe\n    └── gen.sh                     generator build script\n```\n\n---\n\n## Quick Start\n\nThe four-step path — define a component → implement a system → wire callbacks → create \u0026 drive a session — is the same shape on both engines, but the session-driving and view layers are engine-specific. Pick the matching walkthrough (each is self-contained, with full code):\n\n- **[Quick Start — Unity](Docs/QuickStart.Unity.md)** — `MonoBehaviour` controller, `KlothoSessionDriver`, `ScriptableObject` configs, UniTask joins, `EntityViewFactory` / `EntityViewUpdater` / `EntityView`.\n- **[Quick Start — Godot (.NET)](Docs/QuickStart.Godot.md)** — `Node` controller, `GodotSessionDriver` (`_Process`), `Resource` configs, standard `Task` joins, `EntityViewNode` / `EntityViewUpdaterNode` (`.tscn`).\n\nSteps 1–3 (component / system / callbacks) are engine-agnostic core; `KlothoSessionFlow` exposes the same entry points (`StartHostAndListen` / `JoinP2PAsync` / `JoinServerDrivenAsync` / `ReconnectAsync` / `SpectateAsync` / `StartReplayFromFile`) on both — Unity wraps the async ones in UniTask, Godot in standard `Task`. Session creation is observed through the single `IKlothoSessionObserver.OnSessionCreated(session, SessionEntryKind kind)` — branch on `kind`, not `simCfg.Mode`.\n\nDetailed guides: [Docs/GameDevWorkflow.md](Docs/GameDevWorkflow.md), [Docs/GameDevAPI.md](Docs/GameDevAPI.md)\n\n---\n\n## Sample\n\n[Samples/Brawler](Samples/Brawler) — a 4-player fighting-game sample\n\n- ECS-based combat / movement / skills / cooldowns / knockback / items / traps\n- HFSM-based bot AI (`BotHFSMRoot` / `BotActions` / `BotDecisions`)\n- Camera integration with Unity Cinemachine\n- Supports both P2P and ServerDriven modes\n- LZ4-compressed replay record / playback\n\nDocs: [Docs/Samples/Brawler.md](Docs/Samples/Brawler.md)\n\n---\n\n## Documentation Map\n\n| Document | Contents |\n| ---- | ---- |\n| [Docs/Installation.Unity.md](Docs/Installation.Unity.md) · [Docs/Installation.Godot.md](Docs/Installation.Godot.md) | Engine-specific install (client + dedicated server) |\n| [Docs/QuickStart.Unity.md](Docs/QuickStart.Unity.md) · [Docs/QuickStart.Godot.md](Docs/QuickStart.Godot.md) | Engine-specific 5-step quick starts (component → system → callbacks → session → view) |\n| [Docs/FEATURES.md](Docs/FEATURES.md) | Full feature list |\n| [Docs/Specification.md](Docs/Specification.md) | Engine specification (state machines · configuration · events · message protocol · formats) |\n| [Docs/SynchronizationDesign.md](Docs/SynchronizationDesign.md) | Synchronization design direction (determinism · two-chain model · prediction/rollback · timing · authority models · recovery ladder) |\n| [Docs/GameDevWorkflow.md](Docs/GameDevWorkflow.md) | Game-developer workflow (step-by-step) |\n| [Docs/GameDevAPI.md](Docs/GameDevAPI.md) | Game-developer API status |\n| [Docs/SimulationConfigGuide.md](Docs/SimulationConfigGuide.md) | SimulationConfig recommended-value guide (per genre / platform) |\n| [Docs/BaseLibraries.md](Docs/BaseLibraries.md) | List of base libraries used |\n| [Docs/Navigation.md](Docs/Navigation.md) | Deterministic navigation (FPNavMesh · A* · Funnel · ORCA) |\n| [Docs/Samples/Brawler.md](Docs/Samples/Brawler.md) · [Docs/Samples/P2pSample.md](Docs/Samples/P2pSample.md) · [Docs/Samples/SdSample.md](Docs/Samples/SdSample.md) | `Unity` sample walkthroughs — Brawler, P2pSample, SdSample |\n| [Docs/Samples/GodotSdSample.md](Docs/Samples/GodotSdSample.md) · [Docs/Samples/GodotP2pSample.md](Docs/Samples/GodotP2pSample.md) | `Godot (.NET)` sample walkthroughs (architecture + Godot-specific gotchas) |\n\n---\n\n## Design Principles\n\n- **Determinism first** — no float; all simulation state is FP64 / integer / bool\n- **Zero-GC oriented** — ref struct, object pools, cached fields, no LINQ\n- **Engine independence** — the core is pure C# (no `UnityEngine` / `Godot` references); engine integration (Unity / Godot) lives in adapter layers on top of the shared core\n- **Minimal bandwidth** — only inputs (commands) are sent; no state synchronization (only hash verification)\n- **Layer separation** — strict separation between simulation callbacks (deterministic) and view callbacks (non-deterministic)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxpturn%2Fklotho","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxpturn%2Fklotho","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxpturn%2Fklotho/lists"}