Save and Load Game Progress Without Losing Data

What you will learn

Build a versioned save, validate it before loading and handle unavailable storage without breaking play.

1. Extract into a new folder and run node check.mjs from that folder.
2. For the browser games, run python3 -m http.server 8080 with Python 3 and open http://localhost:8080/index.html. Do not open modules with file://.
3. Read the full setup instructions and the original code licence. Keep your existing game on a separate test branch.

The JavaScript behaviour checks and native C comparison can run independently of the browser. Ghidra UI, physical-phone and your engine integration are separate checks. This is a small reference, not a certification of your project.

Explore the related game idea · Start with Build a Game · Improve your existing game

Five practical steps

1. Define the smallest save

   Open systems.mjs and read readSave. Save version, coins and a stable room ID. Keep textures, scene nodes, functions and account credentials out of the record. A save describes progress; the game recreates its objects from that data.

   Expected result: A plain JSON record: {"version":1,"coins":12,"room":"room-a"}.

   Check it: Parse that record; the returned object contains exactly those three fields.

   readSaveObserve the inputs → check the state → compare the result

2. Validate before touching the world

   Parse into a temporary value and enforce the supported version, integer range and allowed room IDs. Only assign the validated result to live game state after every check passes. Unknown future versions must not silently reset a valuable save.

   Expected result: A failed load leaves the current session intact.

   Check it: Try truncated JSON, version 2, coins -1, 1.5 and an unknown room; all fail.

3. Connect a deliberate save action

   In a browser project, call localStorage.setItem with JSON.stringify inside try/catch. Save on a checkpoint or an explicit button, not every animation frame. Report success only after storage accepts the write. Godot projects instead adapt the linked FileAccess tutorial.

   Expected result: A clear Saved or Could not save message; play continues either way.

   Check it: Replace setItem with a function that throws and confirm movement and pause still work.

4. Restore after a clean restart

   Read the key, validate its content, reconstruct the room and show a paused confirmation screen. If no record exists, offer New game. Keep a previous known-good record when adding schema migrations; test a copied save before changing its version.

   Expected result: Loading places the player in the recorded room with the expected coins.

   Check it: Save 12 coins in room-a, reload, and compare both fields; corrupt a copy and verify a useful error.

5. Choose storage for your actual target

   Browser local storage belongs to an origin and can be cleared or unavailable. Desktop engine saves use platform-specific writable paths. Cloud saves require identity, server rules and conflict handling; they are a separate feature from this local exercise.

   Expected result: A documented storage location and honest persistence limits.

   Check it: Test the exported game, private browsing, quota failure and a changed host; never promise permanent storage.

Read and reuse the actual code

systems.mjs: complete source · Standalone behavioural checks · Shared browser runner and input. Original BINX Forge code, MIT; the package includes every required file and its notice.

// Original BINX Forge practice code. MIT; see LICENSE.txt.
export function readSave(raw) {
  const s = JSON.parse(raw);
  if (!s || s.version !== 1 || !Number.isInteger(s.coins) || s.coins < 0 || s.coins > 9999 || !['room-a','room-b'].includes(s.room)) throw Error('Invalid save');
  return {version:1, coins:s.coins, room:s.room};
}
export function transfer(from, to, id, count, capacity=10) {
  if (!Number.isInteger(count) || count < 1 || !Number.isInteger(from[id]) || from[id] < count || Object.values(to).reduce((a,b)=>a+b,0)+count > capacity) return false;
  from[id]-=count; to[id]=(to[id]||0)+count; return true;
}
export function pointerInput() {
  const owners=new Map();
  return {press:(id,action)=>owners.set(id,action),release:id=>owners.delete(id),clear:()=>owners.clear(),held:action=>[...owners.values()].includes(action)};
}
export function enemyMode(distance, hp, cooldown) {
  if (hp<=0) return 'dead';
  if (cooldown>0) return 'recover';
  if (distance<24) return 'attack';
  return distance<180?'chase':'idle';
}
export function frameSummary(samples) {
  const s=samples.filter(Number.isFinite).filter(x=>x>=0).sort((a,b)=>a-b);
  if (!s.length) throw Error('No samples');
  return {median:s[Math.floor((s.length-1)*.5)],p95:s[Math.ceil(s.length*.95)-1],count:s.length};
}
export function fixedStep(clock, elapsed, update) {
  clock.carry+=Math.max(0,Math.min(.1,elapsed));
  while(clock.carry>=1/60){update(1/60);clock.carry-=1/60;}
}
// Owned protocol specimen: version:u8, coins:u16 little-endian, room:u8.
export function decodeRecord(bytes) {
  if(bytes.length!==4)throw Error('Expected four bytes');
  const v=new DataView(bytes.buffer,bytes.byteOffset,bytes.byteLength);
  if(v.getUint8(0)!==1||v.getUint8(3)>1)throw Error('Unknown record');
  return {version:1,coins:v.getUint16(1,true),room:v.getUint8(3)};
}
export function applyInput(player, packet) {
  if(!packet||!Number.isInteger(packet.seq)||packet.seq<=player.seq||![-1,0,1].includes(packet.dx))return false;
  player.seq=packet.seq;player.x=Math.max(0,Math.min(100,player.x+packet.dx*2));return true;
}
export function jumpTrace(speed=300,gravity=900,dt=1/120) {
  let y=0,vy=-speed,t=0,peak=0;
  const rows=[{t,y,vy}];
  while(t<3){vy+=gravity*dt;y+=vy*dt;t+=dt;peak=Math.min(peak,y);rows.push({t,y,vy});if(y>=0)break;}
  return {rows,height:-peak,airtime:t};
}

Code rights: the included MIT notice permits use, modification and distribution, including commercial games and source products, with the copyright and licence notice. Added third-party files have their own terms. Read the official licence & usage terms.

Common failures and fixes

Make Your Game Better

Change one system after the baseline works. Keep the free reference and compare the same inputs before and after.

Optional building blocks from original creators

ScreenshotFree

Godot Engine contributors · Original screenshot ↗ · CC BY 4.0 ↗. Resized and compressed.

Godot Engine contributors

Godot

Free, open-source game editor for 2D and 3D projects, with scene, animation and interface tools.

MITEngine

Official licence ↗Licensing summary, not legal advice. Check the exact edition and use.

See previews & details

Creator previewFree

Kenney

UI Pack

Interface artwork for buttons, panels and sliders.

CC0-1.0Asset pack

Official licence ↗Licensing summary, not legal advice. Check the exact edition and use.

See previews & details

Inspect exact formats and editions on each resource page. Pay for a resource only when it fills an identified gap; the free code exercise needs no paid engine or pack.

Licensing summary, not legal advice. Before publishing or selling, check exact terms for finished-game use, reselling files and including files in a source/template product separately.

Keep learning