godot-genre-card-game

決して行わないこと（エキスパートのアンチパターン）

ロジックとアーキテクチャ

• カードのロジックを UI スクリプト内にハードコードしてはいけません。ゲームプレイ効果は必ず Callable オブジェクトまたは LIFO スタックに積むコマンドリソースにカプセル化してください。
• _process() 内でボード状態の計算（パワー／タフネス）を行ってはいけません。必ずシグナル駆動のトリガーまたは一元化された EffectStack リゾルバーを使用してください。
• LIFO スタックによる解決を忘れてはいけません。必ず Array.push_back() と Array.pop_back() を使用し、リアクションを後入れ先出しで解決してください。

UX とアニメーション

• ドラッグ＆ドロップ時にZ インデックスの管理を省略してはいけません。カードがほかのカードの下に滑り込むのを防ぐため、クリック時に必ずカードを最前面に移動してください。
• カードを山札間で瞬時に「テレポート」させてはいけません。山札間の移動には必ず create_tween() ／ tween_property のチェーン（0.2 秒以上）を使用してください。
• 手札のカードに global_position を使用してはいけません。滑らかな弧を描くよう、必ず Curve2D レイアウトと sample_baked() を使用して配置してください。

デッキと状態の管理

• 空のデッキの状況への対応を忘れてはいけません。ソフトロックを防ぐため、捨て札を自動でシャッフルし直す処理を必ず実装してください。
• カードの離散的なステータスに浮動小数点数を使用してはいけません。精度のずれを防ぐため、コスト、攻撃力、体力には必ず int を使用してください。
• 大量のトークンや戦場に標準の Control ノードを使用してはいけません。カードやマップアイコンを 100 個以上描画する場合は、SceneTree のオーバーヘッドを回避するため、必ず _draw() によるカスタム描画を使用してください。
• 手札のロジックで SceneTree の順序に依存してはいけません。必ず論理的な順序を Array で管理し、queue_redraw() でビジュアルを更新してください。
• 通常の for ループ中に配列要素を削除してはいけません。インデックスエラーを避けるため、必ず逆順に反復するか filter() を使用してください。
• _init() に引数なしのコンストラクターを用意し忘れてはいけません。用意しないと、Inspector でリソースを読み込めません。

---

🛠 エキスパート向けコンポーネント（scripts/）

対応するシステムを実装する前に必ず読んでください：

1. card_effect_resolution.gd — LIFO 効果スタック（push_back ／ pop_back）
2. card_tween_manager.gd — 中断可能な山札／手札の Tween（テレポートなし）
3. card_data_resource.gd — Inspector で安全に扱えるリソース形式のカード定義

エキスパート向けの元のパターン

• card_effect_resolution.gd - 入れ子のトリガーとカウンタープレイに対応する LIFO スタックリゾルバー。

モジュール型コンポーネント

• card_data_resource.gd - Inspector ベースのデザインを可能にする、データ駆動型のカード定義。
• card_data.gd - バリデーター／テストで使用する軽量な CardData リソースのスタブ。
• deck_shuffle_bag.gd - カードを均等に分配するための、安全なランダム化パターン。
• turn_state_machine.gd - 状態マッチングによる厳密なフェーズ（ドロー、プレイ、戦闘）の管理。
• card_drag_drop.gd - Control ノード向けのネイティブな _get_drag_data() の実装。
• board_query_filter.gd - ボードのメタデータを検索するための関数型 filter() パターン。
• card_tween_manager.gd - 中断可能なカード演出とボード遷移の管理。
• reactive_card_ui.gd - リソースのシグナル駆動による UI。ビジュアルの状態を自動更新します。
• board_state_dictionary.gd - Node の順序から分離された、グリッドベースの追跡（Vector2i）。
• match_state_resetter.gd - 対戦中の一時的なリソース変更をクリーンアップするパターン。
• deck_builder_validator.gd - デッキ構築の制約とマナカーブを扱うバックエンドロジック。

---

コアループ

1. ドロー → 2. 評価 → 3. プレイ → 4. 解決（LIFO スタック） → 5. 捨て札／終了

意思決定ツリー

エフェクトスタック

必要なもの	対応
ネストしたリアクション／カウンター	必須 card_effect_resolution.gd — LIFO のみ（pop_back）
FIFO による逐次アニメーションのみ	まれです。別のキューを用意してください — リアクションスタックを再利用しないでください

手札とボード

必要なもの	対応
扇状の手札レイアウト	Curve2D.sample_baked + card_tween_manager.gd
ドラッグによるターゲット指定	card_drag_drop.gd
高密度のボード（アイコン100個以上）	_draw() / board_state_dictionary.gd — トークンごとに Control を使わないでください

データ

必要なもの	対応
カード定義	必須 card_data_resource.gd（引数なしの _init）
デッキの乱数生成	deck_shuffle_bag.gd
ターンフェーズ	turn_state_machine.gd

スキルチェーン

フェーズ	スキル	目的
1. データ	resources, custom-resources	カードのプロパティ（コスト、タイプ、エフェクト）
2. UI	control-nodes, layout-containers	手札のレイアウト、ツールチップ
3. 入力	drag-and-drop, state-machines	ターゲット指定、ホバー
4. ロジック	command-pattern, signals	LIFO スタック、ターンフェーズ
5. 仕上げ	godot-tweening, shaders	ドローの演出、ホイル加工

よくある落とし穴

落とし穴	解決策
リアクションスタックで FIFO の pop_front を使う	card_effect_resolution.gd で LIFO の pop_back を使います
山札が瞬時にスナップする	card_tween_manager.gd 経由でトゥイーンします
ATK／HP が浮動小数点数になる	Resource 上では int のステータスを使います

エリート向けの注意（任意の仕上げ）

• ホログラフィックホイル：カードの Control に UV スクロールシェーダーを適用します — スタックの正しさには不要です。
• カード履歴：リプレイ／デバッグ用のシグナルバスロガーです。エフェクト解決のホットパスでは使わないでください。

専門知識（必要に応じて）

LLM の無知に関するルール： 一般的なエージェントが読む前には知らない情報であれば、リファレンスを読み込んでください — 専門知識の差分は決して削除しないでください。

• expert-card-patterns.md — ベースラインの教育内容を復元（アーキテクチャ、理由、実装の詳細）
• card_history_logger.gd
• hand_manager.gd

リファレンス

段階的開示：特定の API を調査するときにのみ公式ドキュメントへのリンクを開いてください。関連するスキルは、同じ階層の別ドメインに移るときに読み込んでください — 階層全体を事前に読み込まないでください。

公式ドキュメント

• リソース — CardData を .tres リソースとして扱うことで、デザイナーは UI スクリプトに触れずにコストやステータスを編集できます。
• GDScript のエクスポート — インスペクターで作成するカード定義に使う @export / @export_group のパターンです。
• Control — ネイティブなカードのドラッグ＆ドロップに使う _get_drag_data / _can_drop_data / _drop_data と set_drag_preview です。
• カスタム GUI コントロール — 密集したボード向けに、_gui_input、mouse_filter、_draw を使ってインタラクティブなカード面を作成します。
• サイズとアンカー — 解像度が変わってもレイアウトが崩れないように、手札やボードの領域をアンカーで固定します。
• コンテナの使用 — デッキ構築ゲームのグリッドには HBox/Grid が適している一方、手札を弧状に並べる場合は手動配置が適しています。
• Tween — ドロー、プレイ、捨て札の動きにメリハリを加える、中断可能な create_tween() / tween_property です。
• ベジェ曲線、カーブ、パス — 円形配置を安易に使わず、手札を弧状に配置するための数学的な基礎です。
• Curve2D — 円形ではない滑らかな扇状配置の位置と回転を求める sample_baked() です。
• 乱数生成 — ドローパイルの公平性を保つためのシード付き RNG とシャッフルバッグです。
• シグナルの使用 — _process によるポーリングなしで UI の反応性を保つ、Resource の changed と効果スタックのシグナルです。
• 初めての 2D シェーダー — カード面に適用する canvas_item のホイル／レアリティシェーダーです。

関連スキル

前提条件

• godot-project-foundations — DeckManager とカードシーンを接続する前に、シーンツリー、Autoload、インポートの基本を学びます。
• godot-resource-data-patterns — 対戦中の強化が作成済みカードファイルに反映されないようにするための、.tres の所有権、複製、emit_changed について学びます。
• godot-gdscript-mastery — 効果スタックやターン管理に使う、型付き Array、Callable／Command、match によるフェーズ処理について学びます。
• godot-ui-containers — 手札やボードのヒットテストに必要な Control のレイアウト、アンカー、mouse_filter の使い方について学びます。

補完

• godot-tweening — kill／parallel Tween パターンを使い、素早く再生しても位置が瞬間移動したり、破棄済みの Tween が積み重なったりしないようにします。
• godot-signal-architecture — UI にゲームルールを担わせず、ドロー、プレイ、解決、破棄を行うためのバス／シグナルグラフを構築します。
• godot-input-handling — カードとキーボードショートカットやアクセシビリティ対応のドラッグが同じビューポートを共有する場合の、ポインターとアクションマップの使い分けを扱います。
• godot-turn-system — このスキルのターンステートマシンが組み込まれる、ドロー／メイン／戦闘／終了フェーズの管理を扱います。
• godot-shaders-basics — このスキルの基本的なホログラムのスニペットを超える、canvas_item によるレアリティ箔やハイライト用マテリアルを扱います。

下流／利用側

• godot-monte-carlo-balancer — マリガン、マナカーブ、コスト／パワーに対する勝率をシミュレーションし、RNG 下でもカードのステータスが公平になるようにします。
• godot-genre-roguelike — CardData、ショップ、各幕のドラフトプールを利用するラン制のデッキ構築ゲームを扱います。
• godot-inventory-system — 対戦中のカードの山札とは別に、所持カードを永続化するコレクション／デッキ構築 UI を扱います。
• godot-ability-system — Poison、Taunt、Shield などのキーワード／状態効果を、スタック上で再利用可能なアビリティリソースとして解決します。

マスター

• godot-master — スキル間の探索に使用するライブラリルーター兼、ミラーされたモジュールエントリです。