godot-genre-party

絶対にしてはいけないこと（エキスパートのアンチパターン）

マルチプレイヤーと入力

• プレイヤー入力を特定のジョイパッド ID（例：0 や 1）に絶対に固定しないでください。必ず Input.get_connected_joypads() で動的に取得してください。
• プレイヤー ID を入力マップに絶対に埋め込まないでください（例：「p1_jump」）。必ず 動的入力ルーター を使って、実行時に物理コントローラーをプレイヤーに割り当ててください。
• 新しいプレイヤーの参加割り当てに Input.is_action_pressed() を絶対に使わないでください。デバイスのメタデータを取得するため、必ず _unhandled_input() で生の InputEventJoypadButton を解析してください。
• ゲームごとに操作が異なる状態を絶対に許容しないでください。すべてのミニゲームで必ず統一してください（A = 決定／アクション、B = 戻る／キャンセル、ジョイスティック = 移動）。
• ジョイパッドが切断されたときにプレイヤーがいなくなると絶対に決めつけないでください。必ず joy_connection_changed シグナルに接続し、一時停止して切断を適切に処理してください。
• アナログスティックの入力判定にブール値のポーリングを絶対に使わないでください。精度とデッドゾーンのため、必ず Input.get_vector() を使ってください。

ユーザーエクスペリエンスとフィードバック

• 長文のテキストチュートリアルを絶対に使わないでください。必ず 3 秒のループ GIF と、1 文の操作説明オーバーレイ（例：「A を連打して飛ぼう！」）を使ってください。
• 1 対 3 のゲームで「非対称」のバランスを絶対に無視しないでください。数的不利を補うため、必ず「1 人側」に固有の能力を与えるか、HP／速度を上げてください。
• アクセシビリティとハンディキャップの仕組みを絶対に軽視しないでください。競争をみんなで楽しめるよう、任意のサポート（例：スキルの低いプレイヤーへのスピードブースト）を必ず実装してください。
• ゲームパッド用メニューの UI Control ノードに FOCUS_NONE を絶対に設定したままにしないでください。アクセシブルなナビゲーションのため、必ず FOCUS_ALL を設定し、フォーカス先を明示的に指定してください。

レンダリングとアーキテクチャ

• 重いシーン遷移を絶対に使わないでください。ミニゲームのアセットを軽量に保ち、説明画面の表示中に必ず バックグラウンドでのスレッド読み込み を行ってください。
• 個々の分割画面プレイヤー向けのグローバルな CanvasLayer UI を絶対に描画しないでください。必ずビューポートごとに CanvasLayer の子ノードを使用してください。
• SubViewport の子ノードのサイズを絶対に手動で設定しないでください。自動で分割画面のレイアウトを行うため、必ず GridContainer または BoxContainer を使用してください。
• トーナメントの状態やスコアをミニゲームのシーン内に絶対に保存しないでください。必ず 永続的なオートロード（シングルトン）を使用してください。
• 共有ルームのゲームで静的な Camera2D を絶対に使わないでください。すべてのプレイヤーがフレーム内に収まるよう、ズームとパンを行う 動的なグループカメラ を必ず使用してください。
• mouse_filter を PASS に設定せずに SubViewportContainer ノードを絶対に重ねないでください。設定しないと、上側のビューポートが入力をブロックします。

---

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

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

1. party_input_router.gd — ロビーへの参加＋デバイスからプレイヤーへのルーティング（推奨実装パターン）
2. minigame_orchestrator.gd — ハブとミニゲームのシーン切り替え
3. connection_monitor.gd — ジョイパッド切断時の一時停止／再接続

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

• party_input_router.gd - デバイス ID による参加＋pN_* InputMap のルーティング（完全実装。スタブではありません）。

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

• minigame_orchestrator.gd - Autoload 形式のミニゲーム進行管理。
• minigame_async_loader.gd - 説明画面の表示中に PackedScene をスレッドで読み込みます。
• split_screen_setup.gd - 2～4 個の SubViewportContainer グリッド。
• split_screen_manager.gd - ビューポート同期／共有ワールドのヘルパー。
• local_input_manager.gd - 4 台以上のパッド用の実行時 InputMap 再マッピング。
• connection_monitor.gd - joy_connection_changed による一時停止と再接続 UI グループ。
• player_join_manager.gd - 生の JoypadButton イベントからスロットを割り当てます。
• deferred_scene_switcher.gd - 安全な遅延解放／インスタンス化。
• tournament_state.gd - スコア／ロスターを保持する Autoload。
• character_select_grid.gd - フォーカスに安全なキャラクター選択。
• minigame_player_controller.gd - 割り当てられたアクションに紐づくプレイヤーごとのポーン。
• player_haptic_feedback.gd - デバイスごとの振動。
• shared_party_camera.gd - 共有カメラのミニゲーム（分割画面ではありません）。
• minigame_data.gd - MinigameData リソース（シーンパス、ルール、時間）。
• party_manager.gd - ラウンド／スコアの管理とミニゲームシーンの引き継ぎ。
• impact_camera_shake.gd - パーティーでの衝撃を検知するグローバルな画面揺れオブザーバー。

---

コアループ

1. ロビー参加 → 2. メタ／ボード → 3. ミニゲーム → 4. スコア → 5. 繰り返し

判断ツリー

入力と切断

必要なもの	対応
ロビー参加とルーティング	必須 party_input_router.gd
実行時の pN_* 再マッピング	local_input_manager.gd
ゲーム中のパッドのバッテリー切れ	必須 connection_monitor.gd — ツリーを一時停止し、再接続オーバーレイを表示

シーンとビューポート

必要なもの	対応
ミニゲームの切り替え	必須 minigame_orchestrator.gd（および deferred_scene_switcher.gd）
操作説明中の先行読み込み	minigame_async_loader.gd
2～4 人の分割画面	split_screen_setup.gd — ビューポートごとの CanvasLayer。コンテナ上の mouse_filter
パーティー用共有カメラ	shared_party_camera.gd

スキルチェーン

フェーズ	スキル	目的
1. 入力	godot-input-handling	ローカルコントローラー 2～4 台
2. シーン	godot-scene-management	ミニゲームの読み込み／読み込み解除
3. データ	godot-resource-data-patterns	ミニゲームの .tres 定義
4. UI	godot-ui-containers	ロビー／スコア／再接続
5. バランス調整	godot-monte-carlo-balancer	非対称な 1 対 3 の戦力

よくある落とし穴

落とし穴	解決策
共通の jump アクション	ルーター／local_input_manager 経由でデバイスに紐づけた pN_* を使用
分割画面でのグローバル CanvasLayer	SubViewport ごとの UI レイヤー
汎用的な画面揺れ Elite	上記の分割画面と再接続の手順を優先

画面分割と再接続の手順

1. split_screen_setup.gd を使ってビューポートを構築します。
2. ミニゲームの開始前に、party_input_router.gd でデバイスを紐付けます。
3. connection_monitor.gd を Autoload として常に実行し、切断時に一時停止して call_group("ui_overlays", "show_reconnect", device) を呼び出します。
4. 再接続時は、同じ player_id を新しい device_id に再紐付けしてから一時停止を解除します。他のプレイヤーは再マッピングしないでください。

MANDATORY 決定木とスクリプトカタログを超える詳しい情報が必要な場合は、party-elite-implementations.md を参照してください。初回の配線時には Load しないでください — まず同梱の scripts/ を使ってください。

アーキテクチャの概要

1. ミニゲームの定義

リソースを使って、ミニゲームの内容を定義します。

## Godot-Specific Tips

*   **SubViewport**: Powerful for 4-player split-screen. Each player gets a camera, all rendering the same world (or different worlds!).
*   **InputEventJoypadButton**: Use `Input.get_connected_joypads()` to auto-detect controllers on the Lobby screen.
*   **Remapping**: Godot's `InputMap` system can be modified at runtime using `InputMap.action_add_event()`. Creating "p1_jump", "p2_jump" dynamically is a common pattern.

## Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API;
> load Related Skills when routing work to a peer domain — do not preload the whole lattice.

### Official Documentation
- [Controllers, gamepads, and joysticks](https://docs.godotengine.org/en/stable/tutorials/inputs/controllers_gamepads_joysticks.html) — Joypad connect/disconnect, device IDs, and multi-pad mapping for lobby join and local isolation.
- [Using InputEvent](https://docs.godotengine.org/en/stable/tutorials/inputs/inputevent.html) — Event order and `_unhandled_input` so join presses and per-device routing run after UI focus.
- [Controller vibration and features](https://docs.godotengine.org/en/stable/tutorials/inputs/controller_features.html) — Per-device rumble APIs used for localized hit/eliminate feedback.
- [Using Viewports](https://docs.godotengine.org/en/stable/tutorials/rendering/viewports.html) — SubViewport worlds, cameras, and UI layers required for 2–4 player split-screen.
- [Background loading](https://docs.godotengine.org/en/stable/tutorials/io/background_loading.html) — `ResourceLoader` threaded load while the instructions screen stays interactive.
- [Change scenes manually](https://docs.godotengine.org/en/stable/tutorials/scripting/change_scenes_manually.html) — Deferred free/instantiate patterns for hub ↔ minigame swaps without mid-frame crashes.
- [Singletons (Autoload)](https://docs.godotengine.org/en/stable/tutorials/scripting/singletons_autoload.html) — Persistent tournament scores, device maps, and party roster across scene changes.
- [GUI navigation](https://docs.godotengine.org/en/stable/tutorials/ui/gui_navigation.html) — Focus neighbors and gamepad menu traversal for character select and lobby UI.
- [Pausing games](https://docs.godotengine.org/en/stable/tutorials/scripting/pausing_games.html) — Tree pause + reconnect overlays when a joypad drops mid-minigame.
- [Resources](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html) — `.tres` minigame definitions (title, scene path, 1v3 flags) without hardcoding catalogs.
- [InputMap](https://docs.godotengine.org/en/stable/classes/class_inputmap.html) — Runtime `action_add_event` for per-player device-bound actions (`pN_*`).

### Related Skills

#### Prerequisites
- [godot-input-handling](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-input-handling/SKILL.md) — Device IDs, `InputMap` remaps, deadzones, and `_unhandled_input` ownership before party routing.
- [godot-scene-management](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-scene-management/SKILL.md) — Clean load/unload and deferred scene swaps between hub, instructions, and minigames.
- [godot-resource-data-patterns](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-resource-data-patterns/SKILL.md) — Typed `Resource` / `.tres` catalogs that define each minigame's scene and metadata.
- [godot-autoload-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-autoload-architecture/SKILL.md) — Singleton placement for tournament state that must outlive every minigame scene.

#### Complements
- [godot-ui-containers](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-containers/SKILL.md) — Scoreboards, instruction overlays, and `GridContainer` split-screen / character-select layouts with focus.
- [godot-camera-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-camera-systems/SKILL.md) — Shared-room framing and per-viewport cameras that zoom/pan to keep all players on screen.
- [godot-signal-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-signal-architecture/SKILL.md) — `player_joined`, `game_ended`, and reconnect prompts without hard refs across lobby and minigames.
- [godot-turn-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-turn-system/SKILL.md) — Board / meta round phases between short competitive minigames.
- [godot-audio-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-audio-systems/SKILL.md) — Short stingers, countdown cues, and per-player SFX buses that survive rapid scene cycling.

#### Downstream / consumers
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — Simulate asymmetric 1v3 / handicap power offsets so party roles stay socially fair across rounds.
- [godot-characterbody-2d](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-characterbody-2d/SKILL.md) — Typical consumer of per-device move vectors inside shared-screen 2D party arenas.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry; open when discovering which Domain Skill owns input, scenes, or UI pieces of a party stack.