CultLib/src/GameCult.Mesh/README.md

212 lines
6.8 KiB
Markdown
Raw Normal View History

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);
```
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).
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
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
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)
- [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)