Simulation Lifecycle
The simulation engine follows a well-defined state machine.
State Diagram
init() run()
[idle] -------> [idle] -------> [running]
| | \
pause()| |stop() \---> [finished]
v v (natural end)
[paused] [stopped]
| |
resume()| reset()|
| v
[running] [idle]States
| State | Allowed Transitions | Description |
|---|---|---|
idle | init() → idle, run() → running | Initial state. Call init() to seed entities and first events. |
running | pause() → paused, stop() → stopped, natural end → finished | Main loop executing. |
paused | resume() → running, stop() → stopped | Loop suspended, full state preserved. |
stopped | reset() → idle | Terminal. Cannot resume. |
finished | reset() → idle | Natural termination (queue empty or limit reached). |
Methods
sim.run()
Runs the simulation synchronously until completion.
sim.runAsync()
Runs the simulation asynchronously, yielding to the Node.js event loop periodically.
sim.pause() / sim.resume()
Suspend and resume a running simulation. Full state is preserved.
sim.stop()
Terminal stop. Cannot be resumed — only reset() can bring it back to idle.
sim.reset()
Clears clock, queue, entities, stats, and store. Handlers and hooks are preserved.
Last updated on