Interface: PlayerOptions<TMachine>

API / @xmachines/play-xstate / PlayerOptions

Defined in: packages/play-xstate/src/types.ts:18

The lifecycle hooks of the player — the observability surface around the actor.

Type Parameters

Type Parameter
TMachine extends AnyStateMachine

Properties

Property	Type	Description	Defined in
inspect?	| Observer<InspectionEvent> | ((inspectionEvent) => void)	The inspection observer. The factory gives it to createActor of XState without a change. This is the attachment at the moment of the creation, and it is the only route that observes the construction events of the actor. An attachment later, with actor.system.inspect(fn), also works, but it sees only the events after that moment. A PlayerActor is the XState actor itself. Therefore its own events carry actorRef === playerActor, and you can recognize it by its identity. Each PlayerActor is also its own root system. Therefore event.rootId === actor.sessionId separates the complete tree, and this includes the events of an invoked child and of a spawned child, whose actorRef is the child. That identity brings one point to note: the @xstate.actor event fires from inside the constructor of the actor. Its actorRef value is therefore the instance during the construction, and state, currentRoute, currentView, and initialRoute do not exist yet. A read of one of them there throws. Keep the reference, and read the signals from a later event, or outside the observer. Example import { createBrowserInspector } from "@statelyai/inspect"; const { inspect } = createBrowserInspector(); const createPlayer = definePlayer({ machine, options: { inspect } }); For an inspector that you create after the factory, for example behind a dev-tools switch, give the factory a function that forwards each event: inspect: (event) => currentInspector?.(event).	packages/play-xstate/src/types.ts:106
onError?	(actor, error) => void	The actor calls it on an actor error: a snapshot restore that fails at start(), an action or a guard that throws, and a failure of the view derivation. The actor reads this field at the moment of the delivery of an error, and not at its construction. The options object is shared by its reference. Therefore a handler on that object still receives each actor error, also after a later attachment, and the removal of the handler restores the loud default below. With a handler in place, the actor sends the error there, and the error counts as handled. XState decides its own global rethrow for each observer, and this option does not reach that decision: a subscription of your own without an error listener still forces the rethrow, with an onError handler and without one. Without onError, each actor error stays loud, with an unhandled rethrow through setTimeout. No error therefore disappears in silence. Your own error subscribers stop that default not: onError alone stops it. A failure of the actor that is an Error already arrives without a change, and it keeps the identity of the machine. A machine that throws a value that is not an Error arrives as an ActorThrewNonErrorError, with the value from the throw on its cause field.	packages/play-xstate/src/types.ts:71
onStart?	(actor) => void	The actor calls it on each real start, which is every transition from “not running” to “running”. A start after a stop is such a transition. A second start() call while the actor runs fires the hook not again.	packages/play-xstate/src/types.ts:24
onStateChange?	(actor, state) => void	The actor calls it when the state signal changes	packages/play-xstate/src/types.ts:46
onStop?	(actor) => void	The actor calls it on each real stop, which means only after it tore a running actor down. A second stop() call, a second dispose() call, and a stop of an actor that never started fire the hook not.	packages/play-xstate/src/types.ts:31
onTransition?	(actor, prevState, nextState) => void	The actor calls it after every event that send() processes. This includes an event that the machine ignores, and prevState and nextState are then the same snapshot. Compare the two values when only a real transition is important to you.	packages/play-xstate/src/types.ts:39