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)
{