t1k:cocos:playable:signalbus
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: event, pub sub, signal, signalbus, timeout, waitFor
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:signalbusSignalBus — Typed Pub/Sub Event System
Section titled “SignalBus — Typed Pub/Sub Event System”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
Architecture
Section titled “Architecture”SignalBus.instance— singleton- Key = class constructor (no string keys, no magic strings)
- Duplicate subscriptions are silently ignored (safe to call
subscribemultiple times) - Callbacks snapshot before firing — safe to modify subscriptions inside callbacks
Key APIs
Section titled “Key APIs”// SubscribeSignalBus.instance.subscribe(MySignal, (data: MySignal) => { ... });
// Unsubscribe — store callback reference to unsubscribe laterconst cb = (data: MySignal) => { ... };SignalBus.instance.subscribe(MySignal, cb);SignalBus.instance.unsubscribe(MySignal, cb);
// Fire — pass an instance, not the constructorSignalBus.instance.fire(new MySignal(value));
// Async one-shot waitconst result = await SignalBus.instance.waitFor(MySignal);const result = await SignalBus.instance.waitFor(MySignal, 5000); // 5s timeout, throws on expire
// CleanupSignalBus.instance.clear(MySignal); // remove all listeners for one typeSignalBus.instance.clearAll(); // remove everything (use in scene teardown)SignalBus.instance.hasSubscriptions(MySignal); // bool checkSignal Conventions
Section titled “Signal Conventions”Signals are plain TS classes. Constructor args become typed payload fields.
// No payloadexport class FirstInteractionSignal {}
// With payload — use readonly constructor fieldsexport class TapSignal { constructor( public readonly worldPosition: Vec3, public readonly uiPosition: Vec2 ) {}}Project Signals Reference
Section titled “Project Signals Reference”Source paths are under assets/packages/@playablelabs/ (the legacy PLAGameFoundation / PlayableParamterTool repos are the pre-package origin of these files).
| Signal | Source file | Payload |
|---|---|---|
ParametersReadySignal | parameter-tool/PlayableParameterUpdates | none |
AllAsyncParametersReadySignal | scripts/parameter/ParameterController | none |
FirstInteractionSignal | game-foundation/inputService | none |
TapSignal | game-foundation/inputService | worldPosition, uiPosition |
SwipeSignal | game-foundation/inputService | direction, velocity |
DragSignal | game-foundation/inputService | worldPosition, uiPosition, delta |
TouchStartSignal | game-foundation/inputService | worldPosition, uiPosition |
TouchEndSignal | game-foundation/inputService | worldPosition, uiPosition |
RaycastHitSignal | game-foundation/inputService | hitNode, hitPoint |
Workflow: Common Tasks
Section titled “Workflow: Common Tasks”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());When to Use SignalBus vs Alternatives
Section titled “When to Use SignalBus vs Alternatives”| Use case | Recommendation |
|---|---|
| Cross-system communication | SignalBus |
| Parent → child component | Cocos Node events or direct call |
| One-shot async gate (wait for load) | waitFor() |
| UI button clicks | Cocos Button event + direct callback |
| Scene-local tight coupling | Direct method call |
Common Mistakes
Section titled “Common Mistakes”- Firing the constructor instead of an instance:
fire(MySignal)— wrong. Usefire(new MySignal()). - Subscribing without a matching unsubscribe — causes ghost callbacks on recycled nodes. Pair the hooks:
onEnable/onDisable, oronLoad/onDestroy. - Calling
clearAll()mid-game — clears every listener globally; reserve for scene resets. - Awaiting
waitFor(Signal, timeoutMs)with notry/catch— on timeout the promise rejects, it does not resolve withnull/undefined. An unguardedawaiton a timedwaitFor()throws an uncaught rejection instead of degrading gracefully. Observed in aLoadingViewparameters-ready gate: wrap the call intry/catch(or.catch()) and decide the fallback behavior explicitly rather than letting the rejection propagate.
Hard rules
Section titled “Hard rules”- Match the unsubscribe to where you subscribed — subscribed in
onEnable→ unsubscribe inonDisable(a disabled node then receives nothing); subscribed inonLoad/start→ unsubscribe inonDestroy, because a disabled-but-alive node keeps receiving signals. Never subscribe inonLoadand unsubscribe only inonDisable: re-enable does not re-subscribe. - Payloads are passed by reference, never serialized —
RaycastHitSignalcarries aNode(hitNode), which is fine for a synchronous handler. Do not store a payload’s node across a scene replay or anawait: checkisValidfirst, 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.