Skip to content

04 — Snapshots

Goal

Learn the runtime persistence loop: capture live inventory state as JSON, save it, load it, and apply it back with an explicit missing-item policy.

What This Scene Demonstrates

The core snapshot flow:

Live runtime state → JSON snapshot → file → JSON snapshot → apply policy → restored runtime state

Seed and Clear All use SceneInventoryService. Snapshot capture and apply use InventorySnapshots. File tools use the resolved snapshot file path. Missing item behaviour is explicit.

This scene proves a minimal save/load workflow without pretending to be a complete production save system.

What To Look For

  • Seed Items uses GiveExact(...) to create real inventory state through the service
  • Snapshot Options controls snapshot name, equipment inclusion, and missing-item policy
  • Save captures live state as JSON and writes it to disk
  • Load reads JSON from disk and applies it using the configured options
  • Clear All clears the inventory container through SetAt(...) service writes
  • Autosave saves using the fixed autosave snapshot name
  • File Tools deletes, reveals, or opens the snapshot location
  • Last Result / Panel Summary explains what happened

If Include Equipment is enabled and CharacterEquipment is available, equipment is included in capture/apply. Clear All only clears the inventory container; equipment is intentionally left unchanged by this panel.

Sample Scope

This scene focuses only on:

  • Seeding inventory data
  • Capturing inventory and optional equipment state as JSON
  • Saving JSON to disk
  • Loading JSON from disk
  • Applying JSON back to live runtime state
  • Choosing missing-item behaviour
  • Clearing inventory through public service writes
  • Basic snapshot file tools

This scene does NOT cover:

  • Full production save systems
  • Save-slot UI
  • Cloud saves
  • Save versioning
  • Cross-session identity systems
  • Equipment clearing workflows
  • Networking or replication

Those behaviours are project-specific and should wrap or extend the snapshot helpers.

Authority Note

This scene may include a permissive sample authority setup. If no authority is resolved, mutations are allowed for demonstration purposes.

Networking Reminder

No networking is included. Multiplayer authority and synchronization are the developer’s responsibility.

How To Use

  1. Assign ItemDefinitions in Quick Items
  2. Press Give in Seed Items to create inventory state
  3. Set a Name in Snapshot Options
  4. Toggle Include Equipment if equipment should be captured and CharacterEquipment is available
  5. Toggle Placeholder Missing to choose the missing-item policy
  6. Press Save to capture JSON and write the snapshot file
  7. Press Clear All to clear the inventory container through service writes
  8. Press Load to read the JSON file and apply it back
  9. Use Autosave to save under the fixed autosave name
  10. Use Delete Snapshot, Reveal Snapshot, or Open Folder in File Tools as needed
  11. Read Last Result and Panel Summary after each action

Failure Behaviour

Failures and blocked actions are surfaced through InvOpResult, Panel Summary, or live feedback.

Common patterns:

  • Give fails → item assignment, container setup, capacity, filters, or authority → Check the assigned ItemDefinition, container id, available space, filters, or authority setup

  • Load fails because the snapshot is missing → no JSON file exists for the snapshot name → Save first, or enter an existing snapshot name

  • Load is blocked because SceneInventoryService.database is missing → item GUIDs cannot resolve back to ItemDefinitions → Assign an ItemDatabase on SceneInventoryService

  • Snapshot apply fails → JSON, database, item resolution, or snapshot data issue → Check the snapshot data, ItemDatabase, and missing-item policy

  • Clear All is blocked → no readable container view → Check the configured container id and CharacterInventory setup

  • Clear All fails → service, container id, or authority issue → Check authority, container id, and service setup

  • Delete Snapshot skips → the named snapshot file does not exist → Save first, or check the snapshot name

The panel does not silently guess missing items. The selected policy decides whether unresolved item GUIDs are skipped or substituted.

Behind The Scenes

This panel uses public snapshot helpers, service APIs, and public data types:

  • SceneInventoryService.GiveExact(...)
  • SceneInventoryService.Get(...)
  • SceneInventoryService.SetAt(...)
  • InventorySnapshots.CaptureJson(...)
  • InventorySnapshots.SaveJsonToFile(...)
  • InventorySnapshots.LoadJsonFromFile(...)
  • InventorySnapshots.ApplyJson(...)
  • InventorySnapshots.GetPath(...)
  • InventorySnapshotOptions
  • MissingItemPolicy.SubstitutePlaceholder
  • MissingItemPolicy.Skip
  • CharacterInventory
  • CharacterEquipment
  • ItemStack
  • ContainerId
  • InvOpResult

Snapshot APIs own capture/apply. Service writes own inventory seeding and clearing. File tools are learning/debugging helpers.

Key Takeaway

Snapshots are JSON-first persistence helpers. The panel captures live state, writes it to disk, loads it back, and applies it with an explicit policy. Nothing is silently invented when items are missing.

The storage layer stays inspectable and replaceable.