Skip to main content

toSignal

toSignal adapts a native event source to the framework's Signal<T> interface. It does not retain a value or replay events.

Subscription contracts​

OperationSignal<T>NativeSignal<T, Options>
Subscribe resultCleanup functionRegistered callback or void
Remove subscriptionCall the cleanupunsubscribe(callback)
Filter optionsNoneSource-specific options

Minecraft event signals return a callback used for explicit removal. The structural NativeSignal type also accepts sources that return void. See the official event-signal contract.

interface NativeSignal<T, Options = never> {
subscribe(callback: (event: T) => void, options?: Options):
((event: T) => void) | void;
unsubscribe(callback: (event: T) => void): void;
}

toSignal<T, Options = never>(
source: NativeSignal<T, Options>,
options?: Options,
): Signal<T>

Usage​

import { world } from '@minecraft/server';
import { toSignal } from '@bedrock-core/observable';

const deaths = toSignal(world.afterEvents.entityDie);
const stop = deaths.subscribe(({ deadEntity }) => {
console.warn(deadEntity.typeId);
});

stop();

Pass native filter options as the converter's second argument. Their type is inferred from the source. Conversion does not subscribe immediately; every subsequent subscribe registers its own callback with those options.

Each returned cleanup is idempotent and owns one registration. It passes the callback returned by the native source to unsubscribe; when the source returns void, it passes the registered input callback. Reusing a consumer callback across subscriptions does not join their lifetimes.

The adapter preserves the source's delivery timing and execution restrictions. It does not reschedule handlers or add listener error isolation.

Addon APIs​

Expose a converted Signal<T> from public addon APIs. Consumers use subscribe(listener) and call its returned cleanup. Builder requires the cleanup-return contract for public exports; direct native signals must be converted first.

Conversion changes only subscription ownership. For cross-addon APIs, native event payloads still need a supported public data/reference contract; project engine event objects into that contract before exporting them. See public addon APIs.

NativeSignal and toSignal are implemented in the native adapter module and exported from both @bedrock-core/observable and @bedrock-core/observable/minecraft. The main entry remains engine-free. last accepts either signal type when a retained latest payload is needed. Observable value types keep their existing get/set/subscribe contract.