HeruEdhel
ca11bbd4c0
- Introduced various minigame volume templates including map vote pad, NPC spawn, objective progress, player activation spawn, race, score zone, solo arena, team arena, team assignment pad, timed heal pack, and waiting area. - Each template includes specific configurations for positions, shapes, effects, and tags relevant to their functionality. - Implemented unit tests for minigame volume template export and spawn functionalities to ensure correct behavior and tag rewriting. - Added tests for minigame map discovery service to validate player respawn logic based on team assignments. - Enhanced minigame queue service tests to cover player join midgame scenarios. - Created a data store test for saving and loading player defaults in the minigame template builder.
186 lines
6.7 KiB
Markdown
186 lines
6.7 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
|
|
|
|
### 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.
|