123 lines
4.4 KiB
Markdown
123 lines
4.4 KiB
Markdown
# 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.
|