raea/state

A game's logic in raea is a pure step: given the last state and this frame's input, return the next state. That makes a play-through repeatable, so the same input renders the same frames. machine defines a state machine whose states and transitions are checked by TypeScript: a transition to a state that doesn't exist fails to compile. useGameState and useGameEvents run a step function inside a composition.

import { machine } from "raea/state";

type Player = { y: number; vy: number };
type Env = { jump: boolean };

const player = machine<Player, Env>()({
  id: "player",
  initial: "standing",
  states: {
    standing: { always: { to: "jumping", when: (_c, e) => e.jump } },
    jumping: { always: { to: "standing", when: (c) => c.y <= 0 } },
  },
});

See Your first game for a whole game built on a step function.

import { firstDecider, inState, machine, replayDecider } from "raea/state"

raea/state exports 2 hooks, 6 functions, 1 value, 20 types. Bevy's counterpart: bevy_state. Source: sdk/raea/src/state.ts.

#Hooks

#useGameEvents

The frames, in order, at which isEvent(before, after) holds: after is the state step makes at frame f from before, the state at f - 1. It runs the same (kept) fold as useGameState through the composition's last frame, counted from the nearest enclosing Sequence, so sound can be cued to what happens in the game. While a person plays (live input) it runs only through this frame: what comes next hasn't been played yet. The list is read-only (frozen): the same one is handed out while nothing new happened, so copy it before changing it.

function useGameEvents<S>(initial: S, step: Step<S>, isEvent: (before: S, after: S) => boolean): number[]

#useGameState

The game's state at this frame: initial at frame 0, then step(state, input, g) applied for each earlier frame g in order. Frames count from the nearest enclosing Sequence, so a game starts when its Sequence does.

function useGameState<S>(initial: S, step: Step<S>): S

#Functions

#inState

Whether name is active in the snapshot (the leaf or any state around it), as XState's state.matches.

function inState<N extends string>(snap: Snapshot<N>, name: N): boolean

#machine

A machine for contexts of type C, stepped with an env of type E (a game's frame input and world, a workflow's facts). Curried so the state names are inferred from the definition while C and E are given: machine<Player, Env>()({ id, initial, states }). A transition to a state that doesn't exist, or a guard reading a field C lacks, fails to compile; what types can't hold (an initial that isn't a substate, unreachable states, dead ends) throws here, when the module loads.

function machine<C, E = unknown>(): <const N extends string, const K extends string = "sm">(config: MachineConfig<C, E, N, K>) => Machine<C, E, N, K>

#replayDecider

A decider that replays recorded decisions: log[machine][n] is the edge chosen at that machine's step n (missing: wait). How a model's or a person's choices, taken outside the step, re-enter it exactly.

function replayDecider(log: Record<string, Record<number, number | { edge: number; evidence?: unknown; }>>, name?: string): Decider

#stateOf

The active leaf of a snapshot (undefined before the first step).

function stateOf<N extends string>(snap: Snapshot<N>): N | undefined

#stepAll

One frame for each entity of a list, each carrying its own machine (one per enemy), in order.

function stepAll<C, E, N extends string, K extends string>(m: Machine<C, E, N, K>, entities: readonly C[], env: E, opts?: readonly string[] | StepOptions): C[]

#transitionOf

The transition a step took, read from two snapshots of one machine (null when none fired): how a trace that only sees states (a playtest over a game's pure fold) recovers the TransitionRecord a sink would have had, minus evidence.

function transitionOf(m: AnyMachine, before: Snapshot<string> | undefined, after: Snapshot<string>): TransitionRecord | null

#Values

#firstDecider

The default decider: the first candidate.

#Types

#Action

An action: a pure function returning the new context (never a changed old one).

type Action = (ctx: C, env: E) => C

#Actions

type Actions = Action<C, E> | readonly Action<C, E>[]

#Analysis

#AnyMachine

type AnyMachine = Machine<any, any, string, string>

#ChoicePoint

A choice point as a decider sees it: which machine, where, and the candidates whose guards hold.

#Decider

Picks a transition at a choice point. Called inside the step, so it must answer synchronously: a model or a person is asked outside the step and their answer replayed (replayDecider). Deterministic deciders keep a fold pure.

#Decision

What a decider answers: the edge it picks (one of the candidates' edge), or null to wait this step; evidence is whatever supports the choice (a bot's score, a model's probabilities), recorded beside the transition.

#Edge

#Guard

A trigger: polled each step while its state is active (the context, and whatever the step passes as env).

type Guard = (ctx: C, env: E) => boolean

#Machine

#MachineConfig

#Playtest

What a playtester needs from a game, exported beside the view as export const playtest: Playtest<S> = {...} (sdk/react/docs/playtest.md). Optional: a game without one is played from pixels and events alone. Everything here is pure, so a bot steps the game headlessly, restores any state it has seen (states are values) and searches from it; whatever it plays is an input timeline raea render --input turns back into the same frames.

#Snapshot

The machine's runtime state, kept in the context it drives. path is the active states outermost first ([] before the first step); at[i] is the step on which path[i] was entered; n counts the machine's steps from 0; e is the edge the last transition took (an index into machine.edges); by names the decider that chose it (absent: a guard); hist is each history state's last substate.

#StateConfig

#StateName

The state names of a machine.

type StateName = M extends Machine<any, any, infer N, any> ? N : never

#StepOptions

What a step may be given besides the context and env.

#TransitionConfig

A transition: where to go (to, or XState's target), when (when, or XState's guard; none: always), after how many steps in the state at least (after), and what to do on the way (actions).

type TransitionConfig = Target<N> & When<C, E> & { /** steps in the state before this transition may fire (0) */ after?: number; actions?: Actions<C, E>; /** what the transition means: a decider reads it (a model's option description), reports show it */ description?: string; }

#TransitionRecord

One transition as a row: what a trace keeps and rdb loads (step, machine, from, to, edge, decider, evidence). from is null for the first step's entry into the initial states.

#Transitions

A target's name alone, one transition, or several checked in order.

type Transitions = | NoInfer<N> | TransitionConfig<C, E, N> | readonly (NoInfer<N> | TransitionConfig<C, E, N>)[]

#Watched

A machine's state in some context, for a trace (Playtest.machines).