Skip to main content

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 emit creates 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.