Events
sync.events broadcasts transient happenings. The sender's own listeners run synchronously; remote listeners receive the queued message over subsequent ticks. Nothing is stored or replayed.
This page describes transient payloads in the independent Sync transport. Addon APIs export the observable package's Signal<T> contract through public addon API imports.
Import
import type { Events, EventHandler } from '@bedrock-core/sync';
sync.events is created and started by the node.
Usage
sync.events.emit('purchase', { playerId, gold: 5 });
const release = sync.events.on('drav0011_economy', 'purchase', (payload, from) => {
console.warn(`${from} sold for ${String((payload as { gold: number }).gold)}`);
});
release();
API
emit
sync.events.emit(name: string, payload?: unknown): void
Announce a happening under this node's id. Local handlers receive a structured copy synchronously, before the remote message is queued. They cannot mutate the caller's source object through that copy. Local handlers share one copied payload; it is not frozen. The remote message is encoded from the caller's payload and follows the same supported-value contract.
Unsupported payloads throw. A remote structured payload requires protocol 3; JSON-compatible events can reach older supported peers. Local delivery has already happened if the later bus send fails.
on
sync.events.on(namespace: string, name: string, handler: EventHandler): Unsubscribe
type EventHandler = (payload: unknown, from: string) => void;
Listen for one sender's event name. The namespace filter matches the envelope's src, independently of the event payload. SyncNode also checks the current discovered running instance. These identifiers are cooperative metadata, not authenticated identities; validate operations that require authority in the owning addon. A handler may be registered before the sender exists — a subscription is only a filter.
Notes
- Nothing is replayed. A node that was not listening when an event was announced has missed it. A late joiner receives no backlog, unlike State.
- A handler that throws is caught and logged against the namespace and name; the others still run.
- One
emitcreates one logical envelope, subject to framing and the outbound queue. Use State or Replication when late readers need the current value. Each state write or publication update also sends a message; these channels do not automatically coalesce application updates. - No reply. An event has no answer; that is Rpc.
Wire
One message type, event, carrying { n: name, p: payload }. A payload that is not an object with a string n is dropped.
Lifecycle
SyncNode starts and stops Events. Stopping clears event handlers, so register them again after restarting the node. Each on() unsubscribe function is idempotent.