Event model
Timing and state progression
Distinguish scheduled events, delayed results, and gradual changes.
Format definition
Specify deterministic scheduled events, repetition, cancellation, and clock semantics.
Portable format · Suite implementation support
Parameters
events.schedules[].id
ID
Required
Named event allows explicit cancellation.
events.schedules[].anchor
{ kind: scenario-start | state-entry | action-completion, refId?: ID }
Required
State/action anchors require the corresponding ID. Scenario-start prohibits refId.
events.schedules[].delaySeconds
positive number
Required
Simulated offset from each occurrence of the anchor; zero-time effects belong in the originating event.
events.schedules[].conditionId
Condition ID
Optional; omitted means unspecified
Evaluate when due. False skips that occurrence; it does not poll until true.
events.schedules[].priority
integer
Required; lower executes first
Explicit ordering for simultaneous events. Equal priority uses schedule ID lexical order.
events.schedules[].effectIds
Effect ID[]
Required; may be empty
Operations applied atomically if the due event and transition guards are valid.
events.schedules[].nextStateId
State ID
Optional; omitted means unspecified
Optional phase transition; omit for a result or actor cue that does not move the main phase.
events.schedules[].repeat
{ intervalSeconds: positive number, count: positive integer }
Optional; omission means one occurrence
Count includes the initial occurrence. Finite repetition prevents unbounded schedules.
events.schedules[].onAnchorStateExit
cancel | continue
Required only for state-entry anchors
Cancel removes pending occurrences from that entry; re-entry creates a new schedule instance.
Behavior and validation
- Time advances explicitly in simulated seconds, independent of wall time. At a timestamp: sample active trends, complete due actions ordered by action ID, then process schedules by priority and ID, then refresh disclosure conditions. Each operation sees prior committed operations at that instant.
- Every phase transition applies exit effects, originating event effects, then entry effects. Newly scheduled events must be strictly later. An operation targeting a canceled event is a recorded no-op. Repeated anchor occurrences have distinct runtime instance IDs.
- Reject cyclic instantaneous effect chains. A run engine must impose documented execution bounds and report a limit failure rather than silently skipping work.
Shared format conventions · All format elements · Download specification
Four clocks, four meanings
| Concept | Reference field | Recorded value |
|---|---|---|
| Scheduled state | Scenario start or specified state | time + timer_start |
| Vital-sign trend | Transition into changed values | 15s default |
| Encouragement | Delayed learner-facing content | 30s default |
| Object result delay | Action requests the object | delay time; no default |