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，并叠加一句简短说明（例如：“狂按 A 键飞起来！”）。
• 切勿忽视 1v3 游戏中的“非对称”平衡；务必为“单人方”提供独特能力或提高其生命值/速度，以弥补人数劣势。
• 切勿忽视无障碍和辅助机制；务必实现可选支持（例如，为技能较低的玩家提供速度加成），让比赛更具社交性。
• 切勿让游戏手柄菜单中的 UI Control 节点使用 FOCUS_NONE；务必将其设为 FOCUS_ALL，并明确指定焦点邻居，以确保导航无障碍。

渲染与架构

• 切勿使用开销大的场景切换；务必保持迷你游戏资源轻量，并在说明画面显示期间使用线程化后台加载。
• 切勿为各个分屏玩家绘制全局 CanvasLayer UI；务必将 CanvasLayer 作为各自视口的子节点。
• 切勿手动设置 SubViewport 子节点的尺寸；务必使用 GridContainer 或 BoxContainer 自动布局分屏。
• 切勿将锦标赛状态或分数存储在迷你游戏场景中；务必使用持久化 Autoload（Singleton）。
• 切勿在共享房间游戏中使用静态 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	非对称 1v3 力量平衡

常见问题

问题	解决方案
共享 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。首次接线时不要加载——先使用捆绑的 scripts/。

架构概览

1. 小游戏定义

使用 Resources 定义小游戏的内容。

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