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,147 @@
+# King of the Hill : Capture Zones
+
+Each round has one active capture zone. Players standing inside the correct zone for the current round earn +1 point per second. Zones outside the active round do nothing.
+
+You will create three separate trigger volumes : one per hilltop.
+
+---
+
+## How Scoring Works
+
+Each capture zone uses:
+
+- A **TICK** volume type so it fires continuously while players are standing inside it.
+- A `CurrentRound` condition that passes only when the correct round number is active.
+- A `ModifyPlayerScore` effect that adds 1 point per trigger fire.
+
+The tick rate on the volume controls how often points are awarded. Set it to **1 second** in the editor so players earn 1 point per second. If the tick fires every 0.5 seconds, players would earn 2 points per second : adjust the amount or tick rate to your preference.
+leaving it at zero would be everytick its fired, Giving 30 points
+---
+
+## Capture Zone A : Round 1
+
+Place this volume on Hilltop A, the first round's scoring area. Size it so that players must be clearly on top of the hill.
+
+**Volume type:** TICK trigger (tick interval: 1 second)
+
+**Tags:**
+
+| Tag | Value |
+|---|---|
+| `MinigameId` | `King_Of_The_Hill` |
+| `MapId` | `Hillside` |
+
+**Conditions:**
+
+| Condition | Fields | Purpose |
+|---|---|---|
+| `PlayerInMinigame` | `MinigameId = King_Of_The_Hill` | Only scores players in the runtime. |
+| `CurrentRound` | `MinigameId = King_Of_The_Hill`, `Compare = EQUAL`, `Round = 1` | Only active during Round 1. |
+
+**Effects:**
+
+| Effect | Fields |
+|---|---|
+| `ModifyPlayerScore` | `MinigameId = King_Of_The_Hill`, `Operation = ADD`, `Amount = 1` |
+
+---
+
+## Capture Zone B : Round 2
+
+Place this volume on Hilltop B. Same setup as Zone A with only the round number changed.
+
+**Volume type:** TICK trigger (tick interval: 1 second)
+
+**Tags:** Same as Zone A (`MinigameId`, `MapId`)
+
+**Conditions:**
+
+| Condition | Fields |
+|---|---|
+| `PlayerInMinigame` | `MinigameId = King_Of_The_Hill` |
+| `CurrentRound` | `MinigameId = King_Of_The_Hill`, `Compare = EQUAL`, `Round = 2` |
+
+**Effects:**
+
+| Effect | Fields |
+|---|---|
+| `ModifyPlayerScore` | `MinigameId = King_Of_The_Hill`, `Operation = ADD`, `Amount = 1` |
+
+---
+
+## Capture Zone C : Round 3
+
+Place this volume on Hilltop C.
+
+**Volume type:** TICK trigger (tick interval: 1 second)
+
+**Tags:** Same as above
+
+**Conditions:**
+
+| Condition | Fields |
+|---|---|
+| `PlayerInMinigame` | `MinigameId = King_Of_The_Hill` |
+| `CurrentRound` | `MinigameId = King_Of_The_Hill`, `Compare = EQUAL`, `Round = 3` |
+
+**Effects:**
+
+| Effect | Fields |
+|---|---|
+| `ModifyPlayerScore` | `MinigameId = King_Of_The_Hill`, `Operation = ADD`, `Amount = 1` |
+
+---
+
+## Notes
+
+**You may want to add further effects the zones** : 
+On Capture Zone 1 using `SignalRoundStart=1` volume tag (covered in `06-round-signals.md` and `tags.md`) 
+you can add the following to play a sound at the start of the round and have a VFX with a duration of the round set
+
+On Tag Added trigger
+| Effect | Fields |
+|---|---|
+| `PlaySound` | `Your choice of sound`|
+| `Play VFX` | `Your choice of VFX` `Duration = round time`|
+
+
+
+**Multiple players on the hill at once** : each player in the volume gets the `ModifyPlayerScore` effect independently. If two players stand on Hilltop A during Round 1, both earn +1/second. This is intentional for KOTH : fighting over the hill is part of the game.
+
+**Zone size** : make your capture zones intentionally tight so there is real competition for the spot. A zone that is too large removes the "king of the hill" tension.
+
+
+**Dymanic Zone Size**
+Lets say you have rounds last 60 secounds. You want the Capture Zone for round 2 to get smaller half way. 
+Create two Capture Zones one the full size and one the half size
+
+Add on the large Capture Zone 2 using `SignalRoundStart=2` volume tag (covered in `06-round-signals.md` and `tags.md`) 
+And another tag to each to later identify them
+`Round2Capture=Large` 
+`Round2Capture=Small` 
+
+The larger Capture Zone
+On Tag Added trigger
+| Effect | Fields |
+|---|---|
+| `DisableVolume` | `MatchTagKey=Round2Capture` `MatchTagValue=Small`|
+| `PlaySound` | `Your choice of sound`|
+| `Play VFX` | `Your choice of VFX` `Duration = 30`|
+| `EnableVolume` | `EffectDelay=30` `MatchTagKey=Round2Capture` `MatchTagValue=Small`|
+| `ModifyTag` | `Operation=Set` `TagKey=SmallRound2Capture` `TagValue=Enabled` `MatchTagKey=Round2Capture` `MatchTagValue=Small`|
+| `DisableVolume` | `MatchTagKey=Round2Capture` `MatchTagValue=Large`|
+
+The Smaller Capture Zone
+On Tag Added trigger
+| Effect | Fields |
+|---|---|
+| `PlaySound` | `Your choice of sound`|
+| `Play VFX` | `Your choice of VFX` `Duration = 30`|
+| `EnableVolume` | `EffectDelay=30` `MatchTagKey=Round2Capture` `MatchTagValue=Large`|
+| `ModifyTag` | `Operation=Remove` `TagKey=SmallRound2Capture` `TagValue=Enabled` `MatchTagKey=Round2Capture` `MatchTagValue=Small`|
+| `DisableVolume` | `MatchTagKey=Round2Capture` `MatchTagValue=Large`|
+
+
+There are a couple of ways to do this, but this is just one I felt like typing. 
+
+**Score display** : the HUD shows the current score in real time. Players can see how their score compares while standing on the hill. Round and time remaining are also shown because `ShowRound = true` and `ShowTime = true` are set in the definition.