Utilities guide

Signals and event dispatch

Use small, typed primitives to publish values, route named events, and keep game systems loosely coupled.

What are these utilities?

A signal represents one stream of values. An event dispatcher maps event names to their payload types. Both let callers subscribe with a callback and receive an unsubscriber, without depending on the DOM or a game runtime.

Live example

Connect game state to game events

Change a score through a signal, then route gameplay messages through a typed event dispatcher.

score_changed

One value stream drives the score display.

Current score 0

Received: 0

Event dispatcher

Named gameplay messages can carry different payloads.

Events: none yet

Choose a primitive

  • Signal is for one value type, such as health, score, or a loading percentage.
  • Event dispatcher is for several named messages with different payload types.
  • Scene events are for game-scoped communication that also needs ownership, disposal, and runtime error routing.

Public types

  • Signal<EventDetail> and create_signal<EventDetail>()
  • EventDispatcher<EventMap> and create_event_dispatcher<EventMap>()
  • SignalUnsubscriber
  • EventMap keys describe event names, and undefined describes an event with no payload

Minimum viable signal

typescript
import { create_signal } from "squander/signals";

const score_changed = create_signal<number>();
const stop_score_listener = score_changed.subscribe((score) => {
  update_score_display(score);
});

score_changed.emit(100);
stop_score_listener();

Minimum viable event dispatcher

typescript
import { create_event_dispatcher } from "squander/signals";

type GameEvents = {
  player_scored: { points: number };
  game_reset: undefined;
};

const game_events = create_event_dispatcher<GameEvents>();
game_events.on("player_scored", ({ points }) => add_score(points));
game_events.emit("player_scored", { points: 10 });
game_events.emit("game_reset");

Scope and limitations

These utilities are standalone and reusable. They do not schedule work, serialize payloads, or own a game lifetime. Use the scene event bus when events belong to a game and should be disposed with its scene manager. Listener changes during an emission take effect on the next emission, and once listeners unsubscribe before their callback runs.