Snap Structure

This page describes the snap structure, all kinds of snap structures, and their purpose. It also shows how to encode and decode strings in the snap structure.

Snap Empty Structure

Snap Empty chunk have the following bytes structure:

// chunk header...
chunkByte[3-*] // current tick - integer
chunkByte[*]   // delta tick   - integer

Snap Single Structure

Snap Single chunk have the following bytes structure:

// chunk header...
chunkByte[3-*]   // current tick - integer
chunkByte[*]     // delta tick   - integer
chunkByte[*]     // crc          - integer
chunkByte[*]     // payload size - integer
chunkByte[*-...] // snap payload (variable-int compressed)

The snap payload, after variable-int decompression, contains:

int[0]           // removed items count - integer
int[1]           // updated items count - integer
int[2]           // unused              - integer (always 0)
int[3-*]         // removed item keys   - integers (one per removed item)
int[*-...]       // item deltas

Removed Items

Each removed item is identified by its item key — a single packed integer computed as (type_id << 16) | id.

Item Deltas

Each item delta (new or updated) has the following structure:

int[0]           // type_id - packed integer
int[1]           // id      - packed integer
int[2]           // _size   - packed integer (only present if type has no pre-agreed size)
int[3-*]         // data    - packed integers (item-specific fields)

For updated items, the data contains the difference (delta) between the new and old item values, computed element-wise using wrapping 32-bit integer subtraction. For new items, the data contains the full item values.

INFO

It is recommended to check the Snap Types section for more information about these values.

Snap Slice Structure

Snap Slice chunk have the following bytes structure:

// chunk header...
chunkByte[3-*]   // current tick        - integer
chunkByte[*]     // delta tick          - integer
chunkByte[*]     // crc                 - integer
chunkByte[*]     // total number        - integer
chunkByte[*]     // current number      - integer
chunkByte[*]     // size                - integer
chunkByte[*]     // removed items count - integer
chunkByte[*]     // updated items count - integer
chunkByte[*]     // unused              - integer (0) 
chunkByte[*-...] // snap payload

INFO

Snap Slice has a particular way to send the Snap Items. Check the Snap Slice section for more information.

Snap Item Structure

Each snap item uses variable-length integer packing for all fields:

itemByte[*-...]  // item type - packed integer
itemByte[*-...]  // item id   - packed integer
itemByte[*-...]  // item-specific payload - packed integers