Serialiser
API for serialising and deserialising schema-based data structures to and from Luau buffers.
Given a schema definition, the Serialiser API can automatically pack data structures into a compact binary format suitable for network transmission or storage, and unpack them back into usable data structures.
The API will error on any of the functions if the provided schema configuration is invalid, or if the data provided does not conform to the schema.
Functions
Serialiser.writeInPlace
Writes data into a buffer using the provided schema.
To determine the size of the buffer needed, you can use the Serialiser.measure function before calling this one.
Serialiser.writeInPlace(buffer: buffer, schema: Schema, data: any, bitOffset?: number): number
Parameters
| Name | Type | Default Value | Description |
|---|---|---|---|
| buffer | buffer | Required | The buffer to write the data into. |
| schema | Schema | Required | The schema defining the structure of the data. |
| data | any | Required | The data to be serialised according to the schema. |
| bitOffset | number? | 0 | The bit offset in the buffer to start writing at. |
Returns
| Name | Type | Description |
|---|---|---|
| newBitOffset | number | The new bit offset in the buffer after writing the data. |
Serialiser.write
Writes data into a new buffer using the provided schema and returns the buffer.
Serialiser.write(data: any, schema: Schema): buffer
Parameters
| Name | Type | Description |
|---|---|---|
| data | any | The data to be serialised according to the schema. |
| schema | Schema | The schema defining the structure of the data. |
Returns
| Name | Type | Description |
|---|---|---|
| buffer | buffer | The buffer containing the serialised data. |
Serialiser.read
Reads data from a buffer according to the given schema.
Serialiser.read(buffer: buffer, schema: Schema, bitOffset?: number): any
Parameters
| Name | Type | Default Value | Description |
|---|---|---|---|
| buffer | buffer | Required | The buffer to read the data from. |
| schema | Schema | Required | The schema defining the structure of the data. |
| bitOffset | number? | 0 | The bit offset in the buffer to start reading from. |
Returns
| Name | Type | Description |
|---|---|---|
| data | any | The data read from the buffer. |
Serialiser.measure
Measures the number of bits and bytes required to serialise the data using the provided schema.
Useful for determining the size of the buffer needed before performing the actual serialisation with Serialiser.write.
Changing bitOffset can also affect the measurement, as some schema types add padding to align to the nearest byte.
Serialiser.measure(data: any, schema: Schema, bitOffset?: number): number, number
Parameters
| Name | Type | Default Value | Description |
|---|---|---|---|
| data | any | Required | The data to be measured. |
| schema | Schema | Required | The schema defining the structure of the data. |
| bitOffset | number? | 0 | The bit offset to start measuring from. |
Returns
| Name | Type | Description |
|---|---|---|
| bitsNeeded | number | The number of bits needed to serialise the data. |
| bytesNeeded | number | The number of bytes needed to serialise the data. |
Serialiser.int
Creates an integer schema with optional min and max values. The range between min and max defines the number of bits needed to serialise the integer.
Serialiser.int(config?: IntSchemaConfig): Schema
Parameters
| Name | Type | Description |
|---|---|---|
| config | IntSchemaConfig? | The configuration for the integer schema. |
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The integer schema. |
Serialiser.bool
Creates a boolean schema.
Serialiser.bool(): Schema
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The boolean schema. |
Serialiser.string
Creates a string schema with an optional maximum length.
Serialiser.string(config?: StringSchemaConfig): Schema
Parameters
| Name | Type | Description |
|---|---|---|
| config | StringSchemaConfig? | The configuration for the string schema. |
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The string schema. |
Serialiser.float
Creates a 32-bit floating-point number schema.
Float serialisation uses IEEE 754 format and requires byte-alignment (padding bits are automatically added if necessary).
Serialiser.float(): Schema
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The float schema. |
Serialiser.double
Creates a 64-bit floating-point number schema.
Double serialisation uses IEEE 754 format and requires byte-alignment (padding bits are automatically added if necessary).
Serialiser.double(): Schema
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The double schema. |
Serialiser.quantizedFloat
Creates a quantized floating-point number schema.
Quantized floats map a continuous range to discrete integer steps, providing a space-efficient way to represent floating-point values with controlled precision. This is useful for network transmission where exact float precision is not required.
Serialiser.quantizedFloat(config: QuantizedFloatSchemaConfig): Schema
Parameters
| Name | Type | Description |
|---|---|---|
| config | QuantizedFloatSchemaConfig | The configuration for the quantized float schema. |
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The quantized float schema. |
Serialiser.vector3
Creates a Vector3 schema with configurable component serialisation.
Serialiser.vector3(config?: Vector3SchemaConfig): Schema
Parameters
| Name | Type | Description |
|---|---|---|
| config | Vector3SchemaConfig? | The configuration for the Vector3 schema. |
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The Vector3 schema. |
Serialiser.array
Creates an array schema with either a maximum variable length (given by config.maxLength) or a fixed length (given by config.fixedLength).
You must specify either maxLength or fixedLength, but not both.
Variable-length arrays require a few more bits to store the length, but allow for any number of elements up to the max.
Serialiser.array(config: ArraySchemaConfig): Schema
Parameters
| Name | Type | Description |
|---|---|---|
| config | ArraySchemaConfig | The configuration for the array schema. |
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The array schema. |
Serialiser.table
Creates an empty table schema.
Use Serialiser.withField to add fields to the table.
Serialiser.table(): Schema
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The table schema. |
Serialiser.withField
Adds a field to a table schema, mutating it in the process.
Fields are serialised and deserialised in the order they are added.
Serialiser.withField(schema: Schema, fieldName: string, fieldSchema: Schema): Schema
Parameters
| Name | Type | Description |
|---|---|---|
| schema | Schema | The table schema to add the field to. |
| fieldName | string | The name of the field. |
| fieldSchema | Schema | The schema for the field value. |
Returns
| Name | Type | Description |
|---|---|---|
| schema | Schema | The table schema that was passed in (for method chaining). |
Types
IntSchemaConfig
Schema configuration for serialising integers up to 32 bits in size.
Integers are encoded as a range to handle both signed and unsigned integers efficiently.
The min and max properties define the inclusive range of values that can be represented.
The default range can represent any 32-bit signed integer.
type IntSchemaConfig = { .min: number?, .max: number? }
Properties
| Field | Type | Default Value | Description |
|---|---|---|---|
| min | number? | -2147483648 | The minimum integer value (inclusive) that can be represented. |
| max | number? | 2147483647 | The maximum integer value (inclusive) that can be represented. |
StringSchemaConfig
Schema configuration for serialising strings.
Strings are encoded as a length prefix followed by individual character bytes (0-255).
type StringSchemaConfig = { .maxLength: number? }
Properties
| Field | Type | Default Value | Description |
|---|---|---|---|
| maxLength | number? | 65535 | The maximum length of the string. |
QuantizedFloatSchemaConfig
Schema configuration for serialising quantized floating-point numbers.
Quantized floats provide a space-efficient way to represent floating-point values
by mapping a continuous range [min, max] to a discrete number of integer steps.
The precision and size is determined by the number of steps: more steps = higher precision but more bits required.
type QuantizedFloatSchemaConfig = { .min: number, .max: number, .steps: number? }
Properties
| Field | Type | Default Value | Description |
|---|---|---|---|
| min | number | Required | The minimum value (inclusive) that can be represented. |
| max | number | Required | The maximum value (inclusive) that can be represented. |
| steps | number? | 65535 | The number of discrete steps to divide the range into. |
Vector3SchemaConfig
Schema configuration for serialising Vector3 values.
By default, each component (x, y, z) is serialised as a 32-bit float.
You can customize this by providing a different componentSchema (e.g., quantized floats for reduced bandwidth).
type Vector3SchemaConfig = { .componentSchema: Schema? }
Properties
| Field | Type | Default Value | Description |
|---|---|---|---|
| componentSchema | Schema? | Serialiser.float() | The schema to use for each component (x, y, z). |
ArraySchemaConfig
Schema configuration for serialising arrays.
Arrays can be either variable-length or fixed-length:
- Variable-length arrays (defined by
maxLength) store the actual length in the buffer, allowing arrays of different sizes up tomaxLength. - Fixed-length arrays (defined by
fixedLength) do not store length in the buffer, but require the array to always havefixedLengthelements.
You must provide either maxLength or fixedLength, but not both.
type ArraySchemaConfig = { .maxLength: number?, .fixedLength: number?, .elementSchema: Schema }
Properties
| Field | Type | Description |
|---|---|---|
| maxLength | number? | The maximum number of elements in a variable-length array. Cannot be used with fixedLength. |
| fixedLength | number? | The exact number of elements in a fixed-length array. Cannot be used with maxLength. |
| elementSchema | Schema | The schema for each element in the array. |