Client SDKs
Three clients, one catalog: the browser's, .NET's and native code's, all decoding against what the server says rather than its C# types.
Status: โ Implemented ยท Visibility: Public ยท Level: ๐ต Core ยท Category: Subscriptions
๐ฏ What it solves
A client has to decode a compact, quantized, versioned stream, keep a mirror of what its session holds, draw movers smoothly between frames, and send commands in the server's encoding โ without being regenerated every time the server's types change.
โ๏ธ How it works (in brief)
TypeScript (@typhondb/client, src/Typhon.Client.TypeScript, ESM + .d.ts):
ReconnectingClient/Connectionโ the handshake, catalog caching by hash,PINGscheduling (PingScheduler), reconnection with backoff per close code.FrameApplierโ applies eachTICKinto aWorldStore: per-archetypeArchetypeStores of typed columns (field(name)), live slots, and per-frame entered/updated/left lists;SelfState, acks, events andAggregateGrids beside them.Clock+evaluateLive(store, renderTick, frac, out)โ render time and motion-segment extrapolation, including tick-period changes under overload.CommandQueue(one batch per rendered frame) andRegionSender(ClientRegionfootprints, โค 5 Hz).enqueueTyped(commands.MoveCmd, record)sends a command through its generated encoder: a misspelled field is a compile error, and a steady frame allocates nothing.GroupSubscriptionsโsubscribe(set, key)/unsubscribe(set, key)for an explicit group set, each a promise of its answer:pump(queue)before each flush,observe(applier)after each frame,reset()on close (groups).StreamRecorder/replayStreamโ record and replay a session.typhon-codegenโ one module from/typhon/catalog.json: specialised decoders for the hot path, a typed record and encoder per command (commands, checked against the session's catalog hash), the catalog'senums, and per archetype a class of typed column getters (CreatureColumns.of(world).hp).
.NET (Typhon.Client):
TyphonClientoverws://,wss://ortcp://: connect, reconnect policy, aWorldStorewith per-archetype columns andSelfState, aRecorder. Built for bots, tools, load tests and integration tests.- Commands:
Enqueue(in cmd)thenFlushCommandsAsync()once a frame โ the[ReplicatedMessage]struct of the shared contracts assembly, sent as itself. It is bound once per session against the negotiated catalog (a renamed, ignored or retyped field is aMessageBindingExceptionnaming every mismatch, before anything is sent) and allocates nothing per command.SendCommandAsync(name, values)remains for built-ins and commands with no contracts struct; analyzer TYPHON015 flags it where the struct is in reach. SubscribeAsync(set, key)/UnsubscribeAsync(set, key)โ a key of an explicit group set, settling with the server's answer (SubscribeResult); paced by the command's rate, sent again when the server still refuses it for the rate, dropped when the session ends.EventCollectorโ anIEventHandlerthat keeps each frame's events asReceivedEventvalues (fields by wire name); take them inFrameApplied. The way to receive events from code that cannot implementIFieldSink(its parameters arescoped), a Unity script among it.RoundTripโ the round trip measured fromPING/PONG(RttMs, a smoothed estimate;LastRttMs, the latest sample); the TypeScript SDK'sPingScheduler.rttMsand the C SDK'styphon_client_round_tripgive the same figure.FrameAppliedโ raised on the receive thread after eachTICKis applied whole (events and leaves included) and before the next: the window to copy the frame's change lists and columns out to a game or render thread, since the next frame clears and rewrites them.
C (src/Typhon.Client.Native, C++20 inside, a C ABI outside, no third-party dependency):
typhon_client_create/_start/_poll/_stopover TCP โ a columnar store read throughtyphon_archetype_view_getandtyphon_field_column, motion throughtyphon_motion_evaluate_live, commands throughtyphon_command_enqueue/typhon_commands_flush, groups throughtyphon_group_subscribeandtyphon_groups_get, events throughtyphon_event_*. Caller-owned buffers and opaque handles, so any language with an FFI binds the one header (typhon/client.h). TLS and WebSocket are not built (#1045).
๐ฆ Install
| SDK | Where | |
|---|---|---|
| .NET | NuGet | dotnet add package Typhon.Client --prerelease (net10.0, netstandard2.1 for Unity) โ and Typhon.Protocol alone for a contracts assembly shared with the server |
| TypeScript | npm | npm install @typhondb/client@alpha (ESM, Node โฅ 22 or a browser) |
| C | GitHub Releases | typhon-client-native-<version>-<platform> for linux-x64, windows-x64, macos-arm64: headers, a static and a shared library, and a CMake package โ find_package(TyphonClient), then link Typhon::typhon_client (static) or Typhon::typhon_client_shared |
Every package carries the server's version (one version for the engine and its clients); the alpha line is prerelease-only. The Packages page lists the server-side packages too.
๐ป Usage
const client = new ReconnectingClient({
url: 'wss://play.example.com/ws', kind: 'player', token, caps: Capabilities.Stats,
handlers: {
onWelcome: (session) => {
applier = new FrameApplier(session.plan, { clock });
queue = new CommandQueue({ plan: session.plan });
},
onTick: (message, recvMs) => applier.apply(message, recvMs),
},
});
await using var bot = new TyphonClient(new ClientOptions
{
Endpoint = new Uri("tcp://127.0.0.1:9100"),
Kind = "player",
});
await bot.ConnectAsync();
// MoveCmd: a [ReplicatedMessage] struct of the contracts assembly the server declared the command from.
bot.Enqueue(new MoveCmd { Forward = 1, Fx = 0f, Fz = -1f });
await bot.FlushCommandsAsync();
โ ๏ธ Guarantees & limits
- Golden vectors pin the wire: the engine, the .NET client, the TypeScript SDK and the C SDK decode the committed vectors identically, bit for bit.
- Forward compatible: a client skips blocks and fixed-size fields it does not know (AC-14).
- Interpolation helpers, identical in the three SDKs: an angle field interpolated through its wrap (
InterpolateAngle/interpolateAngle/typhon_interpolate_angle) and aquat3rotation by the shorter arc (InterpolateQuat3/interpolateQuat3/typhon_interpolate_quat3). Two golden vectors โ a recorded clock trace and the interpolation cases โ replay bit for bit in .NET, TypeScript and C. - Steady state: the TypeScript SDK shows no retained heap growth over a 10-minute replay; with code generation a steady-state frame of 10 k records decodes in โ 0.3 ms on the reference laptop.
- Packaging: each release's smoke tests install the packages from the release itself โ a server on
Typhon+Typhon.Subscriptions.AspNetCore, the .NET client over TCP, the TypeScript tarball over WebSocket, and the C package throughfind_package, static and shared. - Targets:
Typhon.ProtocolandTyphon.Clienttargetnet10.0andnetstandard2.1โ Unity 2021.2 and later. Thenetstandard2.1builds run the same tests, every golden vector among them, on CoreCLR; a run on Mono or IL2CPP is not yet proven, and WebGL has no sockets. A contracts assembly for Unity targetsnetstandard2.1and is built with the .NET SDK (its generator's output is C# 8);ClientOptionsis settable, since Unity's compiler has noinitsetters. The engine andTyphon.Subscriptions.AspNetCorearenet10.0only.
๐งช Tests
src/Typhon.Client.TypeScript/testโ vitest suites: framing, apply, motion, reconnect, codegen, golden streams- ClockTraceGoldenTests ยท InterpolationGoldenTests โ the clock and interpolation goldens shared by the three SDKs
- EngineStreamGoldenTests โ the .NET client against the engine's golden stream