@remix-gg/mcp 0.4.3

package/skills/workflows/implement-multiplayer.md

@@ -0,0 +1,355 @@
+# Implement Multiplayer Workflow
+
+## Overview
+
+This skill guides you through integrating turn-based multiplayer into an HTML
+game on the Remix platform. Multiplayer games use the RemixSDK's `multiplayer`
+namespace instead of `singlePlayer`. Games are two-player and fully turn-based.
+
+## Prerequisites
+
+- The game must include the RemixSDK script tag:
+  ```html
+  <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).
+- The `REMIX_API_KEY` environment variable must be set.
+- `.remix-settings.json` must contain a `gameId`.
+
+## Constraints
+
+- Multiplayer is **2-player only**. Do not design for more than two players.
+- All games must be **fully turn-based**. Real-time multiplayer is not supported.
+
+## Steps
+
+### 1. Check `.remix-settings.json`
+
+Read the file and extract `gameId`. If it is missing, follow the
+**game-creation** workflow first to create and register the game.
+
+### 2. Mark the Game as Multiplayer
+
+Call the `updateGame` tool with the `gameId` and `isMultiplayer: true`. This
+registers the game as multiplayer on the platform.
+
+```
+updateGame({ gameId: "<gameId>", isMultiplayer: true })
+```
+
+### 3. Initialize the SDK and Check for Existing Game State
+
+Call `await window.RemixSDK.ready()` before the game loop starts. Then check
+`window.RemixSDK.gameState` to restore in-progress matches. If state exists,
+resume the game from that state.
+
+```js
+await window.RemixSDK.ready();
+
+const savedState = window.RemixSDK.gameState;
+if (savedState) {
+  // Resume in-progress match from savedState
+}
+```
+
+### 4. Identify the Current Player and Opponent
+
+Use `window.RemixSDK.player` for the current player and
+`window.RemixSDK.players` for all players. Derive the opponent:
+
+```js
+const player = window.RemixSDK.player;
+const players = window.RemixSDK.players;
+const opponent = players.find(p => p.id !== player.id);
+```
+
+**Important:** The first player in the `players` array (`players[0]`) is always
+the player who should act first in a new game. Use this ordering to determine
+who takes the opening turn rather than sorting or randomizing.
+
+### 5. Display Player Names and Avatars
+
+Each `Player` object has a `name` (string) and an optional `imageUrl` (string)
+for the player's avatar. Use these to personalize the game UI.
+
+```js
+const player = window.RemixSDK.player;
+const opponent = players.find(p => p.id !== player.id);
+
+// Access name and avatar
+player.name;      // e.g. "Alice"
+player.imageUrl;  // e.g. "https://…/avatar.png" or undefined
+opponent.name;
+opponent.imageUrl;
+```
+
+Display names in status messages so players know who they are playing against:
+
+```js
+statusEl.textContent = isMyTurn
+  ? `Your turn, ${player.name}`
+  : `Waiting for ${opponent.name}…`;
+```
+
+Show avatars with a fallback for when `imageUrl` is missing:
+
+```html
+<div class="player-info">
+  <img src="${player.imageUrl}" alt="${player.name}"
+       onerror="this.style.display='none'; this.nextElementSibling.style.display='flex'">
+  <div class="avatar-fallback" style="display:none">${player.name[0]}</div>
+  <span>${player.name}</span>
+</div>
+```
+
+### 6. Save Game State After Each Turn
+
+Use `multiplayer.actions.saveGameState` with `alertUserIds` containing the
+opponent's ID so they are notified it is their turn:
+
+```js
+window.RemixSDK.multiplayer.actions.saveGameState({
+  gameState: { /* current board/game state */ },
+  alertUserIds: [opponent.id],
+});
+```
+
+### 7. Listen for Opponent's Moves
+
+Register `onGameStateUpdated` to handle incoming state changes from the
+opponent:
+
+```js
+window.RemixSDK.onGameStateUpdated((data) => {
+  if (!data) return;
+  const { id, gameState } = data;
+  // Validate and apply the new state
+
+  // If the move is invalid, refute it:
+  // window.RemixSDK.multiplayer.actions.refuteGameState({ gameStateId: id });
+});
+```
+
+### 8. End the Game with Multiplayer gameOver
+
+Report scores for both players using `multiplayer.actions.gameOver`:
+
+```js
+window.RemixSDK.multiplayer.actions.gameOver({
+  scores: [
+    { playerId: player.id, score: playerScore },
+    { playerId: opponent.id, score: opponentScore },
+  ],
+});
+```
+
+### 9. Handle Play Again and Mute
+
+Register `onPlayAgain` and `onToggleMute` callbacks — same as single player:
+
+```js
+window.RemixSDK.onPlayAgain(() => {
+  // Reset game state and start a new match
+});
+
+window.RemixSDK.onToggleMute(({ isMuted }) => {
+  // Mute or unmute audio
+});
+```
+
+## Examples
+
+### Tic-Tac-Toe
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Tic-Tac-Toe</title>
+  <script src="https://cdn.jsdelivr.net/npm/@remix-gg/sdk@latest/dist/index.min.js"></script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { width: 100vw; height: 100vh; display: flex; flex-direction: column;
+           align-items: center; justify-content: center; font-family: sans-serif;
+           background: #1a1a2e; color: #eee; }
+    #status { margin-bottom: 16px; font-size: 1.2rem; }
+    #board { display: grid; grid-template-columns: repeat(3, 100px);
+             grid-template-rows: repeat(3, 100px); gap: 4px; }
+    .cell { background: #16213e; display: flex; align-items: center;
+            justify-content: center; font-size: 2.5rem; cursor: pointer;
+            border-radius: 4px; }
+    .cell:hover { background: #0f3460; }
+    #players { display: flex; gap: 24px; margin-bottom: 12px; }
+    .player-info { display: flex; align-items: center; gap: 8px; }
+    .player-info img { width: 32px; height: 32px; border-radius: 50%; }
+    .avatar-fallback { width: 32px; height: 32px; border-radius: 50%;
+                       background: #0f3460; display: flex; align-items: center;
+                       justify-content: center; font-size: 0.9rem; font-weight: bold; }
+  </style>
+</head>
+<body>
+  <div id="players"></div>
+  <div id="status">Loading…</div>
+  <div id="board"></div>
+  <script>
+    let board = Array(9).fill(null);
+    let player, opponent, mySymbol, isMyTurn;
+    const playersEl = document.getElementById("players");
+    const statusEl = document.getElementById("status");
+    const boardEl = document.getElementById("board");
+
+    function avatarHTML(p) {
+      if (p.imageUrl) {
+        return `<img src="${p.imageUrl}" alt="${p.name}"
+                  onerror="this.style.display='none';this.nextElementSibling.style.display='flex'">
+                <div class="avatar-fallback" style="display:none">${p.name[0]}</div>`;
+      }
+      return `<div class="avatar-fallback">${p.name[0]}</div>`;
+    }
+
+    function renderPlayers() {
+      if (!player || !opponent) return;
+      playersEl.innerHTML = [player, opponent].map(p =>
+        `<div class="player-info">${avatarHTML(p)}<span>${p.name}</span></div>`
+      ).join("");
+    }
+
+    function render() {
+      boardEl.innerHTML = "";
+      board.forEach((val, i) => {
+        const cell = document.createElement("div");
+        cell.className = "cell";
+        cell.textContent = val ?? "";
+        cell.addEventListener("click", () => handleClick(i));
+        boardEl.appendChild(cell);
+      });
+      statusEl.textContent = isMyTurn
+        ? `Your turn, ${player.name}`
+        : `Waiting for ${opponent.name}…`;
+    }
+
+    function checkWinner() {
+      const lines = [
+        [0,1,2],[3,4,5],[6,7,8],
+        [0,3,6],[1,4,7],[2,5,8],
+        [0,4,8],[2,4,6],
+      ];
+      for (const [a,b,c] of lines) {
+        if (board[a] && board[a] === board[b] && board[a] === board[c]) {
+          return board[a];
+        }
+      }
+      return board.every(Boolean) ? "draw" : null;
+    }
+
+    function handleClick(i) {
+      if (!isMyTurn || board[i]) return;
+      board[i] = mySymbol;
+      isMyTurn = false;
+      render();
+
+      const winner = checkWinner();
+      if (winner) {
+        endGame(winner);
+        return;
+      }
+
+      window.RemixSDK.multiplayer.actions.saveGameState({
+        gameState: { board, lastPlayer: player.id },
+        alertUserIds: [opponent.id],
+      });
+    }
+
+    function endGame(winner) {
+      const iWin = winner === mySymbol;
+      const isDraw = winner === "draw";
+      statusEl.textContent = isDraw ? "Draw!" : iWin ? "You win!" : "You lose!";
+      window.RemixSDK.multiplayer.actions.gameOver({
+        scores: [
+          { playerId: player.id, score: iWin ? 1 : 0 },
+          { playerId: opponent.id, score: !iWin && !isDraw ? 1 : 0 },
+        ],
+      });
+    }
+
+    async function init() {
+      await window.RemixSDK.ready();
+
+      player = window.RemixSDK.player;
+      const players = window.RemixSDK.players;
+      opponent = players.find(p => p.id !== player.id);
+
+      // First player in the array takes the first turn (X)
+      mySymbol = players[0].id === player.id ? "X" : "O";
+      renderPlayers();
+
+      // Restore in-progress match
+      const saved = window.RemixSDK.gameState;
+      if (saved && saved.board) {
+        board = saved.board;
+        isMyTurn = saved.lastPlayer !== player.id;
+      } else {
+        board = Array(9).fill(null);
+        isMyTurn = mySymbol === "X";
+      }
+
+      render();
+
+      window.RemixSDK.onGameStateUpdated((data) => {
+        if (!data) return;
+        const { gameState } = data;
+        board = gameState.board;
+        isMyTurn = gameState.lastPlayer !== player.id;
+        render();
+
+        const winner = checkWinner();
+        if (winner) endGame(winner);
+      });
+
+      window.RemixSDK.onPlayAgain(() => {
+        board = Array(9).fill(null);
+        isMyTurn = mySymbol === "X";
+        render();
+      });
+
+      window.RemixSDK.onToggleMute(({ isMuted }) => {
+        // No audio in this example
+      });
+    }
+
+    init();
+  </script>
+</body>
+</html>
+```
+
+## Wrong Patterns
+
+- **Using `singlePlayer.actions.gameOver`** instead of
+  `multiplayer.actions.gameOver` — scores will not be recorded for both players.
+- **Using `singlePlayer.actions.saveGameState`** instead of
+  `multiplayer.actions.saveGameState` — the opponent will not receive state
+  updates.
+- **Forgetting `alertUserIds`** when saving state — the opponent will not be
+  notified that it is their turn.
+- **Not checking `gameState` on startup** — breaks resuming in-progress matches.
+  Always check `window.RemixSDK.gameState` after `ready()`.
+- **Hardcoding player IDs** — always read from `window.RemixSDK.player` and
+  `window.RemixSDK.players`.
+- **Not showing player identity** — multiplayer games should display names and
+  avatars so players know who they are playing against.
+
+## Tips
+
+- **Keep state JSON-serializable.** No functions, class instances, or circular
+  references.
+- **Validate opponent moves.** Check that the incoming state is legal before
+  applying it. Use `refuteGameState` if a move is invalid.
+- **Save at turn boundaries**, not every frame.
+- **Assign symbols deterministically** — use `players[0]` as the first actor
+  (e.g. X) so both clients agree on who goes first.
+- **Handle missing `imageUrl`** — the field is optional; use a placeholder or
+  initials fallback when it is `undefined`.

package/skills/workflows/integrate-save-game.md

@@ -0,0 +1,135 @@
+# 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:
+  ```html
+  <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.
+
+```js
+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.
+
+```js
+const savedState = window.RemixSDK.gameState;
+```
+
+Use the saved state to restore game progress, or fall back to defaults if the
+player is starting fresh:
+
+```js
+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.
+
+```js
+window.RemixSDK.singlePlayer.actions.saveGameState({
+  gameState: { score: player.score, level: player.level },
+});
+```
+
+## Examples
+
+### Simple Clicker Game
+
+```html
+<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
+
+```html
+<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.