Save / Load State

The Save/Load State API captures a compass’ runtime state — fog of war, the active route, visited POIs, runtime-created POIs and the mini-map view — into a compact blob you store in your own save file, and restores it later. It saves what changes at runtime, not the settings you configure in the inspector (those live in your scene or prefab).

Quick start

SaveState returns a byte[] you persist however you like; pass it back to LoadState once the compass and its POIs are initialized (e.g. after the scene has loaded).

using CompassNavigatorPro;
using System.IO;

// Save
byte[] data = CompassPro.instance.SaveState();
File.WriteAllBytes(path, data);

// Load (after the compass and POIs exist in the scene)
CompassLoadResult result = CompassPro.instance.LoadState(File.ReadAllBytes(path));
if (result.ok) Debug.Log($"Restored {result.poisRestored}, recreated {result.poisRecreated}");

What gets saved

Pick subsystems with the CompassSaveScope bitmask (default is All):

• Fog — fog of war discovery state.
• Route — the active route and its progress.
• POIVisited — per-POI visited flags.
• RuntimePOIs — POIs created at runtime (recreated on load).
• MiniMapView — zoom level, follow offset and full-screen state.

var options = new CompassSaveOptions { scope = CompassSaveScope.Fog | CompassSaveScope.POIVisited };
byte[] data = CompassPro.instance.SaveState(options);

API

Instance methods (a single compass):

• byte[] SaveState(CompassSaveOptions options = null) — compact binary blob; empty array if there is nothing to save.
• CompassLoadResult LoadState(byte[] data, CompassSaveOptions options = null)
• string SaveStateJson(...) / CompassLoadResult LoadStateJson(string json, ...) — human-readable JSON (larger; fog payload is base64’d).

Static methods restore every compass in the scene at once (e.g. split-screen); compasses are matched by group:

• static byte[] CompassPro.SaveStateAll(...)
• static CompassLoadResult CompassPro.LoadStateAll(byte[] data, ...)

CompassSaveOptions

• scope — which subsystems to save or load (default CompassSaveScope.All).
• fireEventsOnLoad — when true, a load replays gameplay events (OnPOIVisited, route and full-screen events…). Default false so restoring state does not re-trigger discovery audio, text or quests.

CompassLoadResult

Inspect the returned struct to know what happened:

• ok / error — success flag and message.
• poisRestored — existing POIs matched and updated.
• poisRecreated — runtime POIs rebuilt.
• poisUnmatched — saved POIs with no match in the scene (skipped).
• warning — non-fatal notes.

POI identity & runtime POIs

POIs are matched on load by their stableId (auto-assigned and persistent). Scene POIs are matched and updated; POIs created at runtime are recreated. To control how a runtime POI is rebuilt (prefab, components), implement ICompassPOIFactory and register it with compass.SetPOIFactory(factory) before loading; otherwise the compass creates a bare GameObject and configures the CompassProPOI from the saved descriptor.

Demo

The Save/Load State API is showcased in the main demo scene via the LevelManager component: press F5 to save and F9 to load. The state is written to Application.persistentDataPath so it survives a play-session restart.

Notes

• Call LoadState after the compass and its POIs are initialized.
• The binary format is versioned; loading a blob newer than the runtime supports fails gracefully via CompassLoadResult.error.
• Inspector settings are part of your scene or prefab and are not included in the blob.