From d85f3fd32aef351a7a18d67db67a2962dd157049 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 21 Jun 2026 16:31:50 +0100 Subject: [PATCH] Document CultLib substrate and schema server port --- README.md | 36 +++++++++++++---- packages/cultnet-rs/src/rudp.rs | 14 +++++++ packages/cultnet-rs/tests/cultnet.rs | 6 +++ src/GameCult.Mesh/README.md | 4 +- .../CultNetRudpSchemaServer.cs | 40 ++++++++++++++++++- .../CultNetSchemaServerPort.cs | 35 ++++++++++++++++ src/GameCult.Networking/README.md | 32 +++++++++------ src/GameCult.Networking/Server.cs | 20 +++++++++- 8 files changed, 161 insertions(+), 26 deletions(-) create mode 100644 src/GameCult.Networking/CultNetSchemaServerPort.cs diff --git a/README.md b/README.md index 64109922..99fcb562 100644 --- a/README.md +++ b/README.md @@ -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` diff --git a/packages/cultnet-rs/src/rudp.rs b/packages/cultnet-rs/src/rudp.rs index 94f77e20..8566c38c 100644 --- a/packages/cultnet-rs/src/rudp.rs +++ b/packages/cultnet-rs/src/rudp.rs @@ -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, diff --git a/packages/cultnet-rs/tests/cultnet.rs b/packages/cultnet-rs/tests/cultnet.rs index 3365cb13..2803db51 100644 --- a/packages/cultnet-rs/tests/cultnet.rs +++ b/packages/cultnet-rs/tests/cultnet.rs @@ -377,6 +377,12 @@ fn rudp_transport_profile_advertises_state_and_realtime_channels() { CultNetTransportOrdering::Unordered, Some(64) ), + ( + "media", + CultNetTransportDelivery::Reliable, + CultNetTransportOrdering::Unordered, + Some(64) + ), ] ); } diff --git a/src/GameCult.Mesh/README.md b/src/GameCult.Mesh/README.md index 6b1a4f31..5bd3b1a0 100644 --- a/src/GameCult.Mesh/README.md +++ b/src/GameCult.Mesh/README.md @@ -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 diff --git a/src/GameCult.Networking/CultNetRudpSchemaServer.cs b/src/GameCult.Networking/CultNetRudpSchemaServer.cs index cc867eba..6021dced 100644 --- a/src/GameCult.Networking/CultNetRudpSchemaServer.cs +++ b/src/GameCult.Networking/CultNetRudpSchemaServer.cs @@ -52,7 +52,7 @@ namespace GameCult.Networking /// /// Peer context for a schema-v0 RUDP server. /// - public sealed class RudpCultNetSchemaServerPeer + public sealed class RudpCultNetSchemaServerPeer : ICultNetSchemaServerPeer { private readonly RudpCultNetSchemaServer _server; @@ -86,11 +86,12 @@ namespace GameCult.Networking /// /// Multi-peer schema-v0 host over the native CultNet RUDP transport. /// - public sealed class RudpCultNetSchemaServer : IDisposable + public sealed class RudpCultNetSchemaServer : ICultNetSchemaServer, IDisposable { private readonly Socket _socket; private readonly CultNetRudpSocketTransportServer _transport; private readonly ConcurrentDictionary _handlers = new(); + private readonly ConcurrentDictionary _schemaPeerAdapters = new(); private bool _disposed; /// @@ -167,6 +168,41 @@ namespace GameCult.Networking }); } + /// + public void OnCultNet(Func callback) + where TMessage : ICultNetSchemaMessage + { + if (callback == null) throw new ArgumentNullException(nameof(callback)); + Func adapter = (message, peer) => callback(message, peer); + _schemaPeerAdapters[callback] = adapter; + OnCultNet(adapter); + } + + /// + public void RemoveCultNetMessageListener(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; + } + } + /// /// Sends a schema-v0 message to a transport peer. /// diff --git a/src/GameCult.Networking/CultNetSchemaServerPort.cs b/src/GameCult.Networking/CultNetSchemaServerPort.cs new file mode 100644 index 00000000..58ab2fdc --- /dev/null +++ b/src/GameCult.Networking/CultNetSchemaServerPort.cs @@ -0,0 +1,35 @@ +using System; +using System.Threading.Tasks; + +namespace GameCult.Networking +{ + /// + /// Transport-neutral schema-v0 peer surface for service bridges. + /// + public interface ICultNetSchemaServerPeer + { + /// + /// Sends a schema-v0 message to this peer. + /// + void SendCultNet(TMessage message) + where TMessage : ICultNetSchemaMessage; + } + + /// + /// Transport-neutral schema-v0 server surface for service bridges. + /// + public interface ICultNetSchemaServer + { + /// + /// Registers a schema-v0 handler. + /// + void OnCultNet(Func callback) + where TMessage : ICultNetSchemaMessage; + + /// + /// Removes a previously registered schema-v0 handler. + /// + void RemoveCultNetMessageListener(Delegate callback) + where TMessage : ICultNetSchemaMessage; + } +} diff --git a/src/GameCult.Networking/README.md b/src/GameCult.Networking/README.md index bb5cedd0..c7c4792f 100644 --- a/src/GameCult.Networking/README.md +++ b/src/GameCult.Networking/README.md @@ -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 diff --git a/src/GameCult.Networking/Server.cs b/src/GameCult.Networking/Server.cs index a6234301..4400c95d 100644 --- a/src/GameCult.Networking/Server.cs +++ b/src/GameCult.Networking/Server.cs @@ -17,7 +17,7 @@ namespace GameCult.Networking /// /// Hosts the server-side authentication, session, and message dispatch pipeline. /// - 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 _messageDelegates = new(); private readonly ConcurrentDictionary _cultNetMessageDelegates = new(); private readonly ConcurrentDictionary _cultNetServerPeerMessageDelegates = new(); + private readonly ConcurrentDictionary _cultNetSchemaPeerAdapters = new(); private readonly ConcurrentDictionary _users = new(); private readonly ConcurrentDictionary> _connectionAttempts = new(); private readonly ConcurrentDictionary _connectionAttemptLocks = new(); @@ -225,6 +226,16 @@ namespace GameCult.Networking AddCultNetMessageListener(callback); } + /// + public void OnCultNet(Func callback) + where T : ICultNetSchemaMessage + { + if (callback == null) throw new ArgumentNullException(nameof(callback)); + Func adapter = (message, peer) => callback(message, peer); + _cultNetSchemaPeerAdapters[callback] = adapter; + AddCultNetMessageListener(adapter); + } + /// /// Sends a legacy GameCult.Networking union message through this server's per-peer LiteNetLib adapter. /// @@ -282,6 +293,11 @@ namespace GameCult.Networking /// public void RemoveCultNetMessageListener(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 /// /// Transport-aware server peer context for built-in CultNet service bodies. /// - public sealed class CultNetServerPeer + public sealed class CultNetServerPeer : ICultNetSchemaServerPeer { internal CultNetServerPeer(NetPeer peer, LiteNetLibTransportConnection transport) {