XMachines Guides

User-facing guides for the XMachines Play architecture.

Start Here

Getting Started — Installation, first actor, routing, router adapters, and view renderers

Background reading that explains the why behind XMachines design decisions.

Understanding State Machines — What finite state machines are, how meta.route and meta.view extend them, and why they replace boolean flags and component-level routing logic
Understanding the Actor Model — The actor/infrastructure split, why the machine has zero framework imports, and how the reset invariant works
Understanding Routing — The URLPattern grammar that a meta.route path declares, the prefix rule that decides every optional route, and the three invariants that every router adapter follows
Understanding Atoms — The atom primitives (createAtom, createWritableAtom, watchAtom), why XMachines uses them instead of observables, and the architectural invariants they enforce

Working with a running actor.

Inspecting a Running Actor — Attaching the Stately inspector via PlayerOptions.inspect, reading inspection events, enabling an inspector after startup, and inspecting without a browser