KSLCore/ksl.modeling.agent/StatechartBuilder

StatechartBuilder

Top-level builder for AgentModel.Statechart. Constructed via the statechart { } method on an AgentLike owner; users do not instantiate this class directly.

Within a statechart { ... } block, declare the initial state with initial and one or more states with state. The block must declare at least one state and the initial state must be one of them. States may be composite (nest substates via inner state blocks); a composite state must declare its initial substate via initial(...) inside the state block.

Functions

final

fun final(name: String, block: StateBuilder.() -> Unit = {})

Declare a final (terminal) state named name. Entering a final state runs the optional block's onEntry actions, then auto-stops the statechart and fires onCompletion. Final states are leaves with no other triggers (no onMessage, onTimeout, onCondition, onSignal, or substates) — entering one ends the chart's life.

initial

fun initial(stateName: String)

Designate stateName as the state the statechart enters when started. If that state is composite, its initial substate (and recursively any composite substates' initial substates) is resolved to the leaf state actually entered.

onCompletion

fun onCompletion(block: (finalStateName: String) -> Unit)

Run block when the statechart reaches any final state (just after the chart has stopped). The block receives the name of the final state reached. A natural place to install and start a different statechart on the owner (agent.useStatechart(next)), send a completion message, or record a result — the chart is already stopped, so isStarted is false and a replacement may be selected.

state

fun state(name: String, block: StateBuilder.() -> Unit)

Declare a top-level state with the given name and configure it via block. The block may itself declare substates via nested state calls, producing a composite state.