ms_next_turn

Instructions

Implementation Reference

• src/games/minesweeper.ts:308-335 (registration)

  Registration of the ms_next_turn tool via server.tool() with name 'ms_next_turn', description, empty schema, and async handler.

  server.tool(
    "ms_next_turn",
    "The Flufflings catch their breath and check in with the player. Resets the step counter and gives 8 fresh steps. Must be called after reaching the turn limit — chat first, then call this to continue the crossing.",
    {},
    async () => {
      if (msGame.status === "won" || msGame.status === "lost") {
        return { content: [{ type: "text", text: `The crossing is over (${msGame.status}). Call ms_new_game to try again.` }], isError: true };
      }
      if (msGame.status === "waiting") {
        return { content: [{ type: "text", text: `The Flufflings haven't started yet. Send the first scout with ms_reveal_cell.` }], isError: true };
      }
      if (msGame.status === "in_progress") {
        return { content: [{ type: "text", text: `The Flufflings are still moving (${msGame.movesThisTurn}/${msGame.maxMovesThisTurn} steps used). Finish the turn first.` }], isError: true };
      }
  
      msGame.status = "in_progress";
      msGame.movesThisTurn = 0;
      msGame.maxMovesThisTurn = MOVES_PER_TURN;
      msGame.turnNumber++;
  
      return {
        content: [{
          type: "text",
          text: `The Flufflings are ready again! Turn ${msGame.turnNumber} — ${MOVES_PER_TURN} steps available.\n\n${renderState(msGame)}`,
        }],
      };
    }
  );

• src/games/minesweeper.ts:312-335 (handler)

  The async handler function that implements the ms_next_turn logic. It checks game status, resets movesThisTurn to 0, sets maxMovesThisTurn to MOVES_PER_TURN (8), increments turnNumber, and returns the updated state.

    async () => {
      if (msGame.status === "won" || msGame.status === "lost") {
        return { content: [{ type: "text", text: `The crossing is over (${msGame.status}). Call ms_new_game to try again.` }], isError: true };
      }
      if (msGame.status === "waiting") {
        return { content: [{ type: "text", text: `The Flufflings haven't started yet. Send the first scout with ms_reveal_cell.` }], isError: true };
      }
      if (msGame.status === "in_progress") {
        return { content: [{ type: "text", text: `The Flufflings are still moving (${msGame.movesThisTurn}/${msGame.maxMovesThisTurn} steps used). Finish the turn first.` }], isError: true };
      }
  
      msGame.status = "in_progress";
      msGame.movesThisTurn = 0;
      msGame.maxMovesThisTurn = MOVES_PER_TURN;
      msGame.turnNumber++;
  
      return {
        content: [{
          type: "text",
          text: `The Flufflings are ready again! Turn ${msGame.turnNumber} — ${MOVES_PER_TURN} steps available.\n\n${renderState(msGame)}`,
        }],
      };
    }
  );

• src/games/minesweeper.ts:311-311 (schema)

  The input schema for ms_next_turn — an empty object ({}), meaning the tool takes no parameters.

  {},

• src/games/minesweeper.ts:110-114 (helper)

  The applyTurnLimit helper function that sets status to 'paused' when movesThisTurn reaches maxMovesThisTurn, which is the condition that leads the player to need to call ms_next_turn.

  function applyTurnLimit(state: MinesweeperState): void {
    if (state.movesThisTurn >= state.maxMovesThisTurn) {
      state.status = "paused";
    }
  }

• src/games/minesweeper.ts:143-167 (helper)

  The renderState helper that displays the 'paused' message prompting the user to call ms_next_turn when appropriate.

  function renderState(state: MinesweeperState): string {
    const safe = ROWS * COLS - TOTAL_MINES;
    const cleared = state.revealedCount;
    const remaining = safe - cleared;
    const lines: string[] = [renderBoard(state), ``];
  
    lines.push(`Legend:  ~ uncharted  . safe path  1-8 danger level  P warning post  ! mine`);
    lines.push(`Mission: clear all ${safe} safe squares so the Flufflings can cross | ${MOVES_PER_TURN} steps/turn then call ms_next_turn`);
    lines.push(``);
    lines.push(`Warning posts: ${state.flagCount}/${TOTAL_MINES}  |  Uncharted squares: ${remaining + state.flagCount}  |  Turn: ${state.turnNumber}`);
  
    if (state.status === "in_progress") {
      lines.push(`Steps this turn: ${state.movesThisTurn}/${state.maxMovesThisTurn}  (${state.maxMovesThisTurn - state.movesThisTurn} remaining)`);
    } else if (state.status === "paused") {
      lines.push(`⏸ The Flufflings are resting (${state.movesThisTurn}/${state.maxMovesThisTurn} steps used). Check in with your player, then call ms_next_turn to continue.`);
    } else if (state.status === "won") {
      lines.push(`🎉 The field is clear! Every Fluffling scampers to safety!`);
    } else if (state.status === "lost") {
      lines.push(`💥 A Fluffling triggered a mine! The crossing has failed. Mines shown with !`);
    } else if (state.status === "waiting") {
      lines.push(`The Flufflings are gathered at the edge, trembling. Send the first scout with ms_reveal_cell — the first step is always safe.`);
    }
  
    return lines.join("\n");
  }