Skip to main content

Events

Gameplay events flow through typed dispatch / listen methods on the game, stage, and entities, and through the shared zylemEventBus for cross-cutting subscribers (UI overlays, analytics, editor-adjacent tools).

Editor configuration and entity snapshots use @zylem/bridge, not this bus—keep gameplay listeners on the APIs below.

Event maps​

Defined in @zylem/game-lib/events:

Game events (GameEvents)​

EventPayload highlights
loading:startLoad began; optional stageName, stageIndex
loading:progressmessage, progress, current, total
loading:completeLoad finished
paused{ paused: boolean }
debug{ enabled: boolean }

Stage events (StageEvents)​

EventPayload
stage:loaded{ stageId }
stage:unloaded{ stageId }
stage:variable:changed{ key, value }

Entity events (EntityEvents)​

EventWhen
entity:spawnedEntity entered the stage
entity:destroyedEntity removed
entity:collisionCollision pair ids
entity:model:loadingGLTF fetch started
entity:model:loadedModel ready or failed
entity:animation:loadedClips ready on an actor

Actors emit model/animation events during asset load; other types may dispatch gameplay events manually via entity.dispatch.

Scopes​

import { createGame, createStage } from '@zylem/game-lib/core';
import { zylemEventBus } from '@zylem/game-lib/events';

// Global bus
const off = zylemEventBus.on('loading:progress', (payload) => {
  console.log(payload.message);
});

// Game instance (also mirrors to the bus for game events)
const game = createGame(createStage());
const offGame = game.listen('loading:start', (payload) => {
  console.log(payload.stageName);
});

// Stage wrapper
const stage = createStage();
stage.listen('stage:loaded', ({ stageId }) => console.log(stageId));

// Entity
ball.listen('entity:model:loaded', ({ success }) => console.log(success));

dispatch on game, stage, or entity emits locally and on zylemEventBus for the same event name.

Sample: website/snippets/game-and-stages/events.ts.

DOM stage state (optional)​

For non-valtio consumers, @zylem/game-lib/core exports:

  • initStageStateDispatcher() — listens to reactive stage state and emits STAGE_STATE_CHANGE on window
  • dispatchStageState() — push the current snapshot manually

Payload shape: { entities, variables } (StageStateChangeEvent).

Pitfalls​

  • listen returns an unsubscribe function; call it (or dispose / disposeEvents) to avoid leaks when hot-swapping UI.
  • Loading events on the game use GameLoadingEvent (@zylem/game-lib/core); stage onLoading uses the slimmer LoadingEvent without guaranteed stage metadata until wired through the game delegate.
  • Not every typed stage event is emitted automatically yet—use dispatch for custom stage signals you own.

API reference​