core-minigames/docs/volumes.md

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 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:

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