Skip to content

Engine API

Engine extends Emitter and coordinates dispatch, CRDT-backed containers, history, rules, networking, persistence, compaction, and forks.

Construction

new Engine(options?: EngineOptions)

EngineOptions supports session, stack, space, source, autoConnect, useWebRTC, networkOptions, and an optional profiler. Supplied containers must share the exact same Chronicle session.

Core methods

  • dispatch(type, payload?, opts?) => Promise<any> executes a registry action.
  • dispatchChecked(...) => Promise<DispatchOutcome> returns { ok: true, result } or a structured failure with UNKNOWN_ACTION or ACTION_HANDLER_ERROR.
  • on/off/once come from Emitter; useful events include engine:action, engine:error, and state:updated.
  • state, describe({ detail? }), _gameState, and _agents expose materialized views where implemented by the source.

Lifecycle and history

undo() restores using periodic checkpoints (every 50 actions, at most five), so it is not a per-action snapshot system. snapshot() returns CRDT base64 data plus history; restore(snapshot) reloads it while disconnected.

compact() starts a new CRDT epoch and clears history. It rejects while network or sync is attached. All peers must compact at the same epoch boundary.

fork() creates a divergent branch with shared ancestry. mergeFrom(fork) uses Automerge conflict resolution for divergent scalars and collections; it does not replay the fork's actions as a sequential log.

Operational methods

connect(url), disconnect(), shutdown(), useStorage(adapter), persist(name?, description?), resume(name?), listSaves(), deleteSave(name), enableAutoSave(intervalMs?, name?), and disableAutoSave() are operational APIs, not registry action names.