First commit

docs/volumes.md

@@ -0,0 +1,122 @@
+# Volumes
+
+Minigame areas now use Hytale's built-in trigger volumes. The mod no longer defines custom volume types such as `MinigameAreaVolume`, `JoinQueueVolume`, or `ScoreVolume`.
+
+This is intentional: the area, shape, enter/exit behavior, tags, and trigger-effect asset wiring belong to Hytale's trigger-volume system. core-minigames adds minigame-specific conditions and effects that can be attached to those trigger volumes.
+
+## Defining Minigame Maps
+
+1. Create a normal Hytale trigger volume in the editor.
+2. Shape it around the arena or interaction area.
+3. Tag it with `MinigameId=<MinigameId>` and `MapId=<MapId>`.
+4. Add `VariantId=<VariantId>` when the same map can randomly use overlapping alternate zones.
+5. Add `MapRole=MainArena` to the primary arena volume for each map or variant.
+6. Attach trigger effects and conditions for the relevant minigame.
+7. Use the `MinigameId` dropdown to select the `MinigameDefinition` asset.
+
+There is no required root `MinigameAreaVolume` type. If validation needs an arena boundary later, it should inspect Hytale trigger-volume metadata instead of requiring a custom minigame volume class.
+
+Map candidates are discovered from trigger-volume tags. See [Trigger Volume Tags](tags.md) for the full tag reference.
+
+Overlapping volumes are valid. Runtime routing uses the selected `MinigameId`, `MapId`, and `VariantId`, so the same Hytale build can host multiple arena definitions.
+
+## Common Patterns
+
+### Start Zone
+
+Use a normal trigger volume at an entrance, sign, NPC, or lobby pad.
+
+Attach:
+
+- Effect: `JoinMinigameQueue`
+- Field: `MinigameId = <your minigame>`
+
+For exits or cancel pads:
+
+- Effect: `LeaveMinigameQueue`
+- Field: `MinigameId = <your minigame>`
+
+For voting buttons or pads:
+
+- Effect: `VoteForMap`
+- Field: `MapId = <map id>`, or leave blank to use the volume's `MapId` tag.
+
+To start the queued match:
+
+- Effect: `StartQueuedMinigame`
+- Field: `MinigameId = <your minigame>`
+
+Optionally guard it with:
+
+- Condition: `MinigamePhase`
+- Field: `Phase = WAITING_FOR_PLAYERS`
+
+### Score Zone
+
+Use a normal trigger volume around the scoring area.
+
+Attach:
+
+- Condition: `PlayerInMinigame`
+- Effect: `ModifyPlayerScore`
+- Fields: `Operation = ADD`, `Amount = <points>`
+
+If the score is team-based, use `ModifyTeamScore` instead.
+
+### Phase Gate
+
+Use Hytale's normal volume behavior for the area and guard attached effects with:
+
+- Condition: `MinigamePhase`
+- Field: `Phase = ACTIVE`
+
+### Team Spawns
+
+Use normal trigger volumes as spawn markers. The volume position is the teleport destination.
+
+Tag each team spawn volume with:
+
+- `MinigameId=<your minigame>`
+- `MapId=<map id>`
+- optional `VariantId=<variant id>`
+- `SpawnRole=TeamSpawn`
+- `TeamId=<team id>`
+
+`RespawnPlayer` resolves destinations in this order:
+
+1. The effect's explicit `DestinationId`.
+2. The player's stored checkpoint from `SetSpawnPoint`.
+3. A random matching team spawn volume for the player's `TeamId`.
+
+This means checkpoint-based games can still override spawns per player, while team arena games can rely on tagged team spawn volumes.
+
+### Counters
+
+Use a trigger volume to increment a named runtime counter:
+
+- Effect: `ModifyCounter`
+- Fields: `CounterId = <name>`, `Operation = ADD`, `Amount = 1`
+
+Then use the `Counter` condition to branch once a threshold is reached.
+
+### Kill Scoring
+
+Use a trigger volume covering the arena or scoring zone and attach:
+
+- Effect: `AwardKillScore`
+- Fields: `TargetIds = ["Player"]` or NPC role ids such as `["fox"]`, `Points = <points>`, `AwardTarget = PLAYER`
+
+The death system checks this volume when an entity dies inside it. It routes by the volume's `MinigameId`, `MapId`, and optional `VariantId` tags, so overlapping arenas can have different kill scoring rules.
+
+### Pickup Spawners
+
+Use a small trigger volume at the pickup location and attach:
+
+- Effect: `SpawnItem`
+- Fields: `ItemId = <item id>`, `Amount = <stack size>`, `RespawnDelaySeconds = <seconds>`
+
+The item spawns at the volume position plus optional `OffsetX`, `OffsetY`, and `OffsetZ`. Attach the effect to a `TICK` trigger when the pickup should automatically respawn after being collected or despawning. If the same volume has multiple item spawners, set a different `SpawnKey` for each one.
+
+## Reusable Effect Assets
+
+For repeated logic, define a Hytale trigger effect asset and attach it to multiple trigger volumes. The minigame trigger condition/effect entries are normal codec types, so they can be reused the same way Hytale's built-in trigger-volume effects are reused.