Table of Contents

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, PING scheduling (PingScheduler), reconnection with backoff per close code.
  • FrameApplier โ€” applies each TICK into a WorldStore: per-archetype ArchetypeStores of typed columns (field(name)), live slots, and per-frame entered/updated/left lists; SelfState, acks, events and AggregateGrids 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) and RegionSender (ClientRegion footprints, โ‰ค 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's enums, and per archetype a class of typed column getters (CreatureColumns.of(world).hp).

.NET (Typhon.Client):

  • TyphonClient over ws://, wss:// or tcp://: connect, reconnect policy, a WorldStore with per-archetype columns and SelfState, a Recorder. Built for bots, tools, load tests and integration tests.
  • Commands: Enqueue(in cmd) then FlushCommandsAsync() 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 a MessageBindingException naming 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 โ€” an IEventHandler that keeps each frame's events as ReceivedEvent values (fields by wire name); take them in FrameApplied. The way to receive events from code that cannot implement IFieldSink (its parameters are scoped), a Unity script among it.
  • RoundTrip โ€” the round trip measured from PING/PONG (RttMs, a smoothed estimate; LastRttMs, the latest sample); the TypeScript SDK's PingScheduler.rttMs and the C SDK's typhon_client_round_trip give the same figure.
  • FrameApplied โ€” raised on the receive thread after each TICK is 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 / _stop over TCP โ€” a columnar store read through typhon_archetype_view_get and typhon_field_column, motion through typhon_motion_evaluate_live, commands through typhon_command_enqueue / typhon_commands_flush, groups through typhon_group_subscribe and typhon_groups_get, events through typhon_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 a quat3 rotation 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 through find_package, static and shared.
  • Targets: Typhon.Protocol and Typhon.Client target net10.0 and netstandard2.1 โ€” Unity 2021.2 and later. The netstandard2.1 builds 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 targets netstandard2.1 and is built with the .NET SDK (its generator's output is C# 8); ClientOptions is settable, since Unity's compiler has no init setters. The engine and Typhon.Subscriptions.AspNetCore are net10.0 only.

๐Ÿงช Tests