- C# 44.5%
- Rust 16.3%
- TypeScript 15.2%
- Python 10.6%
- HTML 5%
- Other 8.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
The bridge was one platform, one role and one host: Windows by construction (`windows.h`, `__declspec`, `CryptHashCertificate2`), client-only, and shaped around the managed connector that polls it every 2 ms. Nothing about MsQuic required that; the shape came from having exactly one caller. It now carries a C ABI v2 of twelve exports over a single per-runtime event queue: open a runtime, open listeners and connections on it, open streams and send frames, and take typed events out of one blocking wait. The event struct is 64 bytes described by layout rather than by a shared header, so a host declares it in its own FFI and no header travels with the ABI. `next_event` keeps the v1 two-phase convention — return 2, leave the event at the head, report the size the caller needs — because that is the one part of v1 that was already host-agnostic. The rule that shapes everything else is that nothing calls out. MsQuic's worker threads only push onto the queue and wake that wait, so no host runtime is entered from a thread it does not own, and the bridge needs to know nothing about what is on the other side. That is what makes one binary serve both a Node process through FFI and a Unity player through P/Invoke. Trust moved out. A v2 client connection defers validation, emits the DER as event 3 and answers MsQuic only when the host calls `connection_certificate_complete`; if the host never answers, MsQuic's handshake timeout closes the connection and event 4 says so. The C code no longer has an opinion about certificates — except in the v1 shim, where it must. The five v1 exports are unchanged in signature and behaviour and are now `#ifdef _WIN32`, matching `CanConnect`'s own Windows gate. A v1 client is a private v2 runtime holding one connection, and the pin comparison is the single thing it still decides in C, because that is the contract the shipped Unity package was built against. `windows.h`, `wincrypt.h` and `CryptHashCertificate2` appear nowhere outside that block. Two things the rewrite had to get right that the old shape never exercised. The v1 pin must be attached before `ConnectionStart`, not after it returns: the handshake runs on an MsQuic worker thread and reaches the certificate event immediately on loopback, so a pin applied afterwards loses the race and the connection silently takes the host path nobody is listening on. And teardown must close the connection handles itself — `RegistrationClose` blocks until the app has closed every child handle, and a silent shutdown delivers no shutdown events at all, so leaning on the callbacks to do it deadlocks the caller forever. Both were found by the tests hanging, and both now have a mutation that reproduces them. Verified: the four v1 tests in tests/GameCult.Mesh.Quic.Native.Tests pass unchanged (3 passed, 1 skipped for want of an external endpoint), including the wrong-pin refusal and the departed-client broadcast test. A 15-check FFI smoke drives the whole v2 path — listener, deferred certificate, both sides connected, latest-only stream, one frame with FIN, identical bytes out — and passes on Windows x64 and on Linux x64. Ten source mutations, ten killed, two green no-op controls. One open fork, reported separately and not decided here: the pinned Windows MsQuic is the Schannel build, which refuses QUIC_CREDENTIAL_TYPE_CERTIFICATE_PKCS12 with QUIC_STATUS_NOT_SUPPORTED, so `listener_open` cannot open a provider against it. The map assumed PKCS12 was "one credential type for Schannel and OpenSSL"; the header declares it but the Schannel provider does not implement it. The identical bridge binary passes the full provider smoke against OpenSSL MsQuic 2.5.9, so this is a question about which flavour Windows pins, not about the bridge. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> |
||
| .github/workflows | ||
| .voidbot | ||
| .vscode | ||
| contracts | ||
| docs | ||
| native/GameCult.Mesh.Quic.Native | ||
| notes | ||
| packages | ||
| research/cultnet-distributed-database | ||
| samples | ||
| scripts | ||
| src | ||
| tests | ||
| tools | ||
| unity/org.gamecult.cultlib | ||
| .gitattributes | ||
| .gitignore | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| CultLib.sln | ||
| Directory.Build.props | ||
| LICENSE | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
CultLib
CultLib is GameCult's shared state, transport, and runtime substrate. It started
as reusable C# game infrastructure, but the useful thing now is larger: typed
.cc persistence, schema-stable wire formats, ergonomic reliable-UDP
networking, distributed database sync, simulation witness consensus, streaming
surfaces, and UI/runtime affordances that can be used from C#, TypeScript, Rust,
Python, and Kotlin without each runtime inventing its own local folklore.
The stack is less a single product than a set of capabilities:
- logging primitives and implementations
- CultCache typed documents,
.ccpersistence, and SoA memory access - CultNet schema-v0 messages over TCP and LiteNetLib adapters, a bounded ASP.NET Core WebSocket host adapter, and CultLib's native cross-runtime RUDP pipe
- CultMesh distributed realtime database, Verse discovery, authority leases, shard replication, and witness-authoritative simulation consensus
- typed geometry domain/chunk documents for distributed CSG and LOD streaming
- low-latency stream catalogs and frame-handle negotiation for media, tensors, and runtime-native buffers
- Eve/CultUI daemon-published surfaces that lower into GUI, TUI, web, native, overlay, or agent-facing clients
- declarative Unity UI composition and reflective runtime inspector tooling
The practical pitch: a runtime can persist typed state, exchange it with peers, discover compatible schemas, join a Verse, publish observations, reconcile canonical state, and expose an operator surface without translating through a bespoke JSON bridge at every boundary. A frontend is just another CultMesh client: the daemon publishes a typed Eve/CultUI surface, and any compatible runtime can lower that surface where it needs to live.
Which Package Do I Want?
If the job is shared game state, start here before inventing a fourth drawer and pretending the label makes it furniture.
| Job | Start With | Owns | Use When | Do Not Use It For |
|---|---|---|---|---|
| Local typed state | GameCult.Caching / CultCache |
Document identity, schema compatibility, record keys, indexes, globals, and local persistence | You need a typed cache, file-compatible save data, local reactive reads, or a stable domain document model | Peer discovery, transport security, shard routing, or mesh consensus |
| Portable math | GameCult.Math / CultMath |
Shader-shaped numeric primitives, deterministic random, noise, and CPU/GPU parity helpers | Shared simulation and geometry code must not depend on an engine's math or RNG types | Domain-specific geometry, rendering, or world authority |
| Procedural geometry | GameCult.Geometry / CultGeometry |
Isosurface extraction plus CultCache-native domains, LOD requests, selected cuts, and mesh artifacts | C#, Rust, Godot, or remote workers need shared geometry algorithms and typed results | Transport policy, peer discovery, or gameplay authority |
| Network transport and database plumbing | GameCult.Networking / CultNet |
Native RUDP sessions, LiteNetLib/TCP adapters, an authenticated WebSocket host adapter, schema-v0 wire contracts, shard authority, raw document replication, snapshots, and subscriptions | You need a client/server pipe, login/session flow, schema discovery, reliable UDP, or a low-level distributed CultCache lane | Gameplay-facing mesh ergonomics, Verse policy, mod branches, or simulation consensus composition |
| Distributed realtime gameplay state | GameCult.Mesh / CultMesh |
Public mesh entrypoints, Verse discovery, peer exchange, shard replication defaults, authority leases, client prediction, and witness consensus | You want the game to treat clients and servers as one reactive database for persistent state, input state, and simulation facts | A tiny local-only tool, a bare transport client, or a storage format contract |
| Realtime media/frame streams | GameCult.Mesh / CultMesh streaming mode |
Stream identity, authority, clock metadata, body transport negotiation, frame cursors, and backpressure state | Audio/video/tensor frames need to move between runtimes through shared memory, GPU handles, platform buffers, or CultCache page refs | Durable document mutation, mesh consensus facts, or pretending inline bytes are zero-copy |
| Daemon-published UI | Eve / CultUI | Typed operator and user-facing surfaces over CultMesh state | A daemon should expose controls, inspection, or workflow UI that can lower into GUI, TUI, web, native, overlay, or agent clients | One-off vendor dashboards, untyped debug panels, or runtime-local UI that cannot travel with the daemon |
Quick rule:
- Choose CultCache when the problem is "how do I model and persist typed state?"
- Choose GameCult.Math when the problem is "which portable numeric and random semantics do these runtimes share?"
- Choose GameCult.Geometry when the problem is "how do geometry workers build and share engine-neutral geometry?"
- Choose CultNet when the problem is "how do peers exchange authenticated, schema-aware database messages?"
- Choose CultMesh when the problem is "how does a game join a Verse and share realtime state across a mesh?"
- Choose CultMesh streaming mode when the problem is "how do these runtimes move audio/video frames while the mesh owns identity, clocks, cursors, and pressure?"
- Choose Eve/CultUI when the problem is "how does this daemon publish its own operable surface instead of waiting for a hosted admin console?"
CultMesh sits on CultNet, and CultNet distributes CultCache documents. That is the stack. If a design needs another peer-to-peer category, first check whether it is really Verse policy, peer exchange, or shard authority wearing a fake mustache.
If you want to build an application rather than tour the component drawer,
start with the maintained
CultMesh And Eve Getting Started
series. Its first executable package-consumer checkpoint is
samples/eve-two-runtime.
The real-process browser continuation is
samples/eve-browser-network.
One documented command runs both layers:
pwsh -File ./scripts/verify-eve-getting-started.ps1
The implemented browser client boundary and remaining deployed-infrastructure
gates are mapped explicitly in
browser-verse-transport.md.
If you want only the smallest durable "open node -> put typed doc -> get typed doc"
path, use
src/GameCult.Mesh/docs/durable-node-quickstart.md.
If you want the lower-level "typed local document -> raw wire document ->
mesh/runtime watch surface" handoff, follow it with
src/GameCult.Mesh/docs/typed-document-path.md.
Repository Scope
The solution includes:
GameCult.Logging: common logging abstraction plus console and file implementationsGameCult.Caching:DatabaseEntry-based cache, indexes, global entries, and backing-store abstractionsGameCult.Caching.MessagePack: MessagePack-backed persistence for the cacheGameCult.Caching.NewtonsoftJson: Newtonsoft.Json-backed persistence for the cacheGameCult.Math/ CultMath: portable numeric primitives, deterministic random, noise, and shader-parity helpersGameCult.Geometry/ CultGeometry: engine-neutral geometry algorithms plus CultCache-native domain, selected-cut, and mesh artifact documentsGameCult.Networking: encrypted login/register/verify flows, schema-v0 contracts, transport adapters, and native RUDP sessionsGameCult.Networking.WebSockets: bounded ASP.NET Core binary WebSocket host adapter for browser CultMesh clientsGameCult.Mesh: CultMesh package home for distributed realtime database, shard replication, client prediction, Verse discovery, and mesh witness consensusGameCult.Caching.Tests: NUnit tests for cache and backing-store behaviorGameCult.Networking.Tests: NUnit tests for networking behaviorGameCult.Unity: CultUI, a Unity runtime UI composition framework with reflective inspector generation, prefab-backed field resolvers, reusable controls, and a demo project packaged for UPM-style consumptionpackages/cultcache-ts: TypeScript CultCache with MessagePack persistence and inspector toolingpackages/cultnet-ts: TypeScript CultNet schema-v0 contracts, framing, discovery, raw document replication, and interop testspackages/cultmesh-ts: TypeScript CultMesh local node and mesh catalog surface for local runtimes such as VoidBotpackages/cultmesh-browser: browser-safe, read-only CultMesh document leases and typed operations over an Odin-resolved WebSocket routepackages/cultcache-py: Python CultCache with CultCache v1 wire paritypackages/cultnet-py: Python CultNet contracts, framing, RUDP transport, replication, and interop peerpackages/cultmesh-py: Python CultMesh local node, discovery, sessions, local server, and daemonpackages/cultcache-rs: Rust CultCache and derive macropackages/cultnet-rs: Rust CultNet contracts, framing, discovery, and interop peerpackages/cultmesh-kotlin: Kotlin/JVM CultMesh and CultNet surface for Android-adjacent runtimes
Repository Layout
package.json
src/
GameCult.Logging/
GameCult.Caching/
GameCult.Caching.MessagePack/
GameCult.Caching.NewtonsoftJson/
GameCult.Geometry/
GameCult.Networking/
GameCult.Networking.WebSockets/
GameCult.Mesh/
GameCult.Unity/
tests/
GameCult.Caching.Tests/
GameCult.Geometry.Tests/
GameCult.Networking.Tests/
packages/
cultmath/
cultcache-ts/
cultnet-ts/
cultmesh-ts/
cultmesh-browser/
cultmesh-kotlin/
cultcache-py/
cultnet-py/
cultmesh-py/
cultcache-rs/
cultnet-rs/
Build
dotnet build CultLib.sln
Test
dotnet test CultLib.sln
TypeScript package tests:
npm test --workspace packages/cultcache-ts
npm test --workspace packages/cultnet-ts
npm run test:interop --workspace packages/cultnet-ts
npm test --workspace packages/cultmesh-ts
npm test --workspace packages/cultmesh-browser
Measured reactive, retained-session, and shared-memory hot-body gates:
pwsh -File ./scripts/measure-reactive-document-performance.ps1 -Quick
pwsh -File ./scripts/verify-eve-getting-started.ps1
The first command measures the same 16 KiB document workload in C#, TypeScript, and Python and includes a mapped hot-body probe with explicit copy telemetry on Windows named maps and Unix file-backed maps. The second includes 10,000 real WebSocket operations on one retained identity-owned C# session after provider route replacement.
Rust package tests:
cargo test --manifest-path packages/cultcache-rs/Cargo.toml
cargo test --manifest-path packages/cultnet-rs/Cargo.toml
Kotlin package build:
.\packages\cultmesh-kotlin\build.ps1
Common Concepts
DatabaseEntry
The cache-centric libraries revolve around DatabaseEntry. Every entry has a stable Guid identifier and can optionally:
- expose a human-readable name through
INamedEntry - participate in generic indexes registered at runtime
- be treated as a global singleton entry through
GlobalSettingsAttribute
Typical entry shape:
using GameCult.Caching;
public class ItemData : DatabaseEntry, INamedEntry
{
public string Name = string.Empty;
public int Value;
public string EntryName
{
get => Name;
set => Name = value;
}
}
CultCache and Backing Stores
CultCache is an in-memory index over DatabaseEntry objects. It can operate entirely in memory, or it can be attached to one or more backing stores for persistence and synchronization.
- the cache is the query surface
- backing stores are persistence adapters
- indexes and name maps are maintained inside the cache, not inside the store
Multiple Backing Stores
Every document type has exactly one home store. There are no mirrors.
cache.AddBackingStore(catalogStore, typeof(ItemData), typeof(Faction));
cache.AddBackingStore(runStore, typeof(SavedGame));
- the home is chosen by the document's runtime type: the most derived routed type wins, otherwise the untyped store
- at most one untyped store; a type claimed by two stores is an error
- a write with no home is an error once any store is attached
- attaching a store reads it; attach routed stores first and the untyped store (if any) last, because a record's home cannot move after it is loaded
- loading never writes: opening and flushing without a mutation leaves every file byte-identical
- a read-only store refuses writes and is skipped by flush
The contract is src/GameCult.Caching/Contracts/cultcache-store-composition.md. Until the C# cache implements it, AddBackingStore takes no home types and every attached store receives every record; attach one store per cache.
Example: Cache + Networking
using GameCult.Caching;
using GameCult.Logging;
using GameCult.Networking;
var cache = new CultCache
{
Logger = new ConsoleLogger()
};
var server = new Server(cache)
{
Logger = new ConsoleLogger()
};
server.Start();
Secrets and Runtime Configuration
GameCult.Networking uses two pieces of deployment configuration:
GAMECULT_CONNECTION_KEYGAMECULT_SESSION_SIGNING_SECRET
Production guidance:
- set both values before starting the server
- treat
GAMECULT_CONNECTION_KEYas shared client/server protocol configuration - treat
GAMECULT_SESSION_SIGNING_SECRETas a server-only secret - generate high-entropy random values and store the server-side value in your platform's secret store
- do not rely on local-development defaults in production
- partial configuration is rejected at startup
Recommended value format:
- at least 32 random bytes per value
- encode as Base64 or Base64Url if you want a portable text representation
Example secret generation in PowerShell:
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))
Typical production setup patterns:
- inject
GAMECULT_SESSION_SIGNING_SECRETand the server copy ofGAMECULT_CONNECTION_KEYas environment variables from Docker secrets, Kubernetes secrets, systemd environment files, or your cloud secret manager - ship the matching
GAMECULT_CONNECTION_KEYto the client through a build-generated config asset, code-generated constants, or another explicit client configuration mechanism - scope them per environment so development, staging, and production do not share values
- rotate
GAMECULT_SESSION_SIGNING_SECREToperationally - treat
GAMECULT_CONNECTION_KEYas versioned protocol config; changing it requires a coordinated client/server rollout
Example server startup with strict environment validation:
using GameCult.Caching;
using GameCult.Networking;
var cache = new CultCache();
var security = ServerSecurityOptions.FromEnvironment();
var server = new Server(cache, security);
Example local-development server startup:
using GameCult.Caching;
using GameCult.Networking;
var cache = new CultCache();
var security = ServerSecurityOptions.Development();
var server = new Server(cache, security);
Example shipped-client startup with explicit client configuration:
using GameCult.Networking;
var security = new ClientSecurityOptions("<matching-connection-key>");
var client = new Client(security);
Project Docs
Each subproject has a local README with package-specific detail: