Struct Codec
A wire codec, as an application names it in a projection, an event or a command. One value of the closed set of CodecKind, plus the parameters that kind reads.
public readonly struct Codec : IEquatable<Codec>
- Implements
- Inherited Members
Remarks
A declaration, not an encoder. Nothing here encodes anything: the value records what the field should look like on the wire, and the projection
compiler turns it into the specialized column loop that does the work. That is why the type is a small immutable value with no behaviour — it is copied
into a plan at Start and never touched again.
The parameters an application cannot know are left for the engine to fill. A position's bounds come from the spatial grid (ConfigureSpatialGrid(SpatialGridConfig)), and a velocity's width from the archetype's Teleport(double) speed and the runtime's tick ladder. Declaring them at the call site would be a second, drifting copy of a number the engine already owns.
Equality is by declaration, not by reference, so a test — or a catalog comparison — can assert that what came out of the registry is what went in. It compares the canonical text of ToString(), which allocates: compare codecs at registration, never per entity.
Fields
DefaultPositionBits
A realm's default position width: 24 bits per axis, sub-millimetre over a 16 km world and three bytes per axis. The width is the realm's
(REALM.posBits, 12-realms § 5.5), never a codec's.
public const int DefaultPositionBits = 24
Field Value
Properties
Bool
A boolean: always one bit of its section's implicit pack.
public static Codec Bool { get; }
Property Value
EntityRef
A netId reference to another entity, as varu; 0 is null. A client can only resolve one the server has shown it.
public static Codec EntityRef { get; }
Property Value
EnumName
The name of the enum whose value set this codec carries (W13), or null when it carries none.
public string EnumName { get; }
Property Value
Exact
The exact codec of whatever the field stores (13 § 2.1), resolved where the field's type is known: u64 for a ulong,
i64 for a long, f64 for a double, f32 × 3 for a Point3F, i32 for an
int, a pack of the narrowest width for an enum. "Exact" is one word whatever the type; a field that must be narrower declares the
lossy codec it wants instead.
public static Codec Exact { get; }
Property Value
F16
IEEE half. Saturates at 65 504 — a duration in milliseconds fits, the same duration in microseconds does not.
public static Codec F16 { get; }
Property Value
F32
IEEE single.
public static Codec F32 { get; }
Property Value
F64
IEEE double, little-endian (W32): a double sent whole.
public static Codec F64 { get; }
Property Value
I16
Signed 16-bit integer, little-endian.
public static Codec I16 { get; }
Property Value
I32
Signed 32-bit integer, little-endian.
public static Codec I32 { get; }
Property Value
I64
Signed 64-bit integer, little-endian two's complement (W32).
public static Codec I64 { get; }
Property Value
I8
Signed 8-bit integer.
public static Codec I8 { get; }
Property Value
IsDeclared
Whether this value names a codec at all. false for default(Codec).
public bool IsDeclared { get; }
Property Value
Pos2
A 2D world position, realm-framed (typhon.3, SUB-30): its width and bounds are the session's realm's, sent in the REALM block, so the
catalog carries the kind alone and a position declared here quantizes exactly as the grid's own.
public static Codec Pos2 { get; }
Property Value
Pos3
A 3D world position, realm-framed. typhon.3, SUB-30): its width and bounds are the session's realm's, sent in the REALM block, so the
catalog carries the kind alone and a position declared here quantizes exactly as the grid's own.
public static Codec Pos3 { get; }
Property Value
Quat3
A rotation, smallest-three in 32 bits.
public static Codec Quat3 { get; }
Property Value
Saturating
Whether a source value may be narrowed into this integer codec by clamping. Set only by Saturate(), and required of any field whose
integral source has a range the codec cannot hold — an int in a u8 as much as a long in a varu: the narrowing is never
implicit (design/Subscriptions/13 § 2.3).
public bool Saturating { get; }
Property Value
TickLo
An absolute past tick sent as its low 16 bits and rebuilt against the frame's tick.
public static Codec TickLo { get; }
Property Value
Token
The codec's wire token — u8, varu, bits, unorm … — as the catalog spells it. The empty string when
IsDeclared is false.
public string Token { get; }
Property Value
U16
Unsigned 16-bit integer, little-endian.
public static Codec U16 { get; }
Property Value
U32
Unsigned 32-bit integer, little-endian.
public static Codec U32 { get; }
Property Value
U64
Unsigned 64-bit integer, little-endian (W32): an id or a balance above 2³², exact on every client.
public static Codec U64 { get; }
Property Value
U8
Unsigned 8-bit integer.
public static Codec U8 { get; }
Property Value
VarInt
Zigzag-encoded signed LEB128 varint, 1–5 bytes.
public static Codec VarInt { get; }
Property Value
VarInt64
Zigzag-encoded signed LEB128 varint of a 64-bit value, 1–10 bytes (W32).
public static Codec VarInt64 { get; }
Property Value
VarUInt
Unsigned LEB128 varint, 1–5 bytes. The cheapest codec for a value that is usually small and occasionally large.
public static Codec VarUInt { get; }
Property Value
VarUInt64
Unsigned LEB128 varint of a 64-bit value, 1–10 bytes (W32): the cheapest exact codec for a 64-bit value that is usually small.
public static Codec VarUInt64 { get; }
Property Value
Vel2
The engine-measured 2D displacement of a motion segment. Its width and its divisor are derived at registration from the archetype's Teleport(double) speed and the runtime's largest allowed tick multiplier, so nothing here carries them.
public static Codec Vel2 { get; }
Property Value
Vel3
The engine-measured 3D displacement of a motion segment.
public static Codec Vel3 { get; }
Property Value
Width
Width in bits for the quantizing kinds; the bit count for Bits(int); 0 when the kind reads neither, or when the engine derives it.
public int Width { get; }
Property Value
Methods
Angle(int)
Radians in [−π, π) as a two's-complement code, so the wrap needs no special case on either side.
public static Codec Angle(int bits)
Parameters
bitsintWidth in bits: 8, 16, 24 or 32.
Returns
- Codec
The codec.
Bits(int)
An unsigned integer of n bits, carried in its section's implicit pack.
public static Codec Bits(int n)
Parameters
nintWidth in bits, in [1, 24].
Returns
- Codec
The codec.
Coll(int)
A ComponentCollection<T> field as a collection (W34): its first maxCount elements, each element field in its exact
codec, and the collection's real count — a longer one is cut and the client sees it was. The whole list travels when it changes.
public static Codec Coll(int maxCount)
Parameters
maxCountintThe most elements sent, 1 to 65 535. Required: a collection's bound is load-bearing and has no default.
Returns
- Codec
The codec; its element is filled from
T's fields where the field is declared.
Count(int)
This scalar codec repeated count times (W33): a point, a box, a sphere or a quaternion travels as its components, in its shape's
order. A shape field (Point3F, AABB2D…) gets its count from its type; declaring one is only needed to state it, and must agree.
public Codec Count(int count)
Parameters
countint2 to 16.
Returns
- Codec
The counted codec.
Enum<TEnum>(int)
An integer codec of bits bits carrying TEnum's value set as a catalog attribute. An enum is an integer plus a
list of names, never a codec of its own, so a client that does not know the names still decodes the number.
public static Codec Enum<TEnum>(int bits) where TEnum : struct, Enum
Parameters
bitsintWidth in bits, in [1, 24]. Wide enough for the whole value set — adding a name past that width re-lays the pack.
Returns
- Codec
The codec.
Type Parameters
TEnumThe enum whose names travel in the catalog.
Remarks
The width is checked here, at the declaring call, and not at the catalog. W13 lets a value past the end of the name list decode as a bare integer, so an under-wide field is not a decode failure on either side — it is a set of names the client silently never sees, discovered by a player rather than by a test. The count is a compile-time fact about the type; refusing it where the author wrote the number is the only place the message can name both.
Exceptions
- ArgumentOutOfRangeException
The enum has more names than
bitsbits can index: W13's|names| ≤ 2ⁿ.
Equals(object)
public override bool Equals(object obj)
Parameters
objobject
Returns
Equals(Codec)
Whether two codecs declare the same thing.
public bool Equals(Codec other)
Parameters
otherCodecThe other codec.
Returns
GetHashCode()
public override int GetHashCode()
Returns
Quant(double, double, int)
A scalar quantized over [min, max).
public static Codec Quant(double min, double max, int bits)
Parameters
mindoubleLower bound, inclusive.
maxdoubleUpper bound, exclusive. Must be above
min.bitsintWidth in bits: 8, 16, 24 or 32.
Returns
- Codec
The codec.
Saturate()
Marks this integer codec as the explicit narrowing of a wider source: out-of-range values clamp to the codec's range, and a projected field counts
every clamp. A field whose integral source the codec cannot hold — an int in a u8, a long in a varu — is refused
without it, because a silent truncation is a bug that only shows up once a value is large.
public Codec Saturate()
Returns
- Codec
The same codec, marked saturating.
Snorm(int)
A value in [−1, 1].
public static Codec Snorm(int bits)
Parameters
bitsintWidth in bits: 8, 16, 24 or 32.
Returns
- Codec
The codec.
Str(int)
UTF-8 text with a varu byte length.
public static Codec Str(int maxBytes)
Parameters
maxBytesintThe largest encoded length accepted, above zero.
Returns
- Codec
The codec.
ToString()
The codec's canonical text: its token, its parameters, its enum and its saturation — everything that distinguishes one declaration from another.
public override string ToString()
Returns
- string
The canonical text, or
"(none)"when nothing was declared.
Unorm(int)
A value in [0, 1] — a fraction, a ratio, a normalized health bar.
public static Codec Unorm(int bits)
Parameters
bitsintWidth in bits: 8, 16, 24 or 32.
Returns
- Codec
The codec.
Vec2(double, int)
A signed 2D vector in steps of scale. Unlike Vel2 this is an application quantity, so it carries its own scale.
public static Codec Vec2(double scale, int bits)
Parameters
Returns
- Codec
The codec.
Vec3(double, int)
A signed 3D vector in steps of scale.
public static Codec Vec3(double scale, int bits)
Parameters
Returns
- Codec
The codec.
Operators
operator ==(Codec, Codec)
Whether two codecs declare the same thing.
public static bool operator ==(Codec left, Codec right)
Parameters
Returns
operator !=(Codec, Codec)
Whether two codecs declare different things.
public static bool operator !=(Codec left, Codec right)