flow

What it does

flow runs the game as a graph. Exactly one node is active. A rest node waits; a player answer comes through the gate, a world event through the inbox. Nothing else moves the graph. The runner opens one model transaction per node run and commits it on the edge. A node that throws changes nothing: the runner rolls back to the last rest point, retries, then enters safeNode.

Five modules: runner (its methods sit on the plugin root), gate, inbox, fx and features.

Effects. A node runs an effect three ways. await fx(descriptor) waits for it. fx.start(descriptor) starts it and goes on. fx.emit(hint(...)) is released after the commit of the edge and dropped in fast mode. One plugin owns each effect kind with fx.handle. An awaited effect without a handler resolves undefined at once, so the same node runs headless.

Modes. "live" and "fast". In fast mode effects answer at once, hints are dropped and only runInFast handlers run. All node logic runs for real.

Graph rules checked at run(). Every outcome has an edge. Every node is reachable from the start. A cycle needs a rest node. Every inbox type is an outcome of its node. Flow ids are unique, and a feature name is neither a flow id nor a plugin name. safeNode is the path of a checkpoint. A flow above 15 nodes is a warning.

The node, flow, slot and feature helpers are on the Nodes and flows and Features pages.

Config

pluginConfigs.flow.

In a game made with defineGameApp, mainFlow and safeNode come from the definition's flow and safeNode.

API

Mounted at app.flow, reachable with ctx.require(flowPlugin).

Runner

Gate, inbox, fx, features

Events

Emits

Listens to

None.

Example

import { createApp, createPlugin, defineGame, flowPlugin, type } from "@moku-labs/game";
import { createHeadless } from "@moku-labs/game/testing";

const { defineNode, defineFlow } = defineGame<{
  player: { coins: number };
  session: { rolls: number };
  assets: string;
  strings: Record<string, unknown>;
}>();

const home = defineNode({ outcomes: { roll: type() }, rest: true, checkpoint: true });
const roll = defineNode({
  outcomes: { done: type() },
  run: ({ player, session, rng, out }) => {
    player.coins += rng.stream("dice").range(1, 6);
    session.rolls += 1;
    return out.done();
  }
});

const mainFlow = defineFlow("main", {
  nodes: { home, roll },
  start: "home",
  edges: { home: { roll: "roll" }, roll: { done: "home" } }
});

// A game plugin hooks the edges of the graph.
const edgeLog = createPlugin("edgeLog", {
  depends: [flowPlugin],
  hooks: ctx => ({
    "flow:edge": payload => {
      ctx.log.info("edge", { node: payload.node, outcome: payload.outcome });
    }
  })
});

const app = createApp({
  plugins: [edgeLog],
  pluginConfigs: {
    model: { initialPlayer: { coins: 0 }, initialSession: { rolls: 0 }, seed: 42 },
    flow: { mainFlow, safeNode: "home" }
  }
});

const game = await createHeadless(app); // fast mode, started, resolved at the first rest
await game.walk([{ at: "home", intent: "roll" }]);
app.flow.state().path; // "home"
app.model.store.snapshot().session; // { rolls: 1 }
await game.stop();

Related

• How it works: nodes, edges and commits.
• Nodes and flows: defineNode, defineFlow, slots and effects.
• Doors for the editor: bookmarks and restores from outside.