godot-genre-party

NEVER Do (Expert Anti-Patterns)

Multiplayer & Input

• NEVER hardcode player inputs to specific joypad IDs (e.g., 0 or 1); strictly query dynamically via Input.get_connected_joypads().
• NEVER bake player-IDs into the input map (e.g., "p1_jump"); strictly use a Dynamic Input Router to map physical controllers to players at runtime.
• NEVER use Input.is_action_pressed() for assigning new player joins; strictly parse raw InputEventJoypadButton in _unhandled_input() for device metadata.
• NEVER allow inconsistent controls between games; strictly standardize across all minigames (A = Accept/Action, B = Back/Cancel, Joystick = Move).
• NEVER assume a disconnected joypad removes a player; strictly connect to the joy_connection_changed signal to pause and handle dropouts gracefully.
• NEVER use boolean polling for analog sticks; strictly use Input.get_vector() for precision and deadzones.

User Experience & Feedback

• NEVER use long text-based tutorials; strictly use a 3-second looping GIF + a single-sentence instruction overlay (e.g., "Mash A to fly!").
• NEVER ignore "Asymmetric" balance in 1v3 games; strictly provide the "One" with unique abilities or increased HP/speed to offset the numerical disadvantage.
• NEVER neglect Accessibility and Handicap systems; strictly implement optional support (e.g., speed boosts for lower-skilled players) to keep the competition social.
• NEVER leave UI Control nodes with FOCUS_NONE for gamepad menus; strictly set to FOCUS_ALL with explicit focus neighbors for accessible navigation.

Rendering & Architecture

• NEVER use heavy scene transitions; strictly keep minigame assets light and use Threaded Background Loading while the instructions screen is active.
• NEVER draw global CanvasLayer UI for individual split-screen players; strictly use per-viewport CanvasLayer children.
• NEVER manually set sizes on SubViewport children; strictly use GridContainer or BoxContainer for automatic split-screen layout.
• NEVER store tournament state or scores inside minigame scenes; strictly use a Persistent Autoload (Singleton).
• NEVER use a static Camera2D for shared-room games; strictly use a dynamic group camera that zooms/pans to fit all players in frame.
• NEVER overlap SubViewportContainer nodes without setting mouse_filter to PASS; otherwise, top viewports will block input.

---

🛠 Expert Components (scripts/)

> MANDATORY reads before implementing the matching system:

> 1. [party_input_router.gd](scripts/party_input_router.gd) — lobby join + device→player routing (golden path)

> 2. [minigame_orchestrator.gd](scripts/minigame_orchestrator.gd) — hub ↔ minigame scene cycle

> 3. [connection_monitor.gd](scripts/connection_monitor.gd) — joy disconnect pause / reconnect

Original Expert Patterns

• [party_input_router.gd](scripts/party_input_router.gd) - Device-ID join + pN_* InputMap routing (complete, not a stub).

Modular Components

• [minigame_orchestrator.gd](scripts/minigame_orchestrator.gd) - Autoload-style minigame sequencing.
• [minigame_async_loader.gd](scripts/minigame_async_loader.gd) - Threaded PackedScene load during instruction screens.
• [split_screen_setup.gd](scripts/split_screen_setup.gd) - 2–4 SubViewportContainer grid.
• [split_screen_manager.gd](scripts/split_screen_manager.gd) - Viewport sync / shared world helpers.
• [local_input_manager.gd](scripts/local_input_manager.gd) - Runtime InputMap remaps for 4+ pads.
• [connection_monitor.gd](scripts/connection_monitor.gd) - joy_connection_changed pause + reconnect UI group.
• [player_join_manager.gd](scripts/player_join_manager.gd) - Slot mapping from raw JoypadButton events.
• [deferred_scene_switcher.gd](scripts/deferred_scene_switcher.gd) - Safe deferred free/instantiate.
• [tournament_state.gd](scripts/tournament_state.gd) - Persistent scores / roster Autoload.
• [character_select_grid.gd](scripts/character_select_grid.gd) - Focus-safe character select.
• [minigame_player_controller.gd](scripts/minigame_player_controller.gd) - Per-player pawn bound to routed actions.
• [player_haptic_feedback.gd](scripts/player_haptic_feedback.gd) - Per-device rumble.
• [shared_party_camera.gd](scripts/shared_party_camera.gd) - Shared-camera minigames (non-split).
• [minigame_data.gd](scripts/minigame_data.gd) - MinigameData Resource (scene path, rules, duration).
• [party_manager.gd](scripts/party_manager.gd) - Round/score orchestration + minigame scene handoff.
• [impact_camera_shake.gd](scripts/impact_camera_shake.gd) - Global screen-shake observer for party impacts.

---

Core Loop

1. Lobby join → 2. Meta/board → 3. Minigame → 4. Score → 5. Repeat

Decision Trees

Input & dropout

| Need | Action |

|------|--------|

| Lobby join + route | MANDATORY [party_input_router.gd](scripts/party_input_router.gd) |

| Runtime pN_* remaps | [local_input_manager.gd](scripts/local_input_manager.gd) |

| Pad battery death mid-game | MANDATORY [connection_monitor.gd](scripts/connection_monitor.gd) — pause tree + reconnect overlay |

Scenes & viewports

| Need | Action |

|------|--------|

| Cycle minigames | MANDATORY [minigame_orchestrator.gd](scripts/minigame_orchestrator.gd) (+ [deferred_scene_switcher.gd](scripts/deferred_scene_switcher.gd)) |

| Prefetch during how-to | [minigame_async_loader.gd](scripts/minigame_async_loader.gd) |

| 2–4 split | [split_screen_setup.gd](scripts/split_screen_setup.gd) — per-viewport CanvasLayer; mouse_filter on containers |

| Shared camera party | [shared_party_camera.gd](scripts/shared_party_camera.gd) |

Skill Chain

| Phase | Skills | Purpose |

|-------|--------|---------|

| 1. Input | godot-input-handling | 2–4 local controllers |

| 2. Scene | godot-scene-management | Load/unload minigames |

| 3. Data | godot-resource-data-patterns | Minigame .tres defs |

| 4. UI | godot-ui-containers | Lobby / score / reconnect |

| 5. Balance | godot-monte-carlo-balancer | Asymmetric 1v3 power |

Common Pitfalls

| Pitfall | Solution |

|---------|----------|

| Shared jump action | Device-bound pN_* via router / local_input_manager |

| Global CanvasLayer in split | Per-SubViewport UI layers |

| Generic screen-shake Elite | Prefer split + reconnect procedures above |

Split-screen + reconnect procedure

1. Build viewports with [split_screen_setup.gd](scripts/split_screen_setup.gd).
2. Bind devices through [party_input_router.gd](scripts/party_input_router.gd) before the minigame starts.
3. Keep [connection_monitor.gd](scripts/connection_monitor.gd) alive as Autoload; on disconnect pause and call_group("ui_overlays", "show_reconnect", device).
4. On reconnect, re-bind the same player_id → new device_id then unpause — do not remap other players.

> MANDATORY for depth beyond decision trees and script catalog: [party-elite-implementations.md](references/party-elite-implementations.md). Do NOT Load on first-pass wiring — use bundled scripts/ first.

Architecture Overview

1. Minigame Definition

Using Resources to define what a minigame is.

## 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.