Namespace Typhon.Protocol
Classes
- AckReasons
Reason codes of an
ACKSrejection record. Codes 128–255 belong to the application.
- ArchetypePlan
An archetype compiled for encoding and decoding its records.
- BlockTypes
The block types inside a
TICK(03-wire-protocol § 3). An unknown type is skipped by its length.
- BuiltInCommands
The commands the engine itself understands (W27, W28). They sit in the catalog beside the application's, at reserved indices that never move.
- BuiltInEvents
The events the engine declares itself, at reserved indices 0–15 (W27): today one, EventsLost.
- BuiltInMetrics
The metrics every Typhon server can publish (W25), at reserved indices 0–31 under the reserved
typhon.prefix. Durations travel in milliseconds asf16: microseconds would overflow a half at 65 ms.
- Catalog
Everything a client needs to decode a Typhon stream without any generated code or knowledge of the server's C# types: which archetypes are replicated, which fields each carries, in what codec and group, plus events, commands, grids and metrics.
- CatalogApp
Which application this catalog describes, so a client can tell one server's contract from another's.
- CatalogArchetype
One replicated archetype: the entities of this type a session can see, and what it receives for them.
- CatalogCodec
A codec: a CodecKind and the parameters that kind reads. Parameters a kind does not read stay at their default and are not written.
- CatalogCommand
A typed command a client may send. Commands enter the tick and are validated by ordinary application systems; a client never transacts directly.
- CatalogCommandRate
The rate a client may send one command type at: a token bucket, refilled per second, with a burst ceiling.
- CatalogElement
A collection's element (W34): fields with a name, a codec, and optionally an enum and a shape — never a group, an onEnter flag, or a nested collection. In wire order once canonical: packed fields first, then by ordinal name, as a message's fields are.
- CatalogEvent
An event the server may send: a fact about something that happened, routed to the sessions that should learn of it.
- CatalogException
Thrown when a catalog breaks a rule of 03-wire-protocol. The message lists every problem found, not only the first.
- CatalogExport
A catalog ready to serve: its canonical form, the bytes
WELCOMEcarries, and their digest, produced together.
- CatalogField
One replicated field: its wire name, its codec, and either the change group it belongs to or the fact that it travels on enter only.
- CatalogGrid
A spatial grid a client can reason about: the cell geometry behind aggregate tiers and region requests.
- CatalogGroupSet
A group set (14 § 3.5): entities sharing a key, held whole — a session that holds a group holds every current member, and is told when it does.
- CatalogLimits
Server-wide ceilings a client acts on (W30). Everything else the server enforces stays out of the catalog.
- CatalogMetric
A metric the server publishes in its
STATSblock (W25).
- CatalogOwner
The owner-only part of an archetype (W17): values only the controlling session receives, in
SELF, with their own groups and bit space.
- CatalogPlan
A canonical catalog compiled into the plans both directions work from: the server's encoder, a client's decoder and the golden-vector generator.
- CatalogPosition
An archetype's position on the wire (W15, W16): what an enter record starts with and what a motion segment carries. Absent when the archetype is not spatial.
- CatalogProtocolVersion
The wire protocol version. Negotiated separately from the package version: a client and server agree on this, not on a NuGet number.
- CatalogSerializer
Turns a Catalog into the canonical bytes that travel in
WELCOME, into the digest a returning client offers back to skip them, and back from bytes into a catalog.
- CatalogTick
Tick timing a client needs before it receives its first frame.
- CatalogValidator
Checks a catalog against the registration rules of 03-wire-protocol § 12 before anything is encoded or decoded against it.
- CloseCodes
Close codes, with the meanings RFC 6455 gives them, plus the engine's private-use range (W24). A
KICKcarries one of these; on WebSocket the same number closes the connection.
- CodecAttribute
A message field's codec, named by kind.
- CodecDeclarationAttribute
The codec of a replicated field, named rather than defaulted from its type; the numeric properties parameterize it.
- CodecTokens
The wire tokens of CodecKind, in both directions.
- CommandsMessage
COMMANDS(0x83):u32 clientTick | varu count ≥ 1 | (varu cmdTypeIdx | u16 seq | fields)*, the client's batch for one rendered frame.
- ControlMessage
Reads whole control messages.
- DebugSubTypes
The sub-block types inside a
DEBUGblock (03-wire-protocol § 3, W26). An unknown one is skipped by its length.
- EnterRecord
An enter record to encode.
- EntityRefAttribute
A message field naming an entity: a netId on the wire.
- FieldCodec
Encodes and decodes one section of fields — a record body, an event or command payload — per 03-wire-protocol § 5 and decisions W11–W13: the leading bit pack, then each byte-aligned field in wire order.
- FieldPlan
One field compiled for encoding and decoding: its codec's parameters resolved into the numbers the arithmetic needs, and its place in its section.
- FieldValue
A value to encode. Numbers carry the components of a numeric field, or the flattened elements of a list; Integers the components of a 64-bit integer field; Text and Bytes carry the rest.
- FractionAttribute
A component field sent as a fraction of another (
.Fraction(comp, value, max, bits, name, group)): health of max health.
- HeadingAttribute
A component field that is a heading, sent when it turns past a tolerance (
.Heading(comp, selector, bits, toleranceDeg, name)).
- HelloMessage
HELLO(0x81): the client's first message, at most HelloMaxBytes.
- MessagePlan
An event or command type compiled: its index and its single body section.
- MessageTypes
The first byte of every message (03-wire-protocol § 3). Client-to-server types have the high bit set.
- MetricPlan
A metric compiled: its codec and how many values it contributes to its
STATSsegment.
- MotionAttribute
On an archetype's
Comp<T>field: the component whose spatial field moves the entity, replicated as motion segments (.Motion(comp, …)). Per archetype, because a spaceship and a walking NPC do not deserve the same tolerance.
- OnEnterAttribute
A component field sent only in enter records (
.OnEnter(comp, selector, codec, name)).
- OwnerAttribute
A component field only its controlling session sees, in
SELF(.Owner(o => o.Field(…)), W17).
- PositionAttribute
On an archetype's
Comp<T>field: the component whose spatial field is the entity's position, sent on enter (.Position(comp)).
- PositionPlan
An archetype's position, compiled.
- ProtocolConstants
Values fixed by the protocol major, which a client needs before it has received any catalog (03-wire-protocol § 2, decision W22).
- PushGeometry
A
DEBUGPUSH_GEOMETRYsub-block (09 § 15): what the session holds as of the frame carrying it — its anchor or hull, its delivered cells, its LOD level. Sent to a debugging session whenever it changes. In the experimental range: its layout can change without a protocol version.
- QuantAttribute
A message field quantized over [min, max) at a given number of bits.
- RealmFrame
The realm a session's positions are framed in (
typhon.3, 12-realms § 5.2): what theREALMblock carries, and what every realm-framed codec —pos2,pos3, theAGGgrid — is quantized over and decoded with (SUB-30).
- RecordValues
A value source for encoding a record: a field's value by its wire name.
- ReplicateAttribute
A component field that travels in a change group (
.Field(comp, selector, codec, name, group)).
- ReplicatedAttribute
Opts an archetype into replication by attributes (11 § 5.4): its components' ReplicateAttribute, OnEnterAttribute, OwnerAttribute, FractionAttribute and HeadingAttribute fields, and its MotionAttribute or PositionAttribute component, become its projection. Without it no attribute of its components replicates it — a component shared with another archetype does not replicate that one silently. A builder
subs.Archetype<T>(…)call replaces the attributes entirely.
- ReplicatedMessageAttribute
On a command struct or an event record: its fields' codecs come from their CodecAttribute, QuantAttribute and EntityRefAttribute attributes, compiled by the generator into a descriptor the engine's builders read (11 § 5.3) — engine-free, so a contracts assembly shared with clients can carry it. The message's policy (rate, coalescing, routing) stays in its builder call.
- SectionPlan
A section compiled for encoding: its fields in wire order (packed first) and the size of its leading pack.
- SegmentRecord
A motion segment to encode.
- SourceErrorCodes
The codes a
SOURCE_ERRORcarries (14 § 4): the engine's below FirstApplicationCode, the application's from it. 0 is no code.
- SourceStatus
A
SOURCESrecord's kind (03 § 3, amended by Phase 4's 14 § 3.5): every record leads with it. The first two are a request's outcome — and keep the names they had as a status — the next two a group's lifecycle, the last a Region set's truncation.
- StateRecord
A state record to encode: the groups in GroupMask, with the values of their fields.
- TickReader
Decodes a
TICKmessage into an ITickSink: the header, then every block, each isolated by its length so a block can neither read past its end nor leave bytes unread.
- TickWriter
Encodes a
TICKmessage block by block. The object model here is the reference encoder the golden vectors are generated with; the engine's own encoder writes the same bytes straight from cluster data.
- WelcomeMessage
WELCOME(0x01): the server's reply toHELLO.
- WireFormatException
Thrown when bytes received from the other side do not form a valid message. It carries the close code the connection is closed with, so the transport never has to classify a decoding failure itself.
- WireMath
The codec arithmetic of 03-wire-protocol § 12 (decisions W1–W10): quantization, normalized values, angles, smallest-three quaternions, half floats and low-bit ticks, written so that C#, the TypeScript SDK and the engine produce bit-identical integer codes and bit-identical decoded doubles.
Structs
- ByeMessage
BYE(0x85): a clean leave, with 1000 or a code in 4000–4999 — the codes a browser'sclose()accepts.
- CanonicalHashBuilder
The FNV-1a 64 construction this repository uses for content fingerprints: UTF-8 bytes, fixed-width little-endian integers, and an explicit end-of-entry separator, folded over entries the caller has already sorted.
- DebugGrid
A
DEBUGGRIDsub-block (09 § 15): the replication grid every push session's cells are keyed on. Sent to a debugging session with its first frame and with everyRESET.
- KickMessage
KICK(0x04): the session is closed with Code; the reason is at most 123 UTF-8 bytes (W24).
- MessageFieldDeclaration
One message field's codec as its attributes declare it: what the generator compiles a ReplicatedMessageAttribute type's CodecAttribute, QuantAttribute and EntityRefAttribute fields into. Engine-free, so a contracts assembly that references only this one carries it; the engine turns it into a codec through the same factories a builder call uses, so it is validated the same.
- PingMessage
PING(0x84): mandatory at the catalog'spingHz; its LastAppliedTick drives the server's lag skip.
- PongMessage
PONG(0x03): the reply toPING, with how far the server is into its tick (W31:u32, a tick exceeds 65 535 µs).
- Utf8Buffer256
The 256-byte inline buffer of a Utf8Text256.
- Utf8Text256
A UTF-8 string of at most 256 bytes, carried inside a message struct. See IInlineUtf8Text.
- WireReader
Reads the wire's primitives (03-wire-protocol § 2) from a span: little-endian fixed-width integers, LEB128 varints, half and single floats, and length-prefixed strings and blobs.
- WireWriter
Writes the wire's primitives (03-wire-protocol § 2) into a caller-owned span.
Interfaces
- ICommandSink
Receives a decoded
COMMANDSmessage: each command's header, then its fields through the IFieldSink members.
- IFieldSink
Receives the values of a decoded section, one call per field, in wire order. Implemented as a
structby a zero-allocation decoder, so the generic call is specialized and inlined.
- IInlineUtf8Text
A fixed-capacity UTF-8 string that lives inside a message struct: what lets an event or a command carry a
str.
- IReplicatedMessage
Implemented by the generator on every ReplicatedMessageAttribute type: its attributed fields. The engine's command and event builders read it once, at declaration — a field declared in the builder call still wins, and one with no attribute takes its type's default.
- ITickSink
Receives a decoded
TICK, block by block, in stream order — the blocks Read<TSink>(ReadOnlySpan<byte>, CatalogPlan, ref RealmFrame, ref TSink, TickBlocks) was asked for. Field values arrive through the IFieldSink members between the record call that opened them and the next record call.
Enums
- Capabilities
The
capsbits (W23): only server work a client may decline. Bits 2–31 are reserved, sent as 0 and ignored.
- CodecKind
The closed set of wire codecs (03-wire-protocol § 4). A client refuses at
WELCOMEa codec it does not know, unless the field declares FixedBytes and can therefore be skipped.
- FieldValueKind
What a decoded field value is made of.
- PushGeometryFlags
The flags of a PushGeometry.
- PushShape
The shape of a push session's geometry.
- TickBlocks
Which blocks of a
TICKa TickReader hands to its sink.
- TickFlags
The
TICKflags byte, bits in the order § 3 lists them.
Delegates
- ControlMessage.BodyReader<T>
Reads a message body.