Runtime
Progress State Persistence
Know what is written, when it is hydrated, which terminal states survive Play sessions, and what Flush actually guarantees.
Progress storage is intentionally lightweight
The Manager stores terminal Chapter and Objective progression, named boolean states, and one-use scene handoff data. It does not serialize scenes, GameObjects, transforms, inventory, dialogue variables, health, or arbitrary project data. The default backend is PlayerPrefsProgressStore; projects can install another exact-key IProgressStore before progression initialization locks configuration.
Keys are scoped by Progress Scope ID and Profile ID. The default scope is initialized from Application.identifier; profile defaults to default. V1 exposes a profile namespace, not a complete save-slot UI or manifest of removed content.
What is written and restored
| Record | Written when | Restored |
|---|---|---|
| Objective Completed | Accepted normal completion | Yes, without historical events |
| Objective Skipped | Condition fails or completion is requested without actions | Yes, without historical events |
| Objective Active | Never | No |
| Objective Failed | Never | No |
| Chapter Completed | All rows become terminal | Yes |
| Named boolean true | SetProgressState(id, true) | Yes |
| Named boolean false | The exact key is deleted | Missing and false read the same through public boolean API |
| Handoff | Transition includes a target Chapter | Consumed once, then deleted and flushed |
Writes, Flush, and Clear are different operations
Accepted Objective and Chapter transitions write incrementally. SetProgressState writes or deletes one named state. These operations do not automatically call Flush. FlushProgress() asks the current backend to commit pending writes/deletions exactly once; it creates no keys and captures no new world state. Scene handoff writes are flushed before load.
ClearProgress() deletes keys derivable from the Manager's currently known Chapters, Objectives, named state IDs seen this run, and the current handoff; it resets in-memory Chapter state and flushes once. It never calls PlayerPrefs.DeleteAll. Keys belonging to content removed from the current build cannot be enumerated in V1 and may require a project migration.
Hydration and backend failures
Hydration validates schema, opaque tokens, and destination IDs. Completed/Skipped state is applied without audio or lifecycle replay. A completed Chapter record with a nonterminal Objective set is considered inconsistent: the record remains stored, a warning is emitted, and the Chapter resumes from its first nonterminal position.
Public storage commands return ProgressOperationResult: Success, InvalidIdentifier, StoreUnavailable, StoreError, UnsupportedSchema, or ManagerAlreadyInitialized. Backend exceptions are caught at the Manager boundary and reported as StoreError. Treat a failed result as a real persistence failure; do not display “saved” merely because gameplay state advanced.
Persistence acceptance test
- 1Clear the current profile and start a Chapter with at least three Objectives.
- 2Complete the first and cause the second to be Skipped through a false condition. Leave the third Active.
- 3Call FlushProgress and require
ProgressOperationResult.Success. - 4Exit and re-enter Play Mode. Completed and Skipped must be restored; Active must not be restored as a terminal historical state.
- 5Confirm historical completion audio and events did not fire. The Chapter may resume its first nonterminal row and invoke only current start behavior.