card-game

カードゲーム

カードゲーム向けのプレイブックです。カードデータ、デッキ／手札／捨て札のゾーン、ターン構造、そしてカード効果の解決方法を扱います。これは合成型のスキルです。カードをデータとしてモデル化し、UI に接続します。データアセットや UI ノードについては再説明せず、ゾーンモデル、ドローの仕組み、カードゲームを正しくバグなく動作させる効果解決ルールを定義します。

使用する場面

• デッキビルダー、TCG／CCG、ソリティア、ローグライクデッキビルダーなど、中心となるオブジェクトがゾーン間を移動するカードであるゲームを構築するときに使用します （デッキ → 手札 → プレイ → 捨て札）。
• ドロー／シャッフル／再シャッフル、ターン構造、カードコスト、効果の解決方法を設計するときに使用します。

使用しない場面： マッチングルールのあるボード／タイルの状態には → puzzle を使用します。カードバトルが付随的な RPG には → rpg から始めます。カードをアセットとして定義するには、godot-resources／unity-scriptableobjects を使用します。手札やドラッグ操作の UI には、godot-ui-control を使用します。

コアループ

手札にカードを引く → リソースを消費してカードをプレイする → 効果が解決され、ボードの状態が変化する → ターンを終了する（クリーンアップ／捨て札） → 相手／次のフェーズ → 勝利条件を満たすまで繰り返す。 奥深さは、手札で可能になる組み合わせから生まれます。エンジンの役割は、それらを曖昧さなく解決することです。

必須システム

1. カードデータ — ID、名前、コスト、タイプ、テキスト、効果仕様（コードではなくデータ）。
2. ゾーン — デッキ（ドローパイル）、手札、プレイ／ボード、捨て札、追放／除外。カードは必ずいずれか1つのゾーンに存在します。
3. ドロー＋シャッフル＋再シャッフル — デッキから手札に引きます。空になったら捨て札をデッキに戻してシャッフルします。
4. ターン構造 — フェーズ（アンタップ／ドロー／メイン／戦闘／終了）をステートマシンとして扱います。
5. リソースシステム — ターンごとに実行できる行動を制限するマナ／エネルギー／アクション。
6. 効果解決 — 定義された順序でカードの効果を適用し、対象とトリガーを処理します。
7. 勝敗条件 — ライフ総量、デッキ切れ、目標。
8. UI — 手札のレイアウト、ドラッグ＆ドロップまたはタップしてプレイ、ゾーン内の枚数、対象指定を支援する UI 要素。

設計項目

項目	効果	備考
初期手札／ターンごとのドロー枚数	展開速度、一貫性	ドローが多いほど、ばらつきが小さくなります。
手札上限	溜め込みと使用のバランス	ターン終了時に上限まで捨てます。
デッキサイズ（最小）	一貫性	小さいほど、コンボが決まりやすくなります。
リソースカーブ	いつ何をプレイできるか	「マナカーブ」が強さの推移を決めます。
カードのレア度／パワー予算	バランス	強いカードほどコストを高くするか、レアにします。
決定性とランダム性	技量と展開の振れ幅	シャッフルとランダム効果はばらつきを生みます。
再シャッフルのルール	デッキ切れ、疲労	捨て札を再シャッフルするか、デッキ切れに明確なペナルティを設けます。
除去／対抗手段	対抗プレイ	すべての脅威に対する対抗手段をカードプールに用意します。

パターン

1. 自動再シャッフルを伴うゾーンとドロー

# Pseudocode. A card is in exactly one zone at a time; moving = remove here, add there.
def draw(n):
    for _ in range(n):
        if not deck:
            if not discard:          # truly empty: deck-out (lose, or take fatigue)
                on_deck_out(); return
            deck.extend(discard)     # reshuffle discard into deck
            discard.clear()
            shuffle(deck, rng)       # use a seeded RNG (see save-systems for replays)
        hand.append(deck.pop())

2. データとしてのカードと効果解決

# Pseudocode. Effects are a data list interpreted by the engine — not bespoke code per card.
card = {
    "id": "fireball", "cost": 3, "type": "spell",
    "effects": [ {"op": "damage", "amount": 6, "target": "chosen_enemy"} ],
}
def play(card, caster):
    if resources[caster] < card.cost: return False     # can't afford
    resources[caster] -= card.cost
    move(card, from_zone=hand, to_zone=play_or_discard(card))
    for fx in card.effects:
        resolve_effect(fx, caster)                      # one interpreter handles every card
    return True

3. フェーズマシンとしてのターン構造

# Pseudocode. Fixed phases keep timing windows (triggers, priority) unambiguous.
PHASES = ["untap", "draw", "main", "combat", "end"]
def take_turn(player):
    for phase in PHASES:
        enter_phase(player, phase)        # fire "on_phase" triggers here
        if phase == "draw":   draw(1)
        if phase == "main":   await player_plays_cards()
        if phase == "combat": resolve_combat()
        if phase == "end":    discard_to_hand_limit(player); clear_temporary_effects()

落とし穴／障害要因

• カードが同時に2つのゾーンに存在する → 重複／消失のバグにつながります。「必ず1つのゾーンのみ」を徹底してください。移動は削除してから追加し、カードが重複していないことをアサートします。
• 再シャッフルを忘れる → デッキが空のとき、ドローが失敗したりクラッシュしたりします。捨て札を再シャッフルするか、デッキ切れ／疲労のルールを明示的に定義します（パターン1）。
• カードごとに関数を作る → 保守やテストが困難になります。効果はデータとして定義し、少数の操作で解釈するようにします（パターン2）。
• 効果の順序や同時発生するトリガーが曖昧 → 結果が非決定的になります。定義された順序で解決します（キューまたはスタック）。LIFO と FIFO のどちらを使うか、ドキュメントに記載します（参考資料）。
• リプレイ／アンドゥが必要なゲームで、シードなしのシャッフルを使う → 結果を再現できません。シード付き RNG を使用します。
• 手札上限や対抗手段がない → 手札の不健全な溜め込みや、対処不能な脅威につながります。手札上限を設定し、すべての脅威のタイプに対して除去手段を用意します。
• 対象指定の状態が残る → プレイをキャンセルしても、対象指定の途中でボードが止まってしまいます。プレイを不可分な処理にします。まずコストと対象を検証し、その後で確定します。

構成（これらのスキルから構築）

• カードの内容： godot-resources / unity-scriptableobjects — 各カードをデータアセットとして定義します。
• UI： レイアウト、スケーリング、フォーカスナビゲーションには game-ui-ux を、手札のレイアウト、ドラッグ＆ドロップ、ゾーン数、対象選択プロンプトには godot-ui-control を使用します。
• 永続化／リプレイ： コレクション、ランの状態（ローグライクデッキ構築）、シード付きリプレイには save-systems を使用します。
• 対戦相手の AI： プレイ可能なカードを評価して対象を選ぶ AI には game-ai を使用します。
• アニメーション／フィードバック： カードの移動にはエンジンのアニメーションスキルを、効果音には audio-design を使用します。
• スクリプト： 効果インタープリターには godot-gdscript / unity-csharp-scripting を使用します。

参考資料

• 効果キュー／スタック、キーワード／トリガー、対象選択、デッキ構築型と構築済みデッキのアーキタイプ、シャッフルの公平性については、references/effect-resolution.md をお読みください。