# 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.