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,112 @@
+# King of the Hill — Round Signals & Game End
+
+This step wires up announcements for each new round and explains how the game ends automatically when the final round completes.
+
+---
+
+## How Signal Volumes Work
+
+Signal volumes have special tags (`SignalRoundStart`, `SignalPhaseTick`, `SignalPhaseStart`, etc.) that the runtime writes to at the right moment. When the tag value changes, Hytale fires the volume's `TAG_ADDED` trigger, which runs the attached effects.
+
+Every signal volume must also have `MinigameId` set so the runtime knows which game's signals to respond to.
+
+---
+
+## Round 2 Announcement
+
+When Round 2 begins, fire a message to all players announcing the new hill location.
+
+**Volume type:** Any (Tag Added trigger is conventional for signal volumes — the volume is never physically entered, it is fired by the runtime)
+
+**Tags:**
+
+| Tag | Value |
+|---|---|
+| `MinigameId` | `King_Of_The_Hill` |
+| `MapId` | `Hillside` |
+| `SignalRoundStart` | `2` |
+
+**Effects:**
+
+| Effect | Fields |
+|---|---|
+| `SendMinigameMessage` | `MinigameId = King_Of_The_Hill`, `MessageKey = round_2_start`, `Target = ALL` |
+
+> `MessageKey` references a translation key in your server's language files. If you do not have a dedicated translations setup, you can skip `SendMinigameMessage` for now — the HUD already shows the updated round number automatically.
+
+---
+
+## Round 3 Announcement
+
+Same structure, fires when Round 3 begins.
+
+**Tags:**
+
+| Tag | Value |
+|---|---|
+| `MinigameId` | `King_Of_The_Hill` |
+| `MapId` | `Hillside` |
+| `SignalRoundStart` | `3` |
+
+**Effects:**
+
+| Effect | Fields |
+|---|---|
+| `SendMinigameMessage` | `MinigameId = King_Of_The_Hill`, `MessageKey = round_3_start`, `Target = ALL` |
+
+---
+
+## How the Game Ends Automatically
+
+When the Round 3 timer expires, the runtime calls `end()` automatically (because `TotalRounds = 3` and neither `OvertimeEnabled` nor `SuddenDeathEnabled` are set). No extra timer volume is needed.
+
+The end sequence fires in this order:
+
+1. `SignalPhaseStart=ENDING` fires — use this for a scoreboard display, player freeze, or end announcement.
+2. HUDs are removed, inventories restored, rewards distributed.
+3. `on_game_end` event fires (with `reason = "rounds_complete"`).
+4. Runtime is removed from the active list.
+5. `SignalPhaseStart=RESETTING` fires — use this to restore blocks, re-enable the queue pad, etc.
+6. `on_arena_reset` event fires.
+
+You do not need a `StartTimer`/`SignalOnTimerExpire` pair to end the game.
+
+---
+
+## ENDING Phase Volume (Optional)
+
+To show a final message or freeze players briefly at game end, respond to `SignalPhaseStart=ENDING`:
+
+**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` |
+
+---
+
+## Round 1 Announcement (Optional)
+
+Round 1 begins immediately when the game goes ACTIVE (there is no `SignalRoundStart=1` in the current round implementation for the initial round). If you want a Round 1 announcement, fire it from the `SignalPhaseStart=ACTIVE` volume set up in step 03:
+
+**Tags:**
+
+| Tag | Value |
+|---|---|
+| `MinigameId` | `King_Of_The_Hill` |
+| `MapId` | `Hillside` |
+| `SignalPhaseStart` | `ACTIVE` |
+
+**Effects:**
+
+| Effect | Fields |
+|---|---|
+| `SendMinigameMessage` | `MinigameId = King_Of_The_Hill`, `MessageKey = round_1_start`, `Target = ALL` |