Statechart
A flat statechart attached to an AgentLike owner. Behavior consists of a finite set of named states; the chart is always in exactly one state once started.
Implemented as an inner class of AgentModel rather than a separate ModelElement: the inner-class outer-instance reference (this@AgentModel) gives this class direct access to the outer's protected schedule(...) and executive. No ModelElement registration is needed, so a Statechart can be constructed at any time — including during a replication, as part of a transient Agent's construction.
Lifecycle:
start enters the initial state and installs triggers.
stop tears down pending timeout/condition/transition events and the arrival listener.
For setup-time agents, AgentModel.initialize / AgentModel.afterReplication (for transient
Agent) or the owner's own lifecycle (forPermanentAgent/AgentResource) drives start/stop on each replication.For runtime-created transient
Agents,statechart { }auto-starts the chart immediately since the simulation is already running.
Hierarchical states, history, and onSignal are not in this version (planned as Phase 1b.1).
Properties
All currently-active state names, root composite first, leaf last. For a flat statechart this is always a single-element list. Useful for diagnostics and for checking whether a particular composite is active.
Name of the currently active leaf state, or the last leaf held before the statechart was stopped at end-of-replication. null only before the first start.
All state names declared in this statechart (including nested substates), in undefined order. Used by AgentPerformance to pre-allocate per-state statistics responses.
Functions
Register an observer to receive state-entry, state-exit, and transition events. Events fire for every level of the active chain (composite + leaf), in entry / exit order.
Enter the initial state and install triggers. Idempotent — a second call before stop is a no-op. If the declared initial state is composite, descends through initial substates to reach the leaf. Registers with the enclosing AgentModel so it is cleaned up deterministically at end-of-replication even if the owning agent is never explicitly stopped.
Tear down all pending triggers across every active level and deregister from the AgentModel active-statechart registry. Leaves currentStateName reporting the last leaf for post-simulation inspection. Idempotent. Safe to call while the model is running (graceful stop) or between runs.