Skip to main content

sync

@bedrock-core/sync is the low-level cross-addon transport for Minecraft Bedrock. It layers a message bus, peer discovery, RPC, replicated state, transient events and watched publication snapshots on top of script events.

For framework and library developers

Use public addon APIs for addon integrations. This package is the independent transport used to implement the runtime and test its wire protocol.

Install​

npm install @bedrock-core/sync

Import the transport directly:

import { createSync } from '@bedrock-core/sync';

When to use it directly​

Use Sync to implement transport infrastructure or test bus, discovery, framing and state replication. Normal addon code uses addon API imports from provider packages.

Quick start​

Create one SyncNode for the realm and call start() once on boot.

import { createSync } from '@bedrock-core/sync';

export const sync = createSync({
id: 'mycoolitems', // unique, stable id (a-z0-9_) — transport address + default owned namespace
version: '1.0.0',
meta: { /* opaque data peers see as PeerInfo.meta */ },
});

sync.start();

After start(), sync.discovery, sync.rpc, sync.state, sync.events and sync.replication are live.

sync.discovery.onPeerUp(peer => console.warn('peer up', peer.id));
sync.rpc.onRequest('ping', () => 'pong');
sync.state.set('mycoolitems', 'volume', 5);
sync.events.emit('restocked', { item: 'diamond' });

SyncNodeOptions​

interface SyncNodeOptions {
id: string;
version?: string;
schemaVersion?: number;
meta?: Record<string, unknown>;
maxMessage?: number;
instanceId?: string;
}
OptionDefaultWhat it does
id—Unique addon id. Used as the envelope src, the RPC address, and the one namespace this node writes.
version'0.0.0'Announced to peers as PeerInfo.version.
schemaVersion0Announced alongside version, for higher layers that version their payloads.
meta—JSON-compatible metadata broadcast with every announce; surfaces on peers as PeerInfo.meta. server-runtime puts the addon manifest here
maxMessage2000Character budget for one script-event message — what the chunker splits against and what a batch is packed up to. Mainly for tests.
instanceIdgeneratedOverrides the auto-generated instance id. Mainly for tests.

SyncNode​

class SyncNode {
readonly id: string;
readonly bus: Bus;
readonly discovery: Discovery;
readonly rpc: Rpc;
readonly state: State;
readonly events: Events;
readonly replication: Replication;

start(): void; // idempotent
stop(): void;
}

createSync(options) builds one and returns it; new SyncNode(options) is equivalent. start() brings up the bus and responders before discovery advertises. stop() stops every subsystem, rejects pending RPC calls and releases publication/watch handles. It does not dispose application-owned subscriptions to State or Discovery observables; retain their unsubscribe functions.

Choose a data channel​

ChannelRetained dataUse
rpcPending calls until a reply, timeout or target lossAsk a peer to perform one operation
stateEvery node mirrors owner-written keysRead replicated values synchronously
eventsNo replay or retained payloadAnnounce a transient happening
replicationOnly explicit watches retain foreign publicationsPublish a complete dataset with opt-in local retention

Core uses Sync replication for library registries, while owning their schemas, compatibility checks and provider selection. Sync itself assigns no registry meaning to a publication key.

Application payloads use the data value contract. Protocol 3 preserves collections, sparse arrays, exact numeric values, binary views, shared references and cycles; JSON-compatible messages can use protocols 1 and 2.

Notes​

  • One node per realm. Use additional identities only for protocol tests. The registered addon runtime owns its internal node.
  • Timing is tick-based. Messages flush over ticks; you will never get an RPC reply on the same tick you sent it.
  • Large payloads are fine. An envelope above the size budget is split into frames and reassembled transparently; one that fits is sent whole.
  • Small messages travel together. A node that sends several at once has them packed into as few script events as the budget allows — see the outbound queue.
  • sync never touches dynamic properties. They are pack-scoped, and persistence is each addon's own responsibility — see State.
  • Load order is not a problem. Every node re-announces on a heartbeat and broadcasts a whois at startup, so a late loader catches up and an early loader hears about it.

Next steps​

PageDescription
DiscoveryFinding peers: announce, whois, TTL eviction, namespace collisions
RpcRequest/response calls, typed clients, handler maps, timeouts
StateReplicated key/value: deltas, snapshots, requestSync, ownership
EventsA happening: one message, every listener, nothing kept
ReplicationNamed publications, explicit watches and immutable snapshots
Data valuesSupported JavaScript values, copying and read-only snapshots
ProtocolThe bus, the envelope, the supported protocol window, framing and rate limiting