2026-05-19 19:08:48 +01:00
|
|
|
# CultMesh
|
|
|
|
|
|
|
|
|
|
CultMesh is the distributed realtime database and simulation-consensus layer for
|
|
|
|
|
GameCult projects. The NuGet package and assembly are named `GameCult.Mesh`;
|
|
|
|
|
the public surface is branded as CultMesh.
|
|
|
|
|
|
|
|
|
|
CultMesh sits over:
|
|
|
|
|
|
|
|
|
|
- `GameCult.Caching` for typed domain documents, local indexes, persistence, and
|
|
|
|
|
file-compatible cache storage.
|
|
|
|
|
- `GameCult.Networking` for LiteNetLib transport, schema-v0 wire messages, and
|
|
|
|
|
secure client/server sessions.
|
|
|
|
|
|
|
|
|
|
The intent is direct: a game can treat a mesh of clients and servers as one
|
|
|
|
|
reactive database for persistent state, prediction-friendly input state, and
|
|
|
|
|
simulation observations.
|
|
|
|
|
|
|
|
|
|
## First Node
|
|
|
|
|
|
|
|
|
|
```csharp
|
|
|
|
|
using GameCult.Mesh;
|
|
|
|
|
|
|
|
|
|
using var node = await CultMesh.StartNodeAsync("world.ccmp");
|
|
|
|
|
|
|
|
|
|
var player = await node.Database.GetAsync<PlayerData>(playerKey);
|
|
|
|
|
await node.Database.PutAsync(playerKey, player);
|
|
|
|
|
```
|
|
|
|
|
|
2026-05-21 00:00:15 +01:00
|
|
|
If you want one inspectable path that starts with a durable local cache file and
|
|
|
|
|
ends with a typed read/write through the public CultMesh surface, see
|
|
|
|
|
[docs/durable-node-quickstart.md](docs/durable-node-quickstart.md).
|
|
|
|
|
If you want the lower-level typed-to-raw handoff that CultNet moves across the
|
|
|
|
|
wire, see [docs/typed-document-path.md](docs/typed-document-path.md).
|
|
|
|
|
|
2026-05-19 21:13:33 +01:00
|
|
|
Enable durable authoritative shard logs when a node should serve replica
|
|
|
|
|
catch-up after restart:
|
|
|
|
|
|
|
|
|
|
```csharp
|
|
|
|
|
using var node = await CultMesh.StartNodeAsync("world.ccmp", new CultMeshNodeOptions
|
|
|
|
|
{
|
|
|
|
|
EnableDurableShardLogs = true
|
|
|
|
|
});
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If `ShardLogPath` is omitted, CultMesh stores logs beside the cache under
|
|
|
|
|
`world.cultmesh/shard-logs`.
|
|
|
|
|
|
2026-05-19 19:08:48 +01:00
|
|
|
## Verses
|
|
|
|
|
|
|
|
|
|
A Verse is a rule-bearing consensus graph. Aetheria Main can be a
|
|
|
|
|
cloud-authoritative Verse backed by GameCult regional simulators. A modded
|
|
|
|
|
community branch can be transport-compatible with Aetheria Main while declaring
|
|
|
|
|
different rules, required plugins, and authority policy. A peer-hosted game can
|
|
|
|
|
choose a peer-to-peer authority model.
|
|
|
|
|
|
|
|
|
|
```csharp
|
|
|
|
|
var rulesHash = CultMeshVerseDescriptor.ComputeRulesHash(
|
|
|
|
|
"aetheria",
|
|
|
|
|
"rules:v1",
|
|
|
|
|
"plugins:vanilla");
|
|
|
|
|
|
|
|
|
|
var aetheria = new CultMeshVerseDescriptor(
|
|
|
|
|
"aetheria-main",
|
|
|
|
|
"Aetheria",
|
|
|
|
|
CultMeshVerseAuthorityModel.OperatorCluster,
|
|
|
|
|
new CultMeshVerseCompatibility("cultmesh.v0", rulesHash),
|
|
|
|
|
discoveryEndpoints: ["cultmesh://us-east.aetheria.gamecult.net:3075"]);
|
|
|
|
|
|
|
|
|
|
using var catalog = CultMesh.CreateVerseCatalog();
|
|
|
|
|
catalog.Upsert(aetheria);
|
2026-05-19 21:23:11 +01:00
|
|
|
|
|
|
|
|
using var discovery = CultMesh.ServeVerseCatalog(node, catalog);
|
2026-05-19 19:08:48 +01:00
|
|
|
```
|
|
|
|
|
|
2026-05-19 21:23:11 +01:00
|
|
|
Peers can request Verse catalogs over schema-v0 with
|
|
|
|
|
`cultmesh.verse_catalog_request.v0` and receive transport-filtered
|
|
|
|
|
`cultmesh.verse_catalog_response.v0` descriptors.
|
|
|
|
|
|
2026-05-20 01:35:39 +01:00
|
|
|
## Peer Exchange
|
|
|
|
|
|
|
|
|
|
Verse discovery tells a node which consensus graph exists. Peer exchange tells
|
|
|
|
|
it who else is already in that graph.
|
|
|
|
|
|
|
|
|
|
```csharp
|
|
|
|
|
using var peers = CultMesh.CreatePeerCatalog();
|
|
|
|
|
peers.Upsert(new CultMeshPeerCard(
|
|
|
|
|
"gc-us-east-1",
|
|
|
|
|
"aetheria-main",
|
|
|
|
|
["cultnet://us-east.aetheria.gamecult.net:3075"],
|
|
|
|
|
roles: [CultMeshPeerRoles.Discovery, CultMeshPeerRoles.ShardPrimary],
|
|
|
|
|
shardIds: ["players-us-east"],
|
|
|
|
|
authorityLeaseId: "lease:players-us-east:42"));
|
|
|
|
|
|
|
|
|
|
using var exchange = CultMesh.ServePeerExchange(node, peers);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Peer cards are contact candidates, not authority by themselves. Public Verses
|
|
|
|
|
should validate authority leases or signatures before trusting a peer for
|
|
|
|
|
committed state.
|
|
|
|
|
|
2026-05-20 01:49:18 +01:00
|
|
|
```csharp
|
|
|
|
|
var leases = CultMesh.CreateAuthorityLeaseCatalog();
|
|
|
|
|
leases.Upsert(new CultMeshAuthorityLease(
|
|
|
|
|
"lease:players-us-east:42",
|
|
|
|
|
"aetheria-main",
|
|
|
|
|
"gc-us-east-1",
|
|
|
|
|
[CultMeshPeerRoles.ShardPrimary],
|
|
|
|
|
["players-us-east"],
|
|
|
|
|
"gamecult-operator",
|
|
|
|
|
DateTimeOffset.UtcNow.AddMinutes(-1),
|
|
|
|
|
DateTimeOffset.UtcNow.AddMinutes(10),
|
|
|
|
|
signature: "operator-signature"));
|
|
|
|
|
```
|
|
|
|
|
|
2026-05-20 01:41:12 +01:00
|
|
|
Clients can fetch more peers from known peers:
|
|
|
|
|
|
|
|
|
|
```csharp
|
|
|
|
|
var exchangeClient = CultMesh.CreatePeerExchangeClient();
|
|
|
|
|
await exchangeClient.DiscoverAsync(
|
|
|
|
|
peers,
|
|
|
|
|
aetheria.DiscoveryEndpoints,
|
|
|
|
|
"aetheria-main",
|
|
|
|
|
roles: [CultMeshPeerRoles.ReadReplica]);
|
|
|
|
|
```
|
|
|
|
|
|
2026-05-19 19:08:48 +01:00
|
|
|
## Client-Side Prediction
|
|
|
|
|
|
|
|
|
|
CultMesh lets a runtime declare which input documents it may author
|
|
|
|
|
optimistically. The local cache updates immediately, game simulation can proceed
|
|
|
|
|
against that predicted state, and the authoritative shard log later reconciles
|
|
|
|
|
the record.
|
|
|
|
|
|
|
|
|
|
```csharp
|
|
|
|
|
var db = node.Database;
|
|
|
|
|
|
|
|
|
|
await db.PutPredictedAsync(inputKey, inputState);
|
|
|
|
|
|
|
|
|
|
using var sub = db.WatchRecord<PlayerInput>(inputKey)
|
|
|
|
|
.Subscribe(change =>
|
|
|
|
|
{
|
|
|
|
|
ReconcilePrediction(change);
|
|
|
|
|
});
|
|
|
|
|
```
|
|
|
|
|
|
2026-05-20 07:45:10 +01:00
|
|
|
## Game Session
|
|
|
|
|
|
|
|
|
|
`CultMeshGameSession` wires the common gameplay loop: local catalogs,
|
|
|
|
|
observation hub, observation server, peer exchange, Verse discovery, prediction,
|
|
|
|
|
and quorum fact commits.
|
|
|
|
|
|
|
|
|
|
```csharp
|
|
|
|
|
using var session = CultMesh.CreateGameSession(node, new CultMeshGameSessionOptions
|
|
|
|
|
{
|
|
|
|
|
ConsensusOptions = new CultNetSimulationConsensusOptions
|
|
|
|
|
{
|
|
|
|
|
MinimumWitnesses = 2,
|
|
|
|
|
QuorumRatio = 0.66d
|
|
|
|
|
}
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
await session.PredictAsync(inputKey, inputState);
|
|
|
|
|
|
|
|
|
|
var committed = await session.SubmitAndCommitAsync(new CultNetSimulationObservation
|
|
|
|
|
{
|
|
|
|
|
WitnessRuntimeId = "watcher-1",
|
|
|
|
|
ShardId = "arena",
|
|
|
|
|
ShardEpoch = 4,
|
|
|
|
|
Frame = 100,
|
|
|
|
|
SubjectId = "bob",
|
|
|
|
|
ClaimKind = "hit",
|
|
|
|
|
ClaimHash = CultNetSimulationObservation.ComputeClaimHash("hit", "alice", "bob", "frame:100")
|
|
|
|
|
});
|
|
|
|
|
```
|
|
|
|
|
|
2026-05-19 19:08:48 +01:00
|
|
|
## Witness Consensus
|
|
|
|
|
|
|
|
|
|
CultMesh nodes can publish observations about simulation facts: shard epoch,
|
|
|
|
|
frame, subject, claim kind, and claim hash. `CultNetSimulationConsensus`
|
|
|
|
|
aggregates those observations deterministically into candidate facts with
|
|
|
|
|
support weight, total observed weight, confidence, and quorum status.
|
|
|
|
|
|
|
|
|
|
Those candidates are not committed world state by themselves. They are the fast
|
2026-05-20 01:58:36 +01:00
|
|
|
mesh opinion layer that can feed an authoritative shard commit path. Once a
|
|
|
|
|
candidate has quorum, a shard-authoritative node can commit it as a
|
|
|
|
|
`CultMeshSimulationFact`.
|
|
|
|
|
|
|
|
|
|
```csharp
|
|
|
|
|
var committer = CultMesh.CreateSimulationFactCommitter(node.Database);
|
|
|
|
|
await committer.CommitAsync(candidate);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The central server does not need to decide what every witness saw. It only
|
|
|
|
|
needs to accept the quorum result through the shard log.
|
2026-05-19 19:08:48 +01:00
|
|
|
|
2026-05-19 19:55:29 +01:00
|
|
|
## Durable Catch-Up
|
|
|
|
|
|
|
|
|
|
CultMesh can persist authoritative shard logs through
|
|
|
|
|
`ICultNetShardMutationLogStore`. The included file store writes one MessagePack
|
|
|
|
|
log per shard, so a restarted primary can still serve replica catch-up without
|
2026-05-19 20:53:45 +01:00
|
|
|
depending on warm process memory. When retained log history is compacted, stale
|
|
|
|
|
replicas get an explicit resync requirement instead of a partial log pretending
|
2026-05-19 21:07:46 +01:00
|
|
|
to be enough. The replicator can answer that by fetching a shard-bounded
|
|
|
|
|
snapshot, replacing the local shard view, and advancing its cursor to the
|
|
|
|
|
snapshot's represented log sequence.
|
2026-05-19 19:55:29 +01:00
|
|
|
|
2026-05-19 19:08:48 +01:00
|
|
|
## Documentation
|
|
|
|
|
|
|
|
|
|
- [Public API](docs/public-api.md)
|
2026-05-21 00:00:15 +01:00
|
|
|
- [Durable Node Quickstart](docs/durable-node-quickstart.md)
|
2026-05-20 21:27:33 +01:00
|
|
|
- [Typed Document Path](docs/typed-document-path.md)
|
2026-05-19 19:08:48 +01:00
|
|
|
- [Research Notes](docs/research.md)
|
|
|
|
|
- [Verse Model](docs/verses.md)
|