Skip to main content

Data values

Sync copies application values across message boundaries. JSON-compatible values keep the ordinary wire shape; richer values use the explicit graph encoding in protocol 3.

Supported values​

ValueWhat the copy preserves
Strings, booleans, null and finite numbersTheir values
undefined, NaN, infinities and negative zeroExact values, including own properties whose value is undefined
bigintThe exact integer
ArraysLength, holes, explicit undefined entries and enumerable own string properties
Plain and null-prototype objectsEnumerable own string properties and the plain/null prototype distinction
Map and SetEntry order, values and object keys
DateIts timestamp, including an invalid date
RegExpSource, flags and lastIndex
ArrayBuffer, DataView and supported typed arraysBytes, view type, offsets and shared backing-buffer relationships within the copied graph
Shared references and cyclesIdentity relationships inside one copied graph

The copy is separate from the caller's objects. Object identity is preserved within a message, including objects used as Map keys; it is not shared with the original objects or across separate messages. Buffers are copied rather than transferred.

Supported typed arrays are Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array, BigInt64Array and BigUint64Array. Float16Array is unsupported.

Object property descriptors, methods and custom prototypes do not cross the boundary. Enumerable accessors are read as values. Non-enumerable properties are omitted; enumerable symbol keys are rejected. Built-in objects preserve their supported contents, not arbitrary extra properties attached to them.

Functions, symbol values, promises, Error objects, arbitrary class instances, weak collections and shared-memory buffers are unsupported. They throw during encoding. Direct Sync payloads also do not resolve Minecraft engine objects or custom class codecs; public addon APIs add those higher-level adapters.

Protocol compatibility​

Top-level undefined and JSON-compatible trees use the ordinary representation. A nested undefined, sparse array, collection, repeated object reference or other structured value requires protocol 3.

A directed send to a known peer below protocol 3 throws when the payload needs structured encoding. Structured broadcasts use protocol 3 and are ignored by older readers. Discovery metadata must remain JSON-compatible because its broadcast announcements use the oldest supported protocol.

Import​

import { cloneData, freezeData, encodeData, decodeData } from '@bedrock-core/sync/data';
import type { EncodedData } from '@bedrock-core/sync/data';

These helpers are engine-independent. They can be used without creating a SyncNode.

cloneData​

function cloneData<T>(value: T): T

Create a mutable copy using the wire's value semantics. Unsupported values throw here as well as on a bus send.

const key = { id: 'diamond' };
const source = { key, counts: new Map([[key, 4]]) };
const copy = cloneData(source);

copy.key !== key;
copy.counts.get(copy.key); // 4: the copied Map uses the copied key

freezeData​

function freezeData<T>(value: T, opaque?: WeakSet<object>): T

Freeze an existing copied graph and return its snapshot view. This function does not make the initial copy: use freezeData(cloneData(value)) when the caller must retain a mutable source.

Plain objects and arrays are frozen. Collections, dates, buffers and typed views receive guards for mutation operations, including collection writes and typed-array writes. Read-only typed views expose copied buffers; their subarray() results are read-only views. Callers that need a mutable working value should use cloneData(snapshot).

A frozen RegExp cannot update lastIndex. Clone it before global or sticky matching that needs to change that state.

opaque identifies caller-owned handles to leave untouched. It does not make those handles serializable; native-reference encoding belongs to the addon API layer. The TypeScript return type is still T; mutation guards are runtime behavior, not a deep-readonly type conversion.

Replication uses copied, frozen values. State and local event delivery copy values without freezing them.

Encoding helpers​

function encodeData(value: unknown): EncodedData
function decodeData(value: unknown, nodes: NonNullable<EncodedData['nodes']>): unknown

encodeData() returns a copied value and an optional nodes graph. When nodes is absent, value is already the ordinary copied data. Otherwise pass both fields to decodeData() to reconstruct the value. Invalid graph tokens throw.

The bus owns the envelope marker, protocol selection and framing. Use these helpers for copy/codec integrations; use bus.send() to send an application message.