Compress

Getting it

local Compress = Engine:GetPackage("Compress")

Overview

Compress works on buffer values, which pairs well with Serde: serialize with Serde, then compress the result. Each codec is a small table with Encode and Decode (or Apply).

local Compress = Engine:GetPackage("Compress")
local Serde = Engine:GetPackage("Serde")

local raw = Serde.Dynamic():Encode(bigTable)
local packed = Compress.Auto.Encode(raw)        -- picks the smallest result
local text = Compress.Base91.Encode(packed)     -- safe to store as a string

local restored = Serde.Dynamic():Decode(Compress.Auto.Decode(Compress.Base91.Decode(text)))

Auto

Compress.Auto.Encode(buf: buffer, maxChainLength: number?): buffer
Compress.Auto.Decode(buf: buffer): buffer

Tries RLE and LZ and keeps whichever is smallest, or stores the data unchanged if neither helps. One extra byte records which method was used, so Auto.Decode always knows how to undo it. Start here unless you know your data.

LZ

Compress.LZ.Encode(buf: buffer, maxChainLength: number?): buffer
Compress.LZ.Decode(buf: buffer): buffer

Dictionary compression that replaces repeated sequences with references to earlier copies. Works well on structured data with repeating patterns. maxChainLength trades speed for ratio: higher finds better matches but encodes slower (default from configuration).

RLE

Compress.RLE.Encode(buf: buffer): buffer
Compress.RLE.Decode(buf: buffer): buffer

Run-length encoding: long runs of the same byte become a count and a byte. Very fast, and great for voxel or tile maps with large uniform areas.

Delta

Compress.Delta.Encode(prev: buffer, curr: buffer): buffer
Compress.Delta.Apply(prev: buffer, delta: buffer): buffer

Encodes only the bytes that differ between two versions of the same data. Send a full snapshot once, then send deltas; the receiver keeps the previous snapshot and calls Apply to rebuild the current one.

-- server
local delta = Compress.Delta.Encode(lastSent, current)
remote:FireClient(player, delta)
lastSent = current

-- client
snapshot = Compress.Delta.Apply(snapshot, delta)

Base91

Compress.Base91.Encode(buf: buffer): string
Compress.Base91.Decode(str: string): buffer

Turns binary data into printable text, about 23% larger than the bytes (Base64 adds 33%). Use it when binary must travel through something that only takes text, such as a JSON field or an attribute.

Varint

Compress.Varint.Encode(n: number): buffer
Compress.Varint.Decode(buf: buffer, pos: number?): (number, number)

Writes a non-negative integer in as few bytes as it needs (1 byte up to 127). Decode reads from byte offset pos (default 0) and returns the number and the offset just after it.

Configuration