feat: Enhance minigame effects and UI interactions

- Implemented LeaveMinigameQueueEffect to handle player removal from queues and runtime. - Added OpenMinigameQueueUIEffect to manage the opening of the minigame queue UI. - Introduced StartPlayerTimerEffect and StopPlayerTimerEffect for managing player timers and scoring. - Enhanced PlaceBlocksEffect with options for filling volumes and hollow placements. - Updated SpawnItemEffect to fix codec handling for item IDs. - Added MountPlayerEffect and DismountPlayerEffect for player interactions with NPCs. - Improved StartQueuedMinigameEffect to check player counts before starting games. - Added localization entries for new effects and UI elements. - Updated manifest to include HyUI as a dependency.
2026-06-11 17:17:54 -07:00
parent 67e70a71bd
commit 49bbd2b871
58 changed files with 3664 additions and 37 deletions
@@ -0,0 +1,86 @@
+# King of the Hill — Join Pad & Auto-Start
+
+This step sets up the volumes that let players join the queue and auto-start the game once enough players are ready.
+
+---
+
+## 1. Arena Boundary Volume
+
+This volume is not interactive — it exists purely so the runtime knows which map it is running on. Place it as a large box that encompasses the entire arena.
+
+**Volume type:** Any (Enter trigger is fine, no effects needed)
+
+**Tags:**
+
+| Tag | Value |
+|---|---|
+| `MinigameId` | `King_Of_The_Hill` |
+| `MapId` | `Hillside` *(replace with your map name)* |
+| `MapRole` | `MainArena` |
+
+No conditions. No effects.
+
+> The `MapId` value is arbitrary — pick a name that describes your arena (e.g. `Hillside`, `Volcano`, `Castle`). Use the same value on every other volume in this world that belongs to this map.
+
+---
+
+## 2. Queue Pad
+
+Place this volume at a lobby pad where players gather before the game. When stepped on, it adds the player to the queue and attempts to start the game. The start attempt is a no-op until `MinPlayers` (2) have joined, at which point the runtime is created automatically.
+
+**Volume type:** Enter trigger
+
+**Tags:**
+
+| Tag | Value |
+|---|---|
+| `MinigameId` | `King_Of_The_Hill` |
+
+**Effects:**
+
+| Effect | Fields |
+|---|---|
+| `JoinMinigameQueue` | `MinigameId = King_Of_The_Hill` |
+| `StartQueuedMinigame` | `MinigameId = King_Of_The_Hill` |
+
+> **How the auto-start works:** `StartQueuedMinigame` checks that no runtime is already running and that the queue has at least `MinPlayers` players before doing anything. With `MinPlayers = 2`: Player 1 steps on the pad — `StartQueuedMinigame` sees only 1 queued player and skips. Player 2 steps on the pad — queue now has 2 players, `StartQueuedMinigame` creates the runtime (phase = `WAITING_FOR_PLAYERS`). The signal volume below immediately advances it to `ACTIVE`.
+
+Players who step on this pad after the game has already started are queued for the next game — `StartQueuedMinigame` detects the active runtime and skips.
+
+---
+
+## 3. STARTING Phase Volume
+
+The system runs the `CountdownSeconds` countdown automatically during `WAITING_FOR_PLAYERS`. Once the countdown finishes, the runtime advances to `STARTING` and fires `SignalPhaseStart=STARTING`. Your volume responds by setting the phase to `ACTIVE` to begin the game.
+
+**Volume type:** Any (Tag Added trigger — fired by the runtime, not physically entered)
+
+**Tags:**
+
+| Tag | Value |
+|---|---|
+| `MinigameId` | `King_Of_The_Hill` |
+| `MapId` | `Hillside` |
+| `SignalPhaseStart` | `STARTING` |
+
+**Effects:**
+
+| Effect | Fields |
+|---|---|
+| `SetMinigamePhase` | `MinigameId = King_Of_The_Hill`, `Phase = ACTIVE` |
+| `SetRound` | `Operation = Set`, `Amount = 1` |
+(anything else you want to happen? Effects, sounds, Starting cinematic? Do before setting to active and starting the round)
+
+> **Countdown**: with `CountdownSeconds = 10` in the definition, a "Starting in N..." message is sent to all players each second. If a player steps off the queue pad (`LeaveMinigameQueue`) or disconnects during the countdown and the player count drops below `MinPlayers`, the countdown cancels and players are returned to the queue automatically.
+>
+> **Skip the countdown**: set `CountdownSeconds = 0` in the definition to go from `STARTING` to `ACTIVE` immediately.
+
+---
+
+## Leave Queue (Optional)
+
+If players want to leave before the game starts, add a separate pad with:
+
+| Effect | Fields |
+|---|---|
+| `LeaveMinigameQueue` | `MinigameId = King_Of_The_Hill` |