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.
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
- yarn
- pnpm
npm install @bedrock-core/sync
yarn add @bedrock-core/sync
pnpm add @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;
}
| Option | Default | What 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. |
schemaVersion | 0 | Announced 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 |
maxMessage | 2000 | Character budget for one script-event message — what the chunker splits against and what a batch is packed up to. Mainly for tests. |
instanceId | generated | Overrides 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
| Channel | Retained data | Use |
|---|---|---|
rpc | Pending calls until a reply, timeout or target loss | Ask a peer to perform one operation |
state | Every node mirrors owner-written keys | Read replicated values synchronously |
events | No replay or retained payload | Announce a transient happening |
replication | Only explicit watches retain foreign publications | Publish 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
whoisat startup, so a late loader catches up and an early loader hears about it.
Next steps
| Page | Description |
|---|---|
| Discovery | Finding peers: announce, whois, TTL eviction, namespace collisions |
| Rpc | Request/response calls, typed clients, handler maps, timeouts |
| State | Replicated key/value: deltas, snapshots, requestSync, ownership |
| Events | A happening: one message, every listener, nothing kept |
| Replication | Named publications, explicit watches and immutable snapshots |
| Data values | Supported JavaScript values, copying and read-only snapshots |
| Protocol | The bus, the envelope, the supported protocol window, framing and rate limiting |