farworld-labs/remix-save-game

Integrate Save Game State Workflow

Overview

This skill guides you through integrating save game state into an HTML game on the Remix platform. Save game state lets players persist progress across sessions -- scores, unlocked levels, inventory, and more -- using the RemixSDK.

Prerequisites

• The game must include the RemixSDK script tag:

  <script src="https://cdn.jsdelivr.net/npm/@remix-gg/sdk@latest/dist/index.min.js"></script>
  

• The game must already be playable (follow the game-creation workflow first if starting from scratch).

Steps

1. Initialize the SDK

Call await window.RemixSDK.ready() before the game loop starts. This ensures the SDK is loaded and any existing saved state is available.

await window.RemixSDK.ready();

2. Load Existing State

Read window.RemixSDK.gameState to get previously saved data. It returns Record<string, unknown> | null | undefined -- always check for null before using it.

const savedState = window.RemixSDK.gameState;

Use the saved state to restore game progress, or fall back to defaults if the player is starting fresh:

const state = savedState ?? { score: 0, level: 1 };

3. Save State During Gameplay

Call saveGameState whenever the player reaches a meaningful checkpoint. The gameState value must be a JSON-serializable object.

window.RemixSDK.singlePlayer.actions.saveGameState({
  gameState: { score: player.score, level: player.level },
});

Examples

Simple Clicker Game

<script>
  let clicks = 0;

  async function init() {
    await window.RemixSDK.ready();

    // Load
    const gameState = window.RemixSDK.gameState;
    if (gameState && typeof gameState.clicks === "number") {
      clicks = gameState.clicks;
    }

    document.getElementById("count").textContent = clicks;
    document.getElementById("btn").addEventListener("click", () => {
      clicks++;
      document.getElementById("count").textContent = clicks;

      // Save after every click
      window.RemixSDK.singlePlayer.actions.saveGameState({
        gameState: { clicks },
      });
    });
  }

  init();
</script>

Platformer with Level Progression

<script>
  let level = 1;
  let coins = 0;

  async function init() {
    await window.RemixSDK.ready();

    // Load
    const saved = window.RemixSDK.gameState;
    if (saved) {
      level = saved.level ?? 1;
      coins = saved.coins ?? 0;
    }

    startLevel(level);
  }

  function onLevelComplete() {
    level++;
    coins += 10;

    // Save at level transitions
    window.RemixSDK.singlePlayer.actions.saveGameState({
      gameState: { level, coins },
    });

    startLevel(level);
  }

  init();
</script>

Tips

• Keep state small. Only save what's needed to restore the session -- avoid storing large arrays or transient UI state.
• Save at meaningful moments -- level completion, checkpoints, purchases -- not every frame.
• State must be JSON-serializable. No functions, class instances, or circular references.
• Always guard against null. The first time a player loads the game there is no saved state.