Skip to content

t1k:cocos:playable:signalbus

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: event, pub sub, signal, signalbus, timeout, waitFor

/t1k:cocos:playable:signalbus

Singleton event bus using class constructors as keys. Signals are plain TS classes — no base class required. See also: t1k-cocos-playable-lifecycle, t1k-cocos-playable-gameflow.

Import path: db://assets/packages/@playablelabs/game-foundation/signalBus

  • SignalBus.instance — singleton
  • Key = class constructor (no string keys, no magic strings)
  • Duplicate subscriptions are silently ignored (safe to call subscribe multiple times)
  • Callbacks snapshot before firing — safe to modify subscriptions inside callbacks
// Subscribe
SignalBus.instance.subscribe(MySignal, (data: MySignal) => { ... });
// Unsubscribe — store callback reference to unsubscribe later
const cb = (data: MySignal) => { ... };
SignalBus.instance.subscribe(MySignal, cb);
SignalBus.instance.unsubscribe(MySignal, cb);
// Fire — pass an instance, not the constructor
SignalBus.instance.fire(new MySignal(value));
// Async one-shot wait
const result = await SignalBus.instance.waitFor(MySignal);
const result = await SignalBus.instance.waitFor(MySignal, 5000); // 5s timeout, throws on expire
// Cleanup
SignalBus.instance.clear(MySignal); // remove all listeners for one type
SignalBus.instance.clearAll(); // remove everything (use in scene teardown)
SignalBus.instance.hasSubscriptions(MySignal); // bool check

Signals are plain TS classes. Constructor args become typed payload fields.

// No payload
export class FirstInteractionSignal {}
// With payload — use readonly constructor fields
export class TapSignal {
constructor(
public readonly worldPosition: Vec3,
public readonly uiPosition: Vec2
) {}
}

Source paths are under assets/packages/@playablelabs/ (the legacy PLAGameFoundation / PlayableParamterTool repos are the pre-package origin of these files).

SignalSource filePayload
ParametersReadySignalparameter-tool/PlayableParameterUpdatesnone
AllAsyncParametersReadySignalscripts/parameter/ParameterControllernone
FirstInteractionSignalgame-foundation/inputServicenone
TapSignalgame-foundation/inputServiceworldPosition, uiPosition
SwipeSignalgame-foundation/inputServicedirection, velocity
DragSignalgame-foundation/inputServiceworldPosition, uiPosition, delta
TouchStartSignalgame-foundation/inputServiceworldPosition, uiPosition
TouchEndSignalgame-foundation/inputServiceworldPosition, uiPosition
RaycastHitSignalgame-foundation/inputServicehitNode, hitPoint

Wait for parameters before initializing scene:

await SignalBus.instance.waitFor(AllAsyncParametersReadySignal);
this.initScene();

Subscribe in onEnable / unsubscribe in onDisable (Cocos component pattern; the pair also covers onDestroy, since a node is disabled before it is destroyed):

private onTap = (s: TapSignal) => { this.handleTap(s); };
onEnable() { SignalBus.instance.subscribe(TapSignal, this.onTap); }
onDisable() { SignalBus.instance.unsubscribe(TapSignal, this.onTap); }

Fire after state change:

SignalBus.instance.fire(new ParametersReadySignal());
Use caseRecommendation
Cross-system communicationSignalBus
Parent → child componentCocos Node events or direct call
One-shot async gate (wait for load)waitFor()
UI button clicksCocos Button event + direct callback
Scene-local tight couplingDirect method call
  • Firing the constructor instead of an instance: fire(MySignal) — wrong. Use fire(new MySignal()).
  • Subscribing without a matching unsubscribe — causes ghost callbacks on recycled nodes. Pair the hooks: onEnable/onDisable, or onLoad/onDestroy.
  • Calling clearAll() mid-game — clears every listener globally; reserve for scene resets.
  • Awaiting waitFor(Signal, timeoutMs) with no try/catch — on timeout the promise rejects, it does not resolve with null/undefined. An unguarded await on a timed waitFor() throws an uncaught rejection instead of degrading gracefully. Observed in a LoadingView parameters-ready gate: wrap the call in try/catch (or .catch()) and decide the fallback behavior explicitly rather than letting the rejection propagate.
  • Match the unsubscribe to where you subscribed — subscribed in onEnable → unsubscribe in onDisable (a disabled node then receives nothing); subscribed in onLoad/start → unsubscribe in onDestroy, because a disabled-but-alive node keeps receiving signals. Never subscribe in onLoad and unsubscribe only in onDisable: re-enable does not re-subscribe.
  • Payloads are passed by reference, never serialized — RaycastHitSignal carries a Node (hitNode), which is fine for a synchronous handler. Do not store a payload’s node across a scene replay or an await: check isValid first, or copy the plain values you need.
  • Keys are class constructors, not names — there are no event-name strings to collide. The inverse failure: two copies of the same signal class (a vendored file plus the package import) are two different keys, and subscribers to one never see the other. Import each signal class from one path.