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
Bits per axis of a Pos2 or Pos3: 24, which is sub-millimetre over a 16 km world and still three bytes per axis. It is a property of the codec, not of any world — a smaller world gets finer steps from the same 24 bits, it does not want fewer of them.
public const int DefaultPositionBits = 24Field Value
Properties
Bool
A boolean: always one bit of its section's implicit pack.
public static Codec Bool { get; }Property Value
Element
The element codec of a list, or default when this is not a list.
public Codec Element { 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
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
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
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 at DefaultPositionBits bits per axis. The bounds are the spatial grid's and are filled in at Start: a
position declared here and a position the grid quantizes must be the same number or the client's world is not the server's.
public static Codec Pos2 { get; }Property Value
Pos3
A 3D world position at DefaultPositionBits bits per axis. Start: a
position declared here and a position the grid quantizes must be the same number or the client's world is not the server's.
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 64-bit source value may be narrowed into this codec by clamping. Set only by Saturate(), and required of any projected field whose source is a long or a ulong — no 64-bit integer reaches the wire, and the narrowing is never implicit.
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
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
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
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.
Blob(int)
Raw bytes with a varu length.
public static Codec Blob(int maxBytes)Parameters
maxBytesintThe largest encoded length accepted, above zero.
Returns
- Codec
The codec.
Bytes(int)
Exactly n raw bytes, with no length on the wire.
public static Codec Bytes(int n)Parameters
nintThe byte count, above zero.
Returns
- Codec
The 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, EnumParameters
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
List(Codec, int, int)
A counted sequence of of: a varu count, then that many elements.
public static Codec List(Codec of, int minCount, int maxCount)Parameters
ofCodecThe element codec.
minCountintThe fewest elements accepted.
maxCountintThe most elements accepted, at most 255.
Returns
- Codec
The codec.
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 64-bit source value: out-of-range values clamp and the clamp is counted. A projected field whose source is a long or a ulong is refused without it, because a silent truncation of a credit balance is a bug that only shows up once someone is rich.
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)