Persistence & Saves

SpaceDwarves is an idle game, so your progress is saved constantly and continues while you are away. Persistence is hybrid: every player has a fast local save in their browser, and VIP players additionally get a cloud save that syncs across devices. The whole game state is a single JSON document, wrapped in a small envelope that carries a version number and an integrity checksum.

For how saves tie into the moment-to-moment simulation, see the Core Loop.

The save envelope #

Your entire game — credits, dwarves, asteroids, buildings, research, quests, everything — is serialised into one object and wrapped:

{
  "version": 8,
  "lastSaveTimestamp": 1719590400000,
  "checksum": "a1b2c3d4",
  "gameState": { "credits": 12345, "dwarves": { }, "asteroids": [ ] }
}

Versioning & migrations #

When the game updates and the schema changes, the version number is bumped. On load, if your save’s version is older than the current one, a chain of migration functions runs in sequence (v1→v2, v2→v3, … up to the current version) to bring it up to date, and the upgraded save is written back immediately. The current build ships migrations all the way from version 1 to version 8.

If a save is unreadable, has no game state, or a migration fails, the game falls back to starting a fresh colony rather than loading corrupt data. A checksum mismatch only logs a warning — the game still attempts to load, so minor corruption is recoverable.

Local saves (everyone) #

Every player gets a local save with no account required:

• Stored in the browser under the key sdmc_save_v1.
• Primary storage is localStorage. If a save grows past roughly 4 MB, or if localStorage is full, the game automatically falls back to IndexedDB (which handles much larger data) and clears the stale localStorage copy.
• Autosave is debounced to write at most once every 30 seconds, plus on key events.
• Loads are local-first: the game reads your local save before any network activity, so it starts instantly and works fully offline.

Local saves are tied to one browser on one device. Clearing your browser data, switching devices, or using a different browser means starting over — unless you have a VIP cloud save.

Cloud saves (VIP) #

VIP players get a server-side cloud save on top of the local one. The local save always remains the fast fallback; the cloud is the cross-device backbone.

• Cloud autosave is debounced separately and rate-limited to at most one push every 60 seconds.
• Cloud writes are gated until the initial reconcile has run, so a fresh device can never blindly overwrite the account’s real progress.
• Save size limit: the server rejects any cloud save larger than 2 MB (2,097,152 bytes) with a “save too large” error. (The local 4 MB threshold is just the localStorage→IndexedDB switch point and is separate from this server limit.)
• The server stores the blob as-is and never re-simulates it. The stored checksum is kept verbatim for corruption detection.

Cross-device sync & conflict resolution #

When a VIP player loads on a device, the game reconciles the local save against the cloud save:

The conflict prompt shows a summary of each save (credits, dwarves, asteroids, save time, version) so you can pick the right one. There is also an anti-data-loss safeguard: a low-progress local save (e.g. a brand-new game on a second device) will not silently clobber a richer cloud save just because a device clock is ahead.

To prevent two devices fighting over one save, the cloud push uses a blind-overwrite guard: each push tells the server which cloud version it last saw. If another device wrote in the meantime, the server returns a conflict, and the current device locks itself read-only rather than overwriting the newer save.

Sync Now #

The account/settings UI exposes a Sync Now button for VIP players that forces an immediate cloud push, bypassing the normal autosave debounce. It also:

• Runs the initial reconcile first if it hasn’t happened yet (which may pull a newer cloud save and reload the page).
• Refreshes the local save at the same time.
• Is subject to a 2-minute cooldown between presses (enforced by the UI) to avoid hammering the server.

If cloud sync isn’t available — you’re not VIP, another device currently owns the save, or the cloud is briefly unreachable — Sync Now returns a clear reason instead of risking your data.

Offline progress #

Because SpaceDwarves keeps running while you’re gone, the game fast-forwards elapsed time the next time you load.

• When you return, the game computes how long you were away and replays that time in 60-second chunks so even very long absences resolve quickly without freezing the tab.
• Offline gains use a diminishing-returns curve rather than a flat rate, so the value of being away tapers off the longer you’re gone (a 24-hour half-life curve).
• The effective offline window starts at a base of 8 hours and can be raised through Guild Administration research, up to an absolute hard ceiling of 72 hours. No matter how long you’re away, offline progress never counts more than 72 hours.
• Wall-clock timers (builds, recovery, research) resolve once per load, not per chunk, so reloading repeatedly gives no advantage.

Free vs. VIP persistence #

Cloud saving and cross-device play are the headline VIP perks; everything else about persistence — including the full offline simulation — is identical for free and VIP players.

Tuning note: the offline cap curve and the 8 h / 72 h bounds are first-pass values and may be retuned in future updates.