Document CultLib substrate and schema server port

This commit is contained in:
Meta Vens 2026-06-21 16:31:50 +01:00
commit d85f3fd32a
8 changed files with 161 additions and 26 deletions

View file

@ -1,16 +1,30 @@
# CultLib
CultLib is a set of reusable C# libraries for game backends, game-adjacent services, and Unity-integrated tooling, including a declarative runtime UI composition framework for Unity.
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 libraries cover three main areas:
The stack is less a single product than a set of capabilities:
- logging primitives and implementations
- a typed in-memory cache with pluggable persistence
- LiteNetLib-based networking with encrypted credential exchange and signed session tokens
- CultMesh distributed realtime database and simulation-consensus primitives
- CultCache typed documents, `.cc` persistence, and SoA memory access
- CultNet schema-v0 messages over TCP, WebSocket, LiteNetLib adapters, 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
- 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.
## Which Package Do I Want?
If the job is shared game state, start here before inventing a fourth drawer
@ -20,7 +34,7 @@ and pretending the label makes it furniture.
| --- | --- | --- | --- | --- |
| 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 |
| Procedural geometry state | `GameCult.Geometry` | CultCache-native domain trees, LOD build requests, selected-cut diagnostics, and chunk artifact payloads | Rust, Unity, or remote workers need to share CSG/LOD geometry and graph metadata as typed state | Transport policy, peer discovery, or gameplay authority |
| Network transport and database plumbing | `GameCult.Networking` / CultNet | LiteNetLib transport, authentication, schema-v0 wire contracts, shard authority, raw document replication, snapshots, and subscriptions | You need a client/server pipe, login/session flow, schema discovery, or a low-level distributed CultCache lane | Gameplay-facing mesh ergonomics, Verse policy, mod branches, or simulation consensus composition |
| Network transport and database plumbing | `GameCult.Networking` / CultNet | Native RUDP sessions, LiteNetLib/TCP/WebSocket adapters, authentication, 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 |
@ -59,7 +73,7 @@ The solution includes:
- `GameCult.Caching.MessagePack.Generator`: source generator for MessagePack formatters for cache models
- `GameCult.Caching.MessagePack.Analyzers`: packaging project that delivers the generator to consuming projects
- `GameCult.Geometry`: CultCache-native geometry domain, selected-cut, and chunk artifact documents for VibeGeometry/Fensalir-style pipelines
- `GameCult.Networking`: encrypted login/register/verify flows and message dispatch over LiteNetLib
- `GameCult.Networking`: encrypted login/register/verify flows, schema-v0 contracts, transport adapters, and native RUDP sessions
- `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
@ -70,6 +84,7 @@ The solution includes:
- `packages/cultcache-py`: Python CultCache/CultNet/CultMesh package with CultCache v1 wire parity
- `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
@ -94,6 +109,7 @@ packages/
cultcache-ts/
cultnet-ts/
cultmesh-ts/
cultmesh-kotlin/
cultcache-py/
cultcache-rs/
cultnet-rs/
@ -127,6 +143,12 @@ cargo test --manifest-path packages/cultcache-rs/Cargo.toml
cargo test --manifest-path packages/cultnet-rs/Cargo.toml
```
Kotlin package build:
```powershell
.\packages\cultmesh-kotlin\build.ps1
```
## Common Concepts
### `DatabaseEntry`

View file

@ -1204,6 +1204,14 @@ pub fn create_rudp_transport_profile(
max_fragment_bytes: options.max_fragment_bytes,
max_pending_reliable_packets: options.max_pending_reliable_packets,
},
CultNetTransportChannel {
channel_id: "media".to_string(),
delivery: CultNetTransportDelivery::Reliable,
ordering: CultNetTransportOrdering::Unordered,
max_payload_bytes: options.max_payload_bytes,
max_fragment_bytes: options.max_fragment_bytes,
max_pending_reliable_packets: options.max_pending_reliable_packets,
},
],
}],
}
@ -1325,6 +1333,12 @@ fn channel_send_options(channel_id: &str, now_ms: u64) -> CultNetRudpSendOptions
sequenced: true,
now_ms,
},
"media" => CultNetRudpSendOptions {
reliable: true,
ordered: false,
sequenced: false,
now_ms,
},
_ => CultNetRudpSendOptions {
reliable: false,
ordered: false,

View file

@ -377,6 +377,12 @@ fn rudp_transport_profile_advertises_state_and_realtime_channels() {
CultNetTransportOrdering::Unordered,
Some(64)
),
(
"media",
CultNetTransportDelivery::Reliable,
CultNetTransportOrdering::Unordered,
Some(64)
),
]
);
}

View file

@ -8,8 +8,8 @@ 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.
- `GameCult.Networking` for CultNet schema-v0 wire messages, native RUDP,
transport adapters, 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

View file

@ -52,7 +52,7 @@ namespace GameCult.Networking
/// <summary>
/// Peer context for a schema-v0 RUDP server.
/// </summary>
public sealed class RudpCultNetSchemaServerPeer
public sealed class RudpCultNetSchemaServerPeer : ICultNetSchemaServerPeer
{
private readonly RudpCultNetSchemaServer _server;
@ -86,11 +86,12 @@ namespace GameCult.Networking
/// <summary>
/// Multi-peer schema-v0 host over the native CultNet RUDP transport.
/// </summary>
public sealed class RudpCultNetSchemaServer : IDisposable
public sealed class RudpCultNetSchemaServer : ICultNetSchemaServer, IDisposable
{
private readonly Socket _socket;
private readonly CultNetRudpSocketTransportServer _transport;
private readonly ConcurrentDictionary<Type, Delegate> _handlers = new();
private readonly ConcurrentDictionary<Delegate, Delegate> _schemaPeerAdapters = new();
private bool _disposed;
/// <summary>
@ -167,6 +168,41 @@ namespace GameCult.Networking
});
}
/// <inheritdoc />
public void OnCultNet<TMessage>(Func<TMessage, ICultNetSchemaServerPeer, Task> callback)
where TMessage : ICultNetSchemaMessage
{
if (callback == null) throw new ArgumentNullException(nameof(callback));
Func<TMessage, RudpCultNetSchemaServerPeer, Task> adapter = (message, peer) => callback(message, peer);
_schemaPeerAdapters[callback] = adapter;
OnCultNet(adapter);
}
/// <inheritdoc />
public void RemoveCultNetMessageListener<TMessage>(Delegate callback)
where TMessage : ICultNetSchemaMessage
{
if (_schemaPeerAdapters.TryRemove(callback, out var adapter))
{
callback = adapter;
}
if (!_handlers.TryGetValue(typeof(TMessage), out var current))
{
return;
}
var next = Delegate.Remove(current, callback);
if (next == null)
{
_handlers.TryRemove(typeof(TMessage), out _);
}
else
{
_handlers[typeof(TMessage)] = next;
}
}
/// <summary>
/// Sends a schema-v0 message to a transport peer.
/// </summary>

View file

@ -0,0 +1,35 @@
using System;
using System.Threading.Tasks;
namespace GameCult.Networking
{
/// <summary>
/// Transport-neutral schema-v0 peer surface for service bridges.
/// </summary>
public interface ICultNetSchemaServerPeer
{
/// <summary>
/// Sends a schema-v0 message to this peer.
/// </summary>
void SendCultNet<TMessage>(TMessage message)
where TMessage : ICultNetSchemaMessage;
}
/// <summary>
/// Transport-neutral schema-v0 server surface for service bridges.
/// </summary>
public interface ICultNetSchemaServer
{
/// <summary>
/// Registers a schema-v0 handler.
/// </summary>
void OnCultNet<TMessage>(Func<TMessage, ICultNetSchemaServerPeer, Task> callback)
where TMessage : ICultNetSchemaMessage;
/// <summary>
/// Removes a previously registered schema-v0 handler.
/// </summary>
void RemoveCultNetMessageListener<TMessage>(Delegate callback)
where TMessage : ICultNetSchemaMessage;
}
}

View file

@ -1,6 +1,10 @@
# GameCult.Networking
`GameCult.Networking` provides client/server messaging over LiteNetLib with encrypted credential exchange and signed session tokens.
`GameCult.Networking` provides CultNet: schema-aware client/server messaging,
database replication contracts, encrypted credential exchange, signed session
tokens, and reliable transport surfaces including CultLib's native
cross-runtime RUDP pipe. LiteNetLib remains supported as the C# production
adapter for legacy clients, but it is no longer the protocol boundary.
It is intended for game or game-service scenarios where you want a compact transport layer with a small set of built-in authentication flows rather than a full HTTP stack.
@ -12,8 +16,9 @@ just sample application messages riding that organ.
The library currently includes:
- a shared message contract model
- a client wrapper around LiteNetLib
- a server wrapper around LiteNetLib
- native RUDP packet/session contracts with reliable ordered schema frames
- client and server wrappers for the legacy LiteNetLib lane
- TCP-framed and WebSocket adapter surfaces used by non-C# runtimes
- encrypted login, register, and verify flows
- signed session-token generation and validation
- `PlayerData` integration with `CultCache`
@ -205,7 +210,7 @@ state.
The built-in flow is:
1. client connects with the shared LiteNetLib connection key
1. client connects through a configured CultNet transport profile
2. credentials are encrypted with AES-GCM using a per-message nonce
3. server validates credentials and issues a signed session token
4. client stores the encrypted session token and can send `VerifyMessage` on reconnect
@ -366,14 +371,14 @@ The client:
- automatically re-verifies using the stored signed session token
- exposes reconnect state for UI/operator surfaces
`Client.TransportProfile` and `Server.TransportProfile` describe the production
LiteNetLib lane as a `litenetlib` transport adapter with reliable ordered
`schema` and `legacy` channels. Discovery and operators can inspect the active
pipe without treating LiteNetLib as an implicit protocol truth. `NetPeer`
send helpers route through `LiteNetLibTransportConnection`, keeping outbound
schema and legacy messages behind that channel-aware adapter surface. Inbound
LiteNetLib payloads are classified through the same adapter before the client
or server dispatches schema-v0 or legacy messages.
`Client.TransportProfile` and `Server.TransportProfile` describe the active
transport as a profile with reliable ordered `schema` and, where needed,
`legacy` channels. The old C# path is now explicitly a `litenetlib` adapter,
not an implicit specification. Discovery and operators can inspect whether a
peer is using native RUDP, TCP-framed schema messages, WebSocket transport, or
LiteNetLib without changing the message contract above it. `NetPeer` send
helpers route through `LiteNetLibTransportConnection`, keeping legacy outbound
schema and union messages behind the same channel-aware adapter surface.
The native RUDP socket path also exposes `CultNetRudpReconnectLoop` for
caller-owned game or service loops. The caller reports closure, calls
@ -389,7 +394,8 @@ in `GameCult.Networking`.
- `Server` currently centers on `PlayerData` as the built-in account model.
- Message authorization is based on the built-in verify/login/register flow.
- Transport is LiteNetLib, so this is not a drop-in substitute for HTTP or WebSocket stacks.
- CultNet is not a drop-in substitute for HTTP. It is a schema-aware realtime
pipe for trusted game, mesh, and service runtimes.
Sensitive payload logging is gated. Raw message JSON should only appear when a
caller explicitly opts into diagnostic logging instead of accidentally bleeding

View file

@ -17,7 +17,7 @@ namespace GameCult.Networking
/// <summary>
/// Hosts the server-side authentication, session, and message dispatch pipeline.
/// </summary>
public class Server : IDisposable
public class Server : ICultNetSchemaServer, IDisposable
{
private const string EmailPattern =
@"^([0-9a-zA-Z]([\+\-_\.][0-9a-zA-Z]+)*)+@(([0-9a-zA-Z][-\w]*[0-9a-zA-Z]*\.)+[a-zA-Z0-9]{2,17})$";
@ -31,6 +31,7 @@ namespace GameCult.Networking
private readonly ConcurrentDictionary<Type, Delegate> _messageDelegates = new();
private readonly ConcurrentDictionary<Type, Delegate> _cultNetMessageDelegates = new();
private readonly ConcurrentDictionary<Type, Delegate> _cultNetServerPeerMessageDelegates = new();
private readonly ConcurrentDictionary<Delegate, Delegate> _cultNetSchemaPeerAdapters = new();
private readonly ConcurrentDictionary<long, User> _users = new();
private readonly ConcurrentDictionary<string, Queue<DateTimeOffset>> _connectionAttempts = new();
private readonly ConcurrentDictionary<string, object> _connectionAttemptLocks = new();
@ -225,6 +226,16 @@ namespace GameCult.Networking
AddCultNetMessageListener(callback);
}
/// <inheritdoc />
public void OnCultNet<T>(Func<T, ICultNetSchemaServerPeer, Task> callback)
where T : ICultNetSchemaMessage
{
if (callback == null) throw new ArgumentNullException(nameof(callback));
Func<T, CultNetServerPeer, Task> adapter = (message, peer) => callback(message, peer);
_cultNetSchemaPeerAdapters[callback] = adapter;
AddCultNetMessageListener(adapter);
}
/// <summary>
/// Sends a legacy GameCult.Networking union message through this server's per-peer LiteNetLib adapter.
/// </summary>
@ -282,6 +293,11 @@ namespace GameCult.Networking
/// </summary>
public void RemoveCultNetMessageListener<T>(Delegate callback) where T : ICultNetSchemaMessage
{
if (_cultNetSchemaPeerAdapters.TryRemove(callback, out var adapter))
{
callback = adapter;
}
if (_cultNetMessageDelegates.TryGetValue(typeof(T), out var currentDelegate))
{
var newDelegate = Delegate.Remove(currentDelegate, callback);
@ -799,7 +815,7 @@ namespace GameCult.Networking
/// <summary>
/// Transport-aware server peer context for built-in CultNet service bodies.
/// </summary>
public sealed class CultNetServerPeer
public sealed class CultNetServerPeer : ICultNetSchemaServerPeer
{
internal CultNetServerPeer(NetPeer peer, LiteNetLibTransportConnection transport)
{