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:
- party_input_router.gd — lobby join + device→player routing (golden path)
- minigame_orchestrator.gd — hub ↔ minigame scene cycle
- connection_monitor.gd — joy disconnect pause / reconnect
Original Expert Patterns
Modular Components
Core Loop
- Lobby join → 2. Meta/board → 3. Minigame → 4. Score → 5. Repeat
Decision Trees
Input & dropout
Scenes & viewports
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
- Build viewports with split_screen_setup.gd.
- Bind devices through party_input_router.gd before the minigame starts.
- Keep connection_monitor.gd alive as Autoload; on disconnect pause and
call_group("ui_overlays", "show_reconnect", device).
- 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. 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.
