Skip to main content

Bufferize

Bufferize losslessly encodes and decodes Roblox data types into buffer objects.

The module exposes a default encoder via the top-level encode / decode functions, along with helpers for serializing instances and deduplicating repeated values inside a table. For per-type encoding overrides, create a dedicated Encoder with Bufferize.custom. 

local b = Bufferize.encode("Hello world!", 123, true, { foo = "bar" })
print(Bufferize.decode(b)) -- "Hello world!", 123, true, { foo = "bar" }

Properties​

VERSION​

Versioning
</>
Bufferize.VERSION: string

The semantic version string of the running Bufferize module. This is the same value that gets written into the header of every buffer produced by encode. See the versioning guide in the readme for compatibility rules.

Functions​

readVersion​

Versioning
</>
Bufferize.readVersion(
b: buffer--

A buffer previously produced by Bufferize.encode.

) → string?--

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

Inspects the version that was written into a buffer's header without attempting to decode the body. Useful for migration code that needs to branch on the producing version before decoding.

custom​

</>
Bufferize.custom() → Encoder--

A new encoder with no overrides registered.

Creates a new Encoder that you can configure with custom read/write functions for individual data types via Encoder:override. The returned encoder is independent of the module-level encode / decode functions — you must use the same encoder for both halves of a round-trip.

See custom encoding in the readme for examples.

deduplicateTypeof​

Deduplication
</>
Bufferize.deduplicateTypeof(
typeOfsSet: {[string]: boolean},--

Set of type names (e.g. "string", "CFrame") to consider for deduplication.

rootTbl: {[any]: any}--

The table to deduplicate.

) → {{[any]: any}}--

A { deduplicated, root } pair to pass to encode.

Scans rootTbl for keys and values whose typeof is in typeOfsSet and that appear more than once, and replaces each duplicate with a pointer to a single shared entry. Use this when you don't know up front which specific values are duplicated.

The returned table can be passed directly to Bufferize.encode. After decoding, use Bufferize.reduplicate to expand the pointers back into the original values.

See the deduplication guide for usage examples.

deduplicate​

Deduplication
</>
Bufferize.deduplicate(
supportedSet: {[any]: boolean},--

Set of exact values that should be deduplicated.

rootTbl: {[any]: any}--

The table to deduplicate.

) → {{[any]: any}}--

A { deduplicated, root } pair to pass to encode.

Replaces every occurrence of each value in supportedSet (as a key or as a value) with a pointer into a shared array of deduplicated values. Use this when you know exactly which values you want to collapse.

The returned table can be passed directly to Bufferize.encode. After decoding, use Bufferize.reduplicate to expand the pointers back into the original values.

reduplicate​

Deduplication
</>
Bufferize.reduplicate(
compressed: {{[any]: any}}--

A table previously produced by deduplicate / deduplicateTypeof, after a round-trip through encode / decode.

) → {[any]: any}--

The expanded table with deduplication pointers replaced by their original values.

Reverses Bufferize.deduplicate / Bufferize.deduplicateTypeof, producing a plain table you can use exactly as you would have used the input to the deduplication call.

serializeInstance​

Instances
</>
Bufferize.serializeInstance(
rootInstance: Instance--

The root of the instance tree to serialize.

) → {any}--

A plain table representation that can be passed to encode.

Walks rootInstance and all of its descendants and produces a table that captures each instance's ClassName, non-default writable properties, attributes, and tags. References between instances within the tree are preserved; references to instances outside the tree are dropped.

See the instances guide for the full set of rules and examples.

deserializeInstance​

Instances
</>
Bufferize.deserializeInstance(
serializedArr: {any}--

A table previously produced by serializeInstance, after a round-trip through encode / decode.

) → Instance--

The reconstructed root instance, with all descendants parented underneath.

Recreates the instance tree captured by Bufferize.serializeInstance. Properties, attributes, tags, and intra-tree references are restored on the new instances.

encode​

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

One or more values of supported data types.

) → buffer--

A buffer that round-trips through Bufferize.decode to the same values.

Encodes the given values into a buffer using the module-level default encoder. The buffer is prefixed with the running Bufferize version so that decode can refuse to read data produced by an incompatible version.

Tables are walked recursively; shared sub-tables are preserved as shared references in the decoded output.

decode​

</>
Bufferize.decode(
b: buffer--

A buffer previously produced by Bufferize.encode.

) → ...Supported--

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

Decodes a buffer produced by Bufferize.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": "readVersion",
            "desc": "Inspects the version that was written into a buffer's header without\nattempting to decode the body. Useful for migration code that needs to\nbranch on the producing version before decoding.",
            "params": [
                {
                    "name": "b",
                    "desc": "A buffer previously produced by `Bufferize.encode`.",
                    "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",
            "tags": [
                "Versioning"
            ],
            "source": {
                "line": 54,
                "path": "src/init.luau"
            }
        },
        {
            "name": "custom",
            "desc": "Creates a new [Encoder] that you can configure with custom read/write\nfunctions for individual data types via [Encoder:override]. The returned\nencoder is independent of the module-level `encode` / `decode` functions —\nyou must use the same encoder for both halves of a round-trip.\n\nSee custom encoding in the readme for examples.",
            "params": [],
            "returns": [
                {
                    "desc": "A new encoder with no overrides registered.",
                    "lua_type": "Encoder"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 68,
                "path": "src/init.luau"
            }
        },
        {
            "name": "deduplicateTypeof",
            "desc": "Scans `rootTbl` for keys and values whose `typeof` is in `typeOfsSet` and\nthat appear more than once, and replaces each duplicate with a pointer to a\nsingle shared entry. Use this when you don't know up front which specific\nvalues are duplicated.\n\nThe returned table can be passed directly to `Bufferize.encode`. After\ndecoding, use [Bufferize.reduplicate] to expand the pointers back into the\noriginal values.\n\nSee the [deduplication guide](/docs/deduplication) for usage examples.",
            "params": [
                {
                    "name": "typeOfsSet",
                    "desc": "Set of type names (e.g. `\"string\"`, `\"CFrame\"`) to consider for deduplication.",
                    "lua_type": "{ [string]: boolean }"
                },
                {
                    "name": "rootTbl",
                    "desc": "The table to deduplicate.",
                    "lua_type": "{ [any]: any }"
                }
            ],
            "returns": [
                {
                    "desc": "A `{ deduplicated, root }` pair to pass to `encode`.",
                    "lua_type": "{ { [any]: any } }"
                }
            ],
            "function_type": "static",
            "tags": [
                "Deduplication"
            ],
            "source": {
                "line": 89,
                "path": "src/init.luau"
            }
        },
        {
            "name": "deduplicate",
            "desc": "Replaces every occurrence of each value in `supportedSet` (as a key or as a\nvalue) with a pointer into a shared array of deduplicated values. Use this\nwhen you know exactly which values you want to collapse.\n\nThe returned table can be passed directly to `Bufferize.encode`. After\ndecoding, use [Bufferize.reduplicate] to expand the pointers back into the\noriginal values.",
            "params": [
                {
                    "name": "supportedSet",
                    "desc": "Set of exact values that should be deduplicated.",
                    "lua_type": "{ [any]: boolean }"
                },
                {
                    "name": "rootTbl",
                    "desc": "The table to deduplicate.",
                    "lua_type": "{ [any]: any }"
                }
            ],
            "returns": [
                {
                    "desc": "A `{ deduplicated, root }` pair to pass to `encode`.",
                    "lua_type": "{ { [any]: any } }"
                }
            ],
            "function_type": "static",
            "tags": [
                "Deduplication"
            ],
            "source": {
                "line": 107,
                "path": "src/init.luau"
            }
        },
        {
            "name": "reduplicate",
            "desc": "Reverses [Bufferize.deduplicate] / [Bufferize.deduplicateTypeof], producing\na plain table you can use exactly as you would have used the input to the\ndeduplication call.",
            "params": [
                {
                    "name": "compressed",
                    "desc": "A table previously produced by `deduplicate` / `deduplicateTypeof`, after a round-trip through `encode` / `decode`.",
                    "lua_type": "{ { [any]: any } }"
                }
            ],
            "returns": [
                {
                    "desc": "The expanded table with deduplication pointers replaced by their original values.",
                    "lua_type": "{ [any]: any }"
                }
            ],
            "function_type": "static",
            "tags": [
                "Deduplication"
            ],
            "source": {
                "line": 120,
                "path": "src/init.luau"
            }
        },
        {
            "name": "serializeInstance",
            "desc": "Walks `rootInstance` and all of its descendants and produces a table that\ncaptures each instance's `ClassName`, non-default writable properties,\nattributes, and tags. References between instances within the tree are\npreserved; references to instances outside the tree are dropped.\n\nSee the [instances guide](/docs/instances) for the full set of rules and\nexamples.",
            "params": [
                {
                    "name": "rootInstance",
                    "desc": "The root of the instance tree to serialize.",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "A plain table representation that can be passed to `encode`.",
                    "lua_type": "{ any }"
                }
            ],
            "function_type": "static",
            "tags": [
                "Instances"
            ],
            "source": {
                "line": 137,
                "path": "src/init.luau"
            }
        },
        {
            "name": "deserializeInstance",
            "desc": "Recreates the instance tree captured by [Bufferize.serializeInstance].\nProperties, attributes, tags, and intra-tree references are restored on the\nnew instances.",
            "params": [
                {
                    "name": "serializedArr",
                    "desc": "A table previously produced by `serializeInstance`, after a round-trip through `encode` / `decode`.",
                    "lua_type": "{ any }"
                }
            ],
            "returns": [
                {
                    "desc": "The reconstructed root instance, with all descendants parented underneath.",
                    "lua_type": "Instance"
                }
            ],
            "function_type": "static",
            "tags": [
                "Instances"
            ],
            "source": {
                "line": 150,
                "path": "src/init.luau"
            }
        },
        {
            "name": "encode",
            "desc": "Encodes the given values into a buffer using the module-level default\nencoder. The buffer is prefixed with the running Bufferize version so that\n`decode` can refuse to read data produced by an incompatible version.\n\nTables are walked recursively; shared sub-tables are preserved as shared\nreferences in the decoded output.",
            "params": [
                {
                    "name": "...",
                    "desc": "One or more values of supported data types.",
                    "lua_type": "Supported"
                }
            ],
            "returns": [
                {
                    "desc": "A buffer that round-trips through `Bufferize.decode` to the same values.",
                    "lua_type": "buffer"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 164,
                "path": "src/init.luau"
            }
        },
        {
            "name": "decode",
            "desc": "Decodes a buffer produced by `Bufferize.encode`. Raises an error if the\nbuffer was encoded with an incompatible major version, or with a newer\nversion of Bufferize than the one currently loaded.",
            "params": [
                {
                    "name": "b",
                    "desc": "A buffer previously produced by `Bufferize.encode`.",
                    "lua_type": "buffer"
                }
            ],
            "returns": [
                {
                    "desc": "The original values, in the same order they were passed to `encode`.",
                    "lua_type": "...Supported"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 177,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "VERSION",
            "desc": "The semantic version string of the running Bufferize module. This is the\nsame value that gets written into the header of every buffer produced by\n`encode`. See the versioning guide in the readme for compatibility\nrules.",
            "lua_type": "string",
            "tags": [
                "Versioning"
            ],
            "source": {
                "line": 41,
                "path": "src/init.luau"
            }
        }
    ],
    "types": [],
    "name": "Bufferize",
    "desc": "Bufferize losslessly encodes and decodes Roblox data types into\n[`buffer`](https://create.roblox.com/docs/reference/engine/libraries/buffer)\nobjects.\n\nThe module exposes a default encoder via the top-level `encode` / `decode`\nfunctions, along with helpers for serializing instances and deduplicating\nrepeated values inside a table. For per-type encoding overrides, create a\ndedicated [Encoder] with [Bufferize.custom].\n\n```lua\nlocal b = Bufferize.encode(\"Hello world!\", 123, true, { foo = \"bar\" })\nprint(Bufferize.decode(b)) -- \"Hello world!\", 123, true, { foo = \"bar\" }\n```",
    "source": {
        "line": 18,
        "path": "src/init.luau"
    }
}