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,87 @@
+# King of the Hill — Ending & Resetting
+
+This step covers what happens when the game ends, what signals fire and when, and how to use arena reset to prepare for the next game.
+
+---
+
+## What Happens When the Game Ends
+
+When the final round timer expires (and no overtime/sudden death is configured), the runtime calls `end("rounds_complete")` automatically. The full sequence:
+
+1. **HUDs removed** for all players in the runtime.
+2. **Phase set to `ENDING`** → `SignalPhaseStart=ENDING` fires.
+3. **Active signal timers cancelled.**
+4. **Temporary entities cleaned up** (spawned NPCs/items tracked by the runtime).
+5. **Player inventories restored** (since `RestorePlayerInventory = true` is the default).
+6. **Rewards distributed** (if any `Rewards` are defined in the definition).
+7. **`on_game_end` event dispatched** with `reason = "rounds_complete"` and final scores.
+8. **Runtime state cleared** — scores, player status, timers, counters all zeroed.
+9. **Runtime removed** from the active list.
+10. **Phase set to `RESETTING`** → `SignalPhaseStart=RESETTING` fires.
+11. **`on_arena_reset` event dispatched** (since `ResetOnEnd = true` is the default).
+
+You do not need to manually reset scores or clear HUDs.
+
+---
+
+## ENDING Phase Volume (Optional)
+
+Use `SignalPhaseStart=ENDING` to show a scoreboard, announce the winner, or freeze players briefly before cleanup. This fires while the runtime still holds final scores.
+
+**Tags:**
+
+| Tag | Value |
+|---|---|
+| `MinigameId` | `King_Of_The_Hill` |
+| `MapId` | `Hillside` |
+| `SignalPhaseStart` | `ENDING` |
+
+**Example effects:**
+
+| Effect | Fields |
+|---|---|
+| `SendMinigameMessage` | `MinigameId = King_Of_The_Hill`, `MessageKey = game_over`, `Target = ALL` |
+
+---
+
+## Arena Reset Volume
+
+Use `SignalPhaseStart=RESETTING` to restore any world state changed during the game. This fires after the runtime has been cleaned up, so it is safe to re-enable the queue pad without risk of double-triggering.
+
+> **Scope note:** `SignalPhaseStart=RESETTING` is scoped by `MinigameId` tag match, NOT by physical containment within the `MapRole=MainArena` boundary. Any volume anywhere in the world with a matching `MinigameId` tag will respond. The arena boundary volume is only used for map *discovery*, not for event routing.
+
+For this King of the Hill setup there are no block placements or NPC spawns, so the arena reset volume is optional. Add it if you want to re-enable the queue pad, reset visual markers, or restore barriers changed mid-game.
+
+**Tags:**
+
+| Tag | Value |
+|---|---|
+| `MinigameId` | `King_Of_The_Hill` |
+| `MapId` | `Hillside` |
+| `SignalPhaseStart` | `RESETTING` |
+
+**Example effects:**
+
+| Effect | Fields | Purpose |
+|---|---|---|
+| `PlaceBlocks` | *(coordinates of any changed areas, original block id)* | Restore modified terrain. |
+
+---
+
+## Repeating the Game
+
+After the runtime ends and `SignalPhaseStart=RESETTING` fires, the minigame is ready to start again. Players can step back onto the queue pad and a new runtime will be created when `StartQueuedMinigame` fires again.
+
+No state from the previous game persists — scores, player status, timers, and counters are all cleared by the end flow.
+
+---
+
+## Manual Reset
+
+If you need to reset the game mid-match (for testing or crash recovery), use the admin command:
+
+```
+/minigame reset King_Of_The_Hill
+```
+
+This calls `ResetMinigame` directly, which sets phase to `RESETTING`, fires `SignalPhaseStart=RESETTING`, clears runtime state, and dispatches `on_arena_reset` — without going through the normal end flow (no rewards, no inventory restore, no `ENDING` phase).