Runtime
Events and Event Order
Connect UnityEvents and typed C# events at their documented transition without replaying historical notifications.
Manager notifications
| Event | Exact point | What it does not mean |
|---|---|---|
| OnManagerReady | After initial hydration and startup selection have been attempted | It does not guarantee a valid Chapter was found |
| OnBeforeSceneLoad | After IsTransitioning becomes true, before optional handoff write and SceneManager.LoadScene | It is not an async loading barrier and must not start another transition |
| ChapterFailed | After Chapter and affected Objective failure states are final | It does not restart, save, or load |
| OnFailure | Immediately after typed ChapterFailed | It carries no typed context |
Use ChapterFailed when code needs Chapter, Objective, and reason. Use the serialized On Failure for inspector-owned responses that do not need parameters.
Chapter and Ordered Objective notifications
- On Chapter StartRuns after the Chapter becomes Active and before the first eligible row's delayed start work.
- On Objective StartRuns after start transport and object activation/deactivation, once delay and external animation gates release.
- ObjectiveCompleted(index)Typed Chapter event raised immediately before accepted completion actions for that index.
- On Objective CompletionRuns after terminal state persistence and completion object activation/deactivation, before completion transport and audio.
- Objective component OnCompletedRuns after the Chapter has completed and advanced the linked row; it belongs to the scene detector.
- On Chapter CompletionRuns after Chapter completion persistence and before Manager audio/transition handling.
Because Objective.TryComplete() calls into the Chapter first, the Chapter can advance before the component's own OnCompleted listener executes. Query the Manager deliberately if a listener needs the former versus the new current Objective.
Hydration never replays history
Restoring Completed or Skipped state does not invoke Objective start, Objective completion, component OnCompleted, Chapter completion, failure, or audio feedback. Hydration reconstructs a current snapshot, not an event log. Subscribe to future transitions and render the initial state separately after OnManagerReady.
The same rule applies to named boolean progression states read by the Manager: a read populates a cache; it is not a “state changed” event. ProgressionStateController has its own configured On Loaded behavior, which is a separate helper contract.
Subscribe and unsubscribe symmetrically
- Cache the exact Manager or Chapter instance used for subscription.
- Add typed or UnityEvent listeners once in OnEnable and remove the same delegate in OnDisable.
- Rebind Chapter-specific listeners after Chapter selection changes.
- Do not assume a singleton lookup during teardown returns the original instance.
- Keep callbacks idempotent when scene unload and object disable can occur close together.
Compiled examples are available in Listen to Events Safely.