A scalable server framework for real-time, stateful multiplayer worlds.
A C23 core owns the performance-critical systems: transport, the reactor, spatial indexing, the world stream fabric, and the simulation. Game logic extends the core in Python. Simulation models that need more than Python speed ship as C shared libraries against the same ABI. The core also stands alone: it installs headers and CMake targets, and examples/minimal boots a server with no Python at all.
The world is divided into cells that publish state once; gateways subscribe to cells and compose a per-player view. The fabric carries that stream. The same game code runs as a single embedded process or as a distributed cluster; the topology is a constructor argument.
kith fits real-time, stateful worlds under high concurrency: movement, presence, spatial queries, world state streamed to every connected client. A turn-based or request/response game gains little from it; state moves on a simulation cadence.
The framework runs on Linux only; the reactor is io_uring. It ships without accounts, authentication, matchmaking, or billing; those services belong to the game.
- Five-plane fabric: Sim, Fabric, Gateway, Coord, Control, with the data-flow contracts between planes enforced by CI.
- Pluggable components within planes: sim models, database queries, wire types, control routes, and delivery presets register behind their plane's contract.
- Switchable topologies: embedded single-process, distributed multi-instance, one build.
- Deterministic simulation with replay files and state-hash coverage.
- Free-threaded Python: handlers dispatch on a worker pool off the reactor; runs on standard and 3.14t interpreters.
- Additive C ABI: opaque types, size-versioned structs, an ABI-diff gate.
- Hardened builds by default: PIE, RELRO, stack canaries, CFI, NX.
- Agentic testing: headless clients drive setup, act, assert, diagnose.
- One observability contract: structured logging, metrics, tracing.
Tagged releases ship a binary wheel, the sdist, and SHA256 checksums on the releases page. The wheel bundles the compiled core; boot an embedded server:
python3 -m venv .venv && source .venv/bin/activate
pip install kith_fw-1.0.0-py3-none-manylinux_2_38_x86_64.whlThe PyPI distribution is kith-fw; the module you import is kith.
from kith import Server
with Server(topology="embedded") as server:
print(f"kith: gateway={server.listen_port}")
server.serve() # blocks; Ctrl-C stops it cleanlyThe getting started guide continues from that boot: handlers, control routes, persistence, the two-instance cluster.
Prefer to see it move first? The released wheel ships an out-of-box visual example — a living world with ambient actors, a graphical client, and one command to play:
pip install "kith-fw[visual]"
kith-visual play crowd-in # bots converge on your cell; watch the HUDgit clone https://github.com/pianosuki/kith kith && cd kith
./scripts/setup.sh # preflight, git config, uv sync, hooks
source .venv/bin/activate
cmake --preset release && cmake --build build/release
python -m examples.free_movement.server # prints: free_movement: gateway=… control=…In a second terminal, drive the running server over its control plane:
curl -X POST http://127.0.0.1:<control>/spawn # {"actor_id": 1}
curl http://127.0.0.1:<control>/query_state # the actor's live state./scripts/verify.sh is the same gate CI runs: lint, commits, build,
free-threaded. From a verified tree, CONTRIBUTING.md
is the contributor workflow.
From a built tree, install the headers and libraries:
cmake --install build/release --prefix /opt/kithA downstream CMake project configures with the prefix on its search path
(-DCMAKE_PREFIX_PATH=/opt/kith) and links the imported targets —
kith::server is the composition root a game links against, and every plane
library is an imported target beside it:
find_package(kith 1.0.0 REQUIRED)
target_link_libraries(my_game PRIVATE kith::server)Hand-written Makefiles and autotools consume the pkg-config entry point:
PKG_CONFIG_PATH=/opt/kith/lib/pkgconfig pkg-config --cflags --libs kithtests/consumer/ is a minimal downstream project that exercises both
channels in CI.
- Linux, x86-64, glibc 2.38 or newer.
import kithraises a load error on any other platform. - Python 3.14+, standard or free-threaded builds.
- Wheel path: the bundled libraries link
liburing,libpq,libhiredisat runtime; install them from the system package manager. - Source path: Clang 22+ (or GCC 14+), clang-format-23 (the pinned formatter —
uv tool install clang-format==23.1.0, then symlink~/.local/bin/clang-formatasclang-format-23), CMake 4.4+, Ninja 1.13+,uv,pre-commit.
Releases follow Semantic Versioning from 1.0.0. The public C ABI evolves additively: public types stay opaque, parameter structs carry size and ABI-version fields, and an ABI-diff gate guards every header change (ADR-0008). The Python API is the ctypes binding of that ABI, generated from the same headers, with no separate version line: a change that breaks the C ABI breaks Python with it, and both ride the project version.
Within 1.x nothing is deprecated: evolution is additive, and breaking
changes wait for the next major version. The decision records under
docs/architecture/adr/ are frozen at 1.0.0 and evolve only by supersession
or explicit amendment, not by external contribution.
- API reference, by symbol: the Doxygen reference rendered from the public headers.
- Guides, by task: getting started, Python extensions, C simulation models, scaling gates, agentic headless clients, the wire protocol, the publish choreography, operations, replay format.
- Architecture, by contract: planes, layers, topologies, tracing, performance budgets, event schema, and the decision records.
CONTRIBUTING.md is the workflow; AGENTS.md is the coding standard and review checklist. CODE_OF_CONDUCT.md governs participation; SECURITY.md takes private vulnerability reports. General issues and questions are answered best-effort by the single maintainer, with no response-time guarantee; vulnerability reports carry their own channel and expectations in SECURITY.md.
Apache License, Version 2.0. See LICENSE for the full text.