Document CultLib substrate and schema server port
This commit is contained in:
parent
f06914d7c5
commit
d85f3fd32a
8 changed files with 161 additions and 26 deletions
36
README.md
36
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`
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -377,6 +377,12 @@ fn rudp_transport_profile_advertises_state_and_realtime_channels() {
|
|||
CultNetTransportOrdering::Unordered,
|
||||
Some(64)
|
||||
),
|
||||
(
|
||||
"media",
|
||||
CultNetTransportDelivery::Reliable,
|
||||
CultNetTransportOrdering::Unordered,
|
||||
Some(64)
|
||||
),
|
||||
]
|
||||
);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
35
src/GameCult.Networking/CultNetSchemaServerPort.cs
Normal file
35
src/GameCult.Networking/CultNetSchemaServerPort.cs
Normal 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;
|
||||
}
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in a new issue