Scene component shows Missing
Cause: its stored Objective ID no longer resolves. Confirm: open Objective Link and compare the selected Chapter list. Fix: choose the intended row with the assisted selector. Prevent: keep shipped IDs stable.
Troubleshooting & Reference
Common Problems
Diagnose setup and execution failures by symptom, probable cause, confirmation, correction, and prevention.
Authoring symptoms
Duplicate Binding warning
Cause: more than one scene Objective claims one row. Confirm: select each reported component. Fix: remove or relink accidental copies. Prevent: duplicate row and component as one deliberate operation.
Chapter has no completion path
Cause: empty lifecycle data and no identifiable detector or external contract. Fix: add a real completion source; do not add dummy listeners merely to silence Validation.
Runtime progression symptoms
TryComplete returns false
Confirm: Manager exists, Chapter and row are Active, and the expected ID equals CurrentObjectiveId exactly. Fix: repair link or callback timing. Prevent: inspect results and guard stale callbacks.
Objective is Active but start effects are absent
Confirm: Start Delay and Wait For External Animation. Fix: emit the correct animation-release signal or wait for the unscaled delay.
Row was skipped
Confirm: required true/false states at the moment the Chapter reached it. Fix: write the intended named state before evaluation.
Chapter completes unexpectedly
Confirm: every row is Completed or Skipped. A false condition is a terminal skip, not a pause.
Transition and persistence symptoms
Reload starts the wrong Chapter
Confirm: completion action, target IDs, destination Manager, and progress warnings. Fix: use Load Scene and Start Chapter or Restore Checkpoint; plain Load Scene intentionally uses destination startup rules.
Completed events replay after restart
Core does not do this during hydration. Inspect project code that manually invokes responses from restored state.
Progress appears not durable
Require Success from writes and FlushProgress; test the active backend. Flush does not capture unrelated project data.
Clear leaves an old removed-content key
V1 deletes currently derivable keys only. Migrate or clear legacy backend data through project-owned tooling.
Editor, Demo, and audio symptoms
Product menus are missing
Resolve the earliest C# compile error; Unity does not load editor assemblies after compilation failure.
Demo materials are incorrect
Confirm the sample's Built-in Render Pipeline requirements. Core progression is render-pipeline independent.
No Objective sound
Enable Play Completion Sound and confirm normal accepted completion. Step-back suppresses it.
No clip is assigned but audio plays
Expected: ChapterAudioPlayer creates built-in procedural example cues.
When reporting an unresolved problem, use Support to capture a minimal reproducible case.