Save — Teaching Panels¶
The Teaching folder contains IMGUI-based panels used for learning, debugging, and validating the save coordinator directly in-scene.
These panels act as hostile consumers — they use only the public API and demonstrate real behaviour without shortcuts.
Status: Teaching / development-only UI (not for production) Define Guard:
REV_TEACHABLES
⚠️ Teaching panels are not stripped automatically. Leaving them in a shipped scene will expose them at runtime.
Panel Overview¶
| Panel | Focus | Notes |
|---|---|---|
| SaveCoordinatorPanel | Capture / restore across participants | Failure isolation, carry-over, version refusal |
What the panel demonstrates¶
- Capturing and restoring across several participants at once
- Failure isolation — one participant throwing does not stop the others
- Carry-over of unrecognised sections — data belonging to a participant that is not in the scene survives a save/load round trip instead of being quietly dropped
- Refusal of a newer save version than the participant understands
What it does not demonstrate, and why it matters¶
The panel is a first hour, not a specification. Two parts of the coordinator's contract are load-bearing for real persistence and are not visible in it. If you are building save/load from this panel alone, read this section as well.
Unapplied versus PartiallyApplied¶
When a participant's Restore throws, the coordinator sorts the section into one of two buckets, and the difference decides whether you may keep the data:
| Bucket | What happened | What you may do with it |
|---|---|---|
RevSaveReport.Unapplied | The participant threw before applying anything. The section is still exactly what the save said. | Safe to carry into the next save. Otherwise it exists only until the catch block ends, and the next save overwrites it with no record of the loss. |
RevSaveReport.PartiallyApplied | The participant threw after applying some of it. Part of that section is live state now. | Do not carry it over. Writing it into a later save would overwrite the owners that did load correctly. |
A report that only told you "this section failed" could not support either decision. That is why the two exist as separate collections rather than one failure list — and why treating them alike is the mistake worth naming here.
Related: RevSaveReport.Displaced reports a carried-over section dropped because a live participant wrote the same key. For a section carried from Unapplied, that is the moment the older copy stops existing anywhere, which is precisely why it is reported rather than dropped in silence.
Version migration¶
The panel shows the coordinator refusing a save newer than the participant understands. It does not show the other direction: loading an older section and migrating it forward. Restore receives the section's version alongside its payload for exactly that purpose — reading it and upgrading old payloads in place is the participant's job, and it is the normal case in a shipped game that has released more than once.
Related resources¶
Documentation/Save/— the coordinator's guarantees, report structure, and participant contractRuntime/Core/Save/—RevSaveCoordinator,RevSaveReport, and the participant interface