Skip to main content

Encoder

An Encoder is an isolated encode/decode context. Each instance carries its own table of custom per-type encoders, so two encoders configured differently can co-exist without interfering with each other or with the module-level Bufferize.encode / Bufferize.decode functions.

Create one with Bufferize.custom:

local myEncoder = Bufferize.custom()
myEncoder:override("Color3", { read = ..., write = ... })

local b = myEncoder:encode(Color3.new(1, 0, 0))
local color = myEncoder:decode(b)

A buffer produced by an Encoder with overrides can only be decoded by an encoder configured with the same overrides — there is no way to recover the override information from the buffer alone.

Properties​

VERSION​

</>
Encoder.VERSION: string

The semantic version string of the running Bufferize module. Mirrors Bufferize.VERSION.

Functions​

new​

</>
Encoder.new() → Encoder

Creates a new encoder with no overrides registered. Prefer calling this via Bufferize.custom for clarity at the call site.

readVersion​

</>
Encoder.readVersion(
b: buffer--

A buffer previously produced by an encoder's encode method.

) → string?--

The semantic version string written into the header, or nil if it could not be parsed.

Reads the Bufferize version stored in the buffer's header without decoding the body. See Bufferize.readVersion.

override​

</>
Encoder:override(
typeOf: string,--

The typeof name of the data type to override (e.g. "CFrame", "Color3").

encoder: {
read: (buffer) → T,
write: (T) → buffer
}--

A pair of conversion functions between the data type and a buffer.

) → ()

Registers a custom read/write pair for the given data type on this encoder. The same override must be present on whichever encoder decodes the buffer later — there is no way to recover it from the buffer itself.

Attempting to override a type that is not overridable raises an error.

encode​

</>
Encoder:encode(
...: Supported--

One or more values of supported data types.

) → buffer--

A buffer that round-trips through this encoder's decode to the same values.

Encodes the given values into a buffer, applying any overrides registered via Encoder:override. The buffer is prefixed with the running Bufferize version.

decode​

</>
Encoder:decode(
b: buffer--

A buffer previously produced by this encoder (or one with the same overrides).

) → ...Supported--

The original values, in the same order they were passed to encode.

Decodes a buffer produced by encode. Raises an error if the buffer was encoded with an incompatible major version, or with a newer version of Bufferize than the one currently loaded.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a new encoder with no overrides registered. Prefer calling this via\n[Bufferize.custom] for clarity at the call site.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Encoder"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 230,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "readVersion",
            "desc": "Reads the Bufferize version stored in the buffer's header without decoding\nthe body. See [Bufferize.readVersion].",
            "params": [
                {
                    "name": "b",
                    "desc": "A buffer previously produced by an encoder's `encode` method.",
                    "lua_type": "buffer"
                }
            ],
            "returns": [
                {
                    "desc": "The semantic version string written into the header, or `nil` if it could not be parsed.",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 247,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "override",
            "desc": "Registers a custom read/write pair for the given data type on this encoder.\nThe same override must be present on whichever encoder decodes the buffer\nlater — there is no way to recover it from the buffer itself.\n\nAttempting to override a type that is not overridable raises an error.",
            "params": [
                {
                    "name": "typeOf",
                    "desc": "The `typeof` name of the data type to override (e.g. `\"CFrame\"`, `\"Color3\"`).",
                    "lua_type": "string"
                },
                {
                    "name": "encoder",
                    "desc": "A pair of conversion functions between the data type and a `buffer`.",
                    "lua_type": "{ read: (buffer) -> T, write: (T) -> buffer }"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 267,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "encode",
            "desc": "Encodes the given values into a buffer, applying any overrides registered\nvia [Encoder:override]. The buffer is prefixed with the running Bufferize\nversion.",
            "params": [
                {
                    "name": "...",
                    "desc": "One or more values of supported data types.",
                    "lua_type": "Supported"
                }
            ],
            "returns": [
                {
                    "desc": "A buffer that round-trips through this encoder's `decode` to the same values.",
                    "lua_type": "buffer"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 285,
                "path": "src/Encoder.luau"
            }
        },
        {
            "name": "decode",
            "desc": "Decodes a buffer produced by `encode`. Raises an error if the buffer was\nencoded with an incompatible major version, or with a newer version of\nBufferize than the one currently loaded.",
            "params": [
                {
                    "name": "b",
                    "desc": "A buffer previously produced by this encoder (or one with the same overrides).",
                    "lua_type": "buffer"
                }
            ],
            "returns": [
                {
                    "desc": "The original values, in the same order they were passed to `encode`.",
                    "lua_type": "...Supported"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 316,
                "path": "src/Encoder.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "VERSION",
            "desc": "The semantic version string of the running Bufferize module. Mirrors\n[Bufferize.VERSION].",
            "lua_type": "string",
            "source": {
                "line": 209,
                "path": "src/Encoder.luau"
            }
        }
    ],
    "types": [],
    "name": "Encoder",
    "desc": "An `Encoder` is an isolated encode/decode context. Each instance carries\nits own table of custom per-type encoders, so two encoders configured\ndifferently can co-exist without interfering with each other or with the\nmodule-level [Bufferize.encode] / [Bufferize.decode] functions.\n\nCreate one with [Bufferize.custom]\\:\n\n```lua\nlocal myEncoder = Bufferize.custom()\nmyEncoder:override(\"Color3\", { read = ..., write = ... })\n\nlocal b = myEncoder:encode(Color3.new(1, 0, 0))\nlocal color = myEncoder:decode(b)\n```\n\nA buffer produced by an `Encoder` with overrides can only be decoded by an\nencoder configured with the same overrides — there is no way to recover the\noverride information from the buffer alone.",
    "source": {
        "line": 200,
        "path": "src/Encoder.luau"
    }
}