puzzle

パズル

グリッド／ボードパズルゲームのためのプレイブックです。ボードモデル、操作入力、ルールの解決 （マッチング、押す操作、ロジック）、スコア、元に戻す機能、レベル進行を扱います。これは組み合わせ型 のスキルです。ボードの状態とルールをモデル化し、タイルマップ／UIを通じて提示します。タイルマップを改めて説明するものではなく、解決ループと、パズルを公平でバグのない状態に保つための正しさのルール（クリーンな状態、決定論的な解決、元に戻す機能）を定義します。

使用する場面

• プレイヤーが手を使って状態を変える離散ボードがあり、ボードがルールに従って解決するゲームで使います。例：マッチ3／タイルマッチング、倉庫番／ブロック押し、スライドパズル、ロジックグリッド。
• マッチや連鎖の解決、元に戻す機能、レベル進行、または解けることの保証を設計するときに使います。

使用しない場面： パーマデスありのリアルタイムなグリッドアクション → roguelike。カードのゾーン／ターン → card-game。物理ベースの「パズルプラットフォーマー」 → platformer + physics-tuning。タイルの描画には、godot-tilemap / unity-tilemap-2d を使います。

コアループ

ボードを確認 → 手を考える → 手を実行する → ボードがルールに従って解決する（マッチ、押す、落下、補充、連鎖） → 目標への進捗を確認する → 解決／失敗するまで繰り返す。
面白さは計画を立てることにあります。エンジンの役割は、各手を決定論的に解決し、明確に提示することです。

必須システム

1. ボードモデル — ピースを保持するセルのグリッドです。唯一の信頼できる情報源であり、ビジュアルではなくロジックを表します。
2. 操作入力 — スワップ、押す、ドラッグ、回転、または配置です。適用する前に合法かどうかを検証します。
3. ルールの解決 — マッチ、押す操作、ロジックなど、そのジャンルのルールを安定状態になるまで検出して適用します。
4. 連鎖／コンボ — 解決によってボードが変化したら、それ以上変化しなくなるまで再度解決します。
5. 目標 + スコア — 勝敗条件（スコア、全消去、ゴール到達）と、手数／時間制限です。
6. 元に戻す機能 — 最後の手（およびその解決結果）を正確に取り消します。じっくり考えるパズルには不可欠です。
7. レベル進行 +（多くの場合）生成 — 手作業で作成するか、解けるボードを生成します。
8. フィードバック（「気持ちよさ」） — マッチ、落下、連鎖に対して、明快で満足感のあるアニメーション／サウンドを用意します。

設計の調整項目

項目	効果	備考
グリッドのサイズ／形状	複雑さ	正方形が標準です。六角形や不規則な形状にすると感覚が変わります。
マッチ／押すルール	ジャンルの個性	3つ並べる、形を作る、ゴールに押し込む、などです。
連鎖スコア	深さへの報酬	連鎖が大きいほど、報酬は指数関数的に増えます。
手数／時間制限	プレッシャー	手数制限はパズルらしく、時間制限はアーケードらしくなります。
難易度曲線	学習	一度に1つのメカニクスを導入します。
元に戻せる回数	寛容さ	1手分か、全履歴かを選びます。
解けることの保証	公平さ	生成するボードは解ける必要があります。
デッドロックへの対応	行き詰まりの防止	手がないことを検出し、シャッフルするか終了します（参考資料）。

パターン

1. ボードモデル + マッチ検出（ロジックとビジュアルを分離）

# Pseudocode. The board is the truth; rendering reads from it. (0,0) top-left, y grows down.
board = [[piece_or_empty for _ in range(W)] for _ in range(H)]

def find_matches(board):
    matched = set()
    for y in range(H):                       # horizontal runs of >= 3 equal pieces
        run = 1
        for x in range(1, W):
            if board[y][x] and board[y][x] == board[y][x-1]: run += 1
            else:
                if run >= 3: matched |= {(y, k) for k in range(x-run, x)}
                run = 1
        if run >= 3: matched |= {(y, k) for k in range(W-run, W)}
    # ... repeat the same scan vertically (columns) ...
    return matched

2. 解決 → 落下 → 補充 → 連鎖（安定するまで繰り返す）

# Pseudocode. One player move can trigger a chain; loop until the board stops changing.
def resolve(board):
    chain = 0
    while True:
        matches = find_matches(board)
        if not matches: break                 # stable: resolution complete
        chain += 1
        score += score_for(matches, chain)    # later chain steps score more (see refs)
        clear(board, matches)                  # remove matched pieces
        apply_gravity(board)                   # pieces fall into the gaps
        refill(board, rng)                      # spawn new pieces at the top (seeded RNG)
    return chain

3. 状態のスナップショットまたはコマンドによる元に戻す機能

# Pseudocode. Snapshot before each move; undo restores it exactly (board + score + counters).
def make_move(move):
    history.append(snapshot(board, score, moves_left))   # push BEFORE applying
    apply(move); resolve(board); moves_left -= 1

def undo():
    if history:
        board, score, moves_left = history.pop()         # exact revert, including resolution

大きなボードでは、メモリを節約するため、状態全体のスナップショットよりもコマンドパターン（手と、それを反転するために必要な情報を保存する方法）をおすすめします。スナップショットは最もシンプルで、小さなボードなら問題ありません。

落とし穴／失敗パターン

• ロジックと見た目を混在させる → アニメーションが状態と同期しなくなり、バグの原因になります。ボードモデルを唯一の信頼できる情報源とし、ビューはそれを描画するだけにします。
• 解決処理を一度しか行わない → 連鎖やコンボを見落とします。ボードが安定するまで解決処理を繰り返します（パターン 2）。
• すべての状態を復元しないアンドゥ → スコア／手数／乱数状態にずれが生じます。すべての状態をスナップショットするか、手を完全に逆変換できるようにします。
• シードなしの補充用乱数生成器 → レベルを再現できず、決定論的なアンドゥやデイリーパズルも実現できません。シードを設定します。
• 解けないボードを生成する → 不公平な行き詰まりが発生します。生成後に検証するか、既知の解答から逆算して生成します（参考資料）。
• デッドロック検出がない（マッチ 3）→ 有効な手がないボードで進行不能になります。「手がない」ことを検出し、シャッフルするかレベルを終了します（参考資料）。
• 難易度が急激に上がる → 一度に多くの仕組みを導入しすぎています。組み合わせる前に、レベルごとに仕組みを 1 つずつ教えます。
• 解決処理のアニメーション中に入力を受け付ける → 二重に手が実行されたり、状態が破損したりします。ボードが安定するまで入力をロックします。

構成（これらのスキルを組み合わせて構築する）

• ボードの描画： グリッドには godot-tilemap／unity-tilemap-2d、HUD、スコア、メニューには godot-ui-control を使用します。
• レベル： 手作りパズルと難易度の調整には level-design、解けるボードの自動生成には procedural-gen を使用します。
• 永続化： レベルの進行状況、ハイスコア、シード付きデイリーパズルには save-systems を使用します。
• 演出： マッチや連鎖のポップ演出、画面の揺れ、連鎖のフィードバックには game-feel、入れ替え／落下／消去にはエンジンのアニメーション／Tween スキル、マッチや連鎖の合図には audio-design を使用します。
• スクリプト： 解決ループとルールには godot-gdscript／unity-csharp-scripting を使用します。

参考資料

• マッチ 3 の検出／重力／補充／連鎖の詳細、デッドロック検出とシャッフル、倉庫番／ルールベースのパズル、アンドゥの戦略、解けるボードの生成、スコアリングについては、 references/board-and-resolution.md をご覧ください。