InstructionRunner — Loop Adventure Docs

ExecutionStatus

Enum representing the runner's current state.

Value	Description
`Uninitialized`	The runner has not been started yet.
`Stopped`	Execution was stopped manually via `Stop()`.
`Running`	Instructions are actively executing.
`Observing`	Running in observe mode (no validation, infinite loop).
`Finished`	All instructions completed — either success or failure.
`Fail`	Execution ended due to a validation failure or player death.
`Success`	All level goals were met and the player reached the end tile.

Properties

Property	Type	Description
`status`	`ExecutionStatus`	The runner's current execution state.
`context`	`ExecutionContext`	The active ExecutionContext for the current run. `null` when `status` is `Stopped` or `Uninitialized`.

Methods

Method	Description
`Play()`	Starts a full execution run. Calls each instruction's `Validate()` before execution and checks level goals at the end. Fires `OnStartExecution`.
`Observe()`	Starts execution in observe mode — instructions run in an infinite loop without validation or goal checking. Used to let designers preview behaviour. Fires `OnStartExecution`.
`Stop()`	Halts any running coroutine, resets `Time.timeScale` to 1, stops all scheduled tasks, and fires `OnStopExecution`.
`Reset()`	Calls `context.Reset()` to restore cloned game objects to their pre-run state, then fires `OnReset`.

Events

Event	Signature	Description
`OnTurnStart`	`Action`	Raised at the beginning of each turn cycle, before any instruction executes.
`OnTurnEnd`	`Action`	Raised at the end of each turn cycle, after all tasks complete.
`OnAnyTurnEnd`	`static Action`	Static version of `OnTurnEnd` — fired by every runner instance. Useful for systems that need to react to any turn ending regardless of which runner is active.
`OnReset`	`Action`	Raised after `Reset()` restores the scene to its pre-run state.
`OnStartExecution`	`Action<ExecutionContext>`	Raised when `Play()` or `Observe()` is called. The context passed is the one for this run.
`OnStopExecution`	`Action<ExecutionContext>`	Raised when `Stop()` is called manually. Not fired when the run ends naturally.
`OnFinishExecution`	`Action<ExecutionContext>`	Raised when the run ends — either with success or failure. Always fired after `OnSucceedExecution` or `OnFailedExecution`.
`OnFailedExecution`	`Action<ExecutionContext>`	Raised when an instruction signals failure (`resolution = false`) or the player dies mid-run.
`OnSucceedExecution`	`Action<ExecutionContext>`	Raised when all instructions complete without failure and all level goals are satisfied.

Turn Cycle

Each turn follows this sequence:

OnTurnStart fires.
All ITaskReceiver tasks in the context (enemies, interactables) are started in parallel via TaskSchedule.
The current instruction's Execute() is called, then Tick() runs as a coroutine.
The runner waits until both the instruction's coroutine and all parallel tasks finish.
OnTurnEnd and OnAnyTurnEnd fire.
Player health and position are validated. If invalid, Fail() is called.
Execution advances to the next instruction. When all instructions are exhausted, goals are evaluated.

InstructionRunner.TaskSchedule

Inner helper class created at the start of each run. It collects all ITaskReceiver objects from context.taskSchedulers (enemies, traps, interactables) and starts their tasks in parallel at the beginning of each turn. The runner waits for TaskSchedule.running to become false before advancing to the next turn.