# 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

### Template Spawning

Use `/triggervolume minigametemplate` to place a starter set of normal Hytale trigger
volumes at your current position:

```text
/triggervolume minigametemplate core_lifecycle --MinigameId=MyGame --MapId=Arena01
```

Use `/triggervolume minigametemplates` for the builder UI version. It remembers the
builder's `MinigameId`, `MapId`, and optional `VariantId`, then lists every loaded
template as a one-click spawn action.

Use `/triggervolume templategroup <pack> <groupName> <templateId> <name>` to turn a
configured trigger-volume group in the current world into a reusable template asset.
The exporter stores member positions relative to the group origin and rewrites
minigame/map/variant tags to `Template`.

Templates are assets in `Server/MinigameVolumeTemplates/` and can be edited in the
asset editor. Template volume ids should use `Template_{VolumePurpose}`. When spawned,
`Template` is replaced with `MinigameId_MapId` plus optional `VariantId`, and tags with
`MinigameId=Template`, `MapId=Template`, and `VariantId=Template` are replaced with the
provided command values.

Built-in templates:

- `core_lifecycle`
- `solo_arena`
- `team_arena`
- `race`
- `capture_point`
- `item_spawn`
- `npc_spawn`
- `waiting_area`
- `join_late_spectator`
- `timed_heal_pack`
- `checkpoint`
- `deathzone`
- `map_vote_pad`
- `score_zone`
- `objective_progress`
- `team_assignment_pad`
- `player_activation_spawn`

### 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: `ModifyScore`
- Fields: `Operation = ADD`, `Amount = <points>`

If the score is team-based, use `ModifyScore` with `TargetType=TEAM`.

### Phase Gate

Use Hytale's normal volume behavior for the area and guard attached effects with:

- Condition: `MinigamePhase`
- Field: `Phase = ACTIVE`

### Player And Team Spawns

Use normal trigger volumes as spawn markers. The volume position is the teleport destination.

Tag shared all-player spawn volumes with:

- `MinigameId=<your minigame>`
- `MapId=<map id>`
- optional `VariantId=<variant id>`
- `SpawnRole=PlayerSpawn`

Tag each team-specific 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`.
4. A random shared `PlayerSpawn` volume with no `TeamId`.

This means checkpoint-based games can still override spawns per player, team arena games can rely on tagged team spawn volumes, and solo/FFA games can rely on a pool of shared `PlayerSpawn` volumes.

Player deaths during a minigame automatically use the same destination order. `RespawnPlayer.DestinationId` accepts coordinate strings, such as `100,64,200` or `world_name,100,64,200`; `SetSpawnPoint` uses separate `X`, `Y`, and `Z` fields. Spawn fallback is resolved from tagged 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.

### Block Fill Effects

Attach `PlaceBlocks` when a trigger should place or replace a cuboid of blocks:

- Effect: `PlaceBlocks`
- Fields: `BlockId = <block id>`, `X1/Y1/Z1 = <first world corner>`, `X2/Y2/Z2 = <second world corner>`

The region is inclusive and uses absolute world block coordinates. `MaxBlocks` defaults to `32768`.

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