No description
  • C# 44.5%
  • Rust 16.3%
  • TypeScript 15.2%
  • Python 10.6%
  • HTML 5%
  • Other 8.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Meta Vens 6a091ef65c Make the MsQuic bridge a two-role event queue instead of a Unity client
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>
2026-09-16 21:03:01 +02:00
.github/workflows Run both halves of the realtime frame parity in CI 2026-09-16 20:21:27 +02:00
.voidbot REC-102: cut stale generated mirrors and a dead maintenance receipt 2026-09-13 14:10:10 +02:00
.vscode Initial commit 2026-04-18 06:04:39 +01:00
contracts Encode a CultMesh realtime frame in TypeScript 2026-09-16 19:20:41 +02:00
docs Record Soul's Cut 2 pass and correct one attribution 2026-09-16 19:58:50 +02:00
native/GameCult.Mesh.Quic.Native Make the MsQuic bridge a two-role event queue instead of a Unity client 2026-09-16 21:03:01 +02:00
notes Specify canonical CultCache persistence format 2026-05-08 00:16:55 +01:00
packages Say what the eleven stricter endpoint spellings actually are 2026-09-16 20:21:42 +02:00
research/cultnet-distributed-database Add CultNet simulation observation server 2026-05-19 18:48:53 +01:00
samples Give the counter sample integer MessagePack keys 2026-09-14 00:27:19 +02:00
scripts Stop the realtime decoder handing back a view of its own frame 2026-09-16 20:20:16 +02:00
src Release CultLib Unity 1.0.59 and the Studio 1.3.1 2026-09-14 21:35:34 +02:00
tests Encode a CultMesh realtime frame in TypeScript 2026-09-16 19:20:41 +02:00
tools Authenticate CultMesh authority routes and replay operations 2026-08-18 19:02:46 +02:00
unity/org.gamecult.cultlib Release CultLib Unity 1.0.59 and the Studio 1.3.1 2026-09-14 21:35:34 +02:00
.gitattributes Initial commit 2026-04-18 06:04:39 +01:00
.gitignore Ignore Python package build output 2026-09-10 13:55:46 +02:00
AGENTS.md JSON backing store, I/O fixes, Networking Security 2026-04-18 13:01:24 +01:00
CLAUDE.md Wire AGENTS.md into Claude Code memory 2026-09-04 00:33:01 +02:00
CultLib.sln Delete the CultCache MessagePack source generator 2026-09-13 23:38:08 +02:00
Directory.Build.props Ship authenticated remote transports in Unity package 2026-08-18 20:23:27 +02:00
LICENSE Initial commit 2026-04-18 06:04:39 +01:00
package-lock.json Give every cultcache-ts document type one home store 2026-09-14 00:37:31 +02:00
package.json Add real browser CultMesh transport proof 2026-08-18 00:05:57 +02:00
README.md Delete the CultCache MessagePack source generator 2026-09-13 23:38:08 +02:00

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, .cc persistence, 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 implementations
  • GameCult.Caching: DatabaseEntry-based cache, indexes, global entries, and backing-store abstractions
  • GameCult.Caching.MessagePack: MessagePack-backed persistence for the cache
  • GameCult.Caching.NewtonsoftJson: Newtonsoft.Json-backed persistence for the cache
  • GameCult.Math / CultMath: portable numeric primitives, deterministic random, noise, and shader-parity helpers
  • GameCult.Geometry / CultGeometry: engine-neutral geometry algorithms plus CultCache-native domain, selected-cut, and mesh artifact documents
  • GameCult.Networking: encrypted login/register/verify flows, schema-v0 contracts, transport adapters, and native RUDP sessions
  • GameCult.Networking.WebSockets: bounded ASP.NET Core binary WebSocket host adapter for browser CultMesh clients
  • GameCult.Mesh: CultMesh package home for distributed realtime database, shard replication, client prediction, Verse discovery, and mesh witness consensus
  • GameCult.Caching.Tests: NUnit tests for cache and backing-store behavior
  • GameCult.Networking.Tests: NUnit tests for networking behavior
  • GameCult.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 consumption
  • packages/cultcache-ts: TypeScript CultCache with MessagePack persistence and inspector tooling
  • packages/cultnet-ts: TypeScript CultNet schema-v0 contracts, framing, discovery, raw document replication, and interop tests
  • packages/cultmesh-ts: TypeScript CultMesh local node and mesh catalog surface for local runtimes such as VoidBot
  • packages/cultmesh-browser: browser-safe, read-only CultMesh document leases and typed operations over an Odin-resolved WebSocket route
  • packages/cultcache-py: Python CultCache with CultCache v1 wire parity
  • packages/cultnet-py: Python CultNet contracts, framing, RUDP transport, replication, and interop peer
  • packages/cultmesh-py: Python CultMesh local node, discovery, sessions, local server, and daemon
  • packages/cultcache-rs: Rust CultCache and derive macro
  • packages/cultnet-rs: Rust CultNet contracts, framing, discovery, and interop peer
  • packages/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_KEY
  • GAMECULT_SESSION_SIGNING_SECRET

Production guidance:

  • set both values before starting the server
  • treat GAMECULT_CONNECTION_KEY as shared client/server protocol configuration
  • treat GAMECULT_SESSION_SIGNING_SECRET as 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_SECRET and the server copy of GAMECULT_CONNECTION_KEY as environment variables from Docker secrets, Kubernetes secrets, systemd environment files, or your cloud secret manager
  • ship the matching GAMECULT_CONNECTION_KEY to 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_SECRET operationally
  • treat GAMECULT_CONNECTION_KEY as 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: