core-minigames/docs/events-conditions-effects.md

Events, Conditions & Effects

Minigame logic is implemented as Hytale-native trigger conditions and trigger effects. These are registered into TriggerCondition.CODEC and TriggerEffect.CODEC, so they appear beside Hytale's built-in trigger-volume logic.

Events

MinigameEvent implements IEvent<String> and is dispatched through Hytale's event bus, keyed by minigame ID.

Current runtime events emitted by the service layer:

Event ID	Fired When
on_game_start	A minigame runtime starts.
on_game_end	A minigame runtime ends.
on_arena_reset	A minigame runtime is reset via ResetMinigame, or a game ends with ResetOnEnd=true.
on_phase_change	SetMinigamePhase changes the runtime phase.
on_round_start	SetRound starts a round, or the round timer advances to the next round.
on_round_end	The internal round timer expires.
on_overtime_start	The final round ends and OvertimeEnabled=true. Phase is set to OVERTIME. Fired before on_game_rounds_complete.
on_sudden_death_start	The final round ends and SuddenDeathEnabled=true. Phase is set to SUDDEN_DEATH. Fired before on_game_rounds_complete.
on_game_rounds_complete	The final configured round ends (after any overtime/sudden-death events).
on_timer_expired	A named signal timer expires. The internal $round timer is consumed by runtime round progression and is not re-dispatched.
on_player_eliminated	SetPlayerStatus sets ELIMINATED, or ModifyPlayerLives reduces lives to zero.
on_objective_complete	An objective status becomes COMPLETE or objective progress reaches completion.
on_kill_score	The kill scoring system awards points for a configured kill.

The event payload is a string-object map. Runtime events include runtime_id, minigame_id, map_id, and variant_id. End events also include reason.

Conditions

All minigame conditions share a MinigameId field. In the editor this is registered as an asset picker backed by MinigameDefinition assets.

Type ID	Fields	Description
MinigamePhase	MinigameId, Phase	Passes when the runtime phase matches.
PlayerInMinigame	MinigameId, optional PlayerId	Passes when the player is in the runtime. If PlayerId is blank, the trigger context player is used.
PlayerStatus	MinigameId, optional PlayerId, Status	Passes when the player's minigame status matches.
PlayerScore	MinigameId, optional PlayerId, Compare, Value	Compares a player's score.
TeamScore	MinigameId, TeamId, Compare, Value	Compares a team's score.
Counter	MinigameId, CounterId, Compare, Value	Compares a named runtime counter.
CurrentRound	MinigameId, Compare, Round	Compares the current runtime round number.
PlayerLives	MinigameId, optional PlayerId, Compare, Value	Compares a player's remaining lives.
TeamCondition	MinigameId, optional PlayerId, TeamId	Passes when the player is assigned to the expected team.
TimerElapsed	MinigameId, TimerName	Passes when a named runtime timer exists and has elapsed.
ObjectiveStatus	MinigameId, ObjectiveId, Status	Passes when an objective has the expected status.
WinConditionMet	MinigameId, optional TargetScore	Evaluates the runtime definition's win condition for LAST_ALIVE, FIRST_TO_SCORE, and OBJECTIVE_COMPLETE.

Compare Values

PlayerScore, TeamScore, Counter, CurrentRound, and PlayerLives use the NumberCompare enum:

Value	Meaning
EQUAL	Actual value equals Value.
NOT_EQUAL	Actual value does not equal Value.
GREATER_THAN	Actual value is greater than Value.
GREATER_THAN_OR_EQUAL	Actual value is greater than or equal to Value.
LESS_THAN	Actual value is less than Value.
LESS_THAN_OR_EQUAL	Actual value is less than or equal to Value.

Effects

All minigame effects that operate on a runtime include a MinigameId field. In the editor this is registered as an asset picker backed by MinigameDefinition assets.

Type ID	Fields	Description
StartMinigame	MinigameId	Starts a minigame runtime using the triggering volume's map tags when present.
JoinMinigameQueue	MinigameId	Adds the triggering player to the minigame waiting session.
LeaveMinigameQueue	MinigameId	Removes the triggering player from the minigame waiting session and clears their vote.
VoteForMap	MinigameId, optional MapId	Votes for a map in the waiting session. If MapId is blank, the triggering volume's MapId tag is used.
StartQueuedMinigame	MinigameId	Starts a queued match using MapSelectionMode and discovered map tags.
SpawnItem	optional MinigameId, ItemId, optional Amount, RespawnDelaySeconds, SpawnKey, OffsetX, OffsetY, OffsetZ	Spawns an item entity on the ground at the trigger volume position. When attached to a TICK volume, it respawns after the previous item is picked up or despawns and the delay has elapsed.
SpawnNpc	optional MinigameId, RoleId, optional Count, RespawnDelaySeconds, SpawnKey, OffsetX, OffsetY, OffsetZ, Yaw, Pitch, Roll, SpreadRadius	Spawns one or more NPCs at the trigger volume position. Spawned NPCs are tracked as temporary runtime entities and can respawn after all active NPCs for the spawn key are gone.
MountPlayer	optional MinigameId, PlayerId, NpcId, NpcRoleId, MaxDistance, AnchorX, AnchorY, AnchorZ, MovementConfig, EmptyRoleId, optional PreventManualDismount	Mounts the triggering or configured player onto the nearest matching tracked NPC. When PreventManualDismount is true, the player cannot dismount manually until a DismountPlayer effect runs.
DismountPlayer	optional MinigameId, optional PlayerId, optional NpcRoleId, optional RemoveNpc	Dismounts the player from their NPC mount. RemoveNpc defaults to true and removes the mount entity from the world. Clears any manual-dismount lock set by MountPlayer.
PlaceBlocks	optional MinigameId, BlockId, X1, Y1, Z1, X2, Y2, Z2, optional MaxBlocks	Places BlockId in the inclusive cuboid between the two world-coordinate corners. MaxBlocks defaults to 32768 as a guard against accidental large fills.
AwardKillScore	optional MinigameId, TargetIds, Points, AwardTarget	Configures kill scoring for deaths inside this volume. TargetIds accepts Player, NPC role ids such as fox, or *. AwardTarget is PLAYER, TEAM, or BOTH.
EndMinigame	MinigameId, optional Reason	Ends the selected minigame runtime.
ResetMinigame	MinigameId	Resets the selected minigame runtime.
SetMinigamePhase	MinigameId, Phase	Sets the runtime phase directly.
ResetScores	MinigameId	Resets all player and team scores for the runtime.
ModifyPlayerScore	MinigameId, optional PlayerId, Operation, Amount	Sets, adds, or subtracts a player's score.
ModifyTeamScore	MinigameId, TeamId, Operation, Amount	Sets, adds, or subtracts a team's score.
ModifyCounter	MinigameId, CounterId, Operation, Amount	Sets, adds, or subtracts a named runtime counter.
ModifyPlayerLives	MinigameId, optional PlayerId, Operation, Amount	Sets, adds, or subtracts a player's remaining lives.
SetPlayerStatus	MinigameId, optional PlayerId, Status	Sets a player's minigame status. Setting ACTIVE triggers the activation lifecycle: saves inventory (if SavePlayerInventory), gives loadout or start items, and applies RequiredGameMode.
SetPlayerLoadout	MinigameId, optional PlayerId, LoadoutId	Assigns a named loadout to a player. The loadout must exist in StartLoadouts. Takes effect the next time the player becomes ACTIVE. Pass an empty LoadoutId to clear the assignment.
SetRound	MinigameId, Operation, Amount	Sets, adds, or subtracts the runtime round number and dispatches on_round_start.
StartTimer	MinigameId, TimerName, DurationSeconds	Starts a named runtime timer and signal timer.
StopTimer	MinigameId, TimerName	Stops a named runtime timer and cancels the signal timer.
SetSpawnPoint	MinigameId, optional PlayerId, DestinationId	Stores a player's respawn destination/checkpoint.
RespawnPlayer	MinigameId, optional PlayerId, optional DestinationId	Respawns a player using explicit destination, checkpoint, then team spawn fallback.
SendMinigameMessage	MinigameId, MessageKey, Target	Sends a translated message to PLAYER, TEAM, or ALL.
AssignTeam	MinigameId, optional PlayerId, TeamId, optional BalanceTeams	Assigns a player to a team in the runtime. If BalanceTeams is true, evenly distributes all runtime players across existing teams or auto-creates team1..teamN using TeamCount, or PlayersPerTeam when TeamCount is 0.
SaveInventory	MinigameId, optional PlayerId	Saves the player's current inventory into runtime state.
RestoreInventory	MinigameId, optional PlayerId	Restores the player's saved runtime inventory.
ClearInventory	MinigameId, optional PlayerId	Clears the player's inventory.
SetObjectiveStatus	MinigameId, ObjectiveId, Status	Creates or updates an objective status and dispatches on_objective_complete when complete.
ModifyObjectiveProgress	MinigameId, ObjectiveId, Operation, Amount	Sets, adds, or subtracts objective progress and completes an active objective when progress reaches the required threshold.
OpenMinigameQueueUI	optional MinigameId, optional MapId	Opens the queue UI page for the triggering player. Mode is inferred: no MinigameId → Global browser; MinigameId only → Single-game map list; both MinigameId and MapId → Local arena popup.
StartPlayerTimer	MinigameId, optional PlayerId	Starts a per-player stopwatch for the triggering player. Records the start timestamp in player state. Use on race start pads. If PlayerId is blank, the trigger context player is used.
StopPlayerTimer	MinigameId, optional PlayerId, optional Operation	Stops the player's stopwatch and applies the lap time to the player's score. Operation controls multi-round behaviour: SET (default) replaces the score, ADD accumulates lap times for a total time, BEST keeps the lowest recorded lap. Ignored if StartPlayerTimer was never called for this player.

Operation Values

Score, counter, and lives mutation effects use:

Value	Meaning
SET	Replace the current value with Amount.
ADD	Add Amount to the current value.
SUBTRACT	Subtract Amount from the current value.

Player Resolution

Several conditions and effects allow PlayerId to be omitted. When it is blank, the implementation attempts to resolve the triggering player from Hytale's trigger context. This is the intended setup for normal enter/interact trigger volumes.

Use an explicit PlayerId only when the trigger is not naturally tied to the player who caused it.

Respawn Resolution

RespawnPlayer resolves where to send the player in this order:

1. The effect's explicit DestinationId.
2. The player's stored checkpoint from SetSpawnPoint.
3. A random team spawn volume matching the player's TeamId.

Team spawn volumes are normal Hytale trigger volumes tagged with MinigameId, MapId, optional VariantId, SpawnRole=TeamSpawn, and TeamId=<team id>.

Player deaths during a minigame use the same resolution order automatically. DestinationId and SetSpawnPoint checkpoint values are coordinate strings, such as 100,64,200 or world_name,100,64,200.

Item Spawners

SpawnItem creates a normal Hytale item drop, not a direct inventory grant. Use it for health packs, ammo, weapons, armor, and other pickups placed in the arena.

For automatic respawns, attach it to a trigger volume that fires on TICK. The effect keeps one active item per volume plus SpawnKey; once that item reference is invalid, it waits RespawnDelaySeconds before spawning the next copy. If one volume hosts several item spawners, give each effect a different SpawnKey.

NPC Spawners

SpawnNpc uses Hytale NPC role ids. RoleId is registered as a spawnable NPC role asset picker in the editor. Use Count plus SpreadRadius for small packs, and use RespawnDelaySeconds on a repeatedly firing volume when the encounter should come back after all NPCs for the same SpawnKey are gone.

Player Mounts

MountPlayer uses Hytale's built-in NPC mount component. It mounts the player onto the nearest tracked NPC in the trigger volume, optionally filtered by NpcRoleId or exact NpcId. The trigger volume must track the NPC as well as the player, so include NPC target types on the volume when using nearest-NPC mounting.

AnchorX, AnchorY, and AnchorZ define the rider anchor passed to the client. EmptyRoleId defaults to Empty_Role, matching Hytale's built-in mount action. MovementConfig is optional; set it when the mounted player should use horse-style movement settings.

Set PreventManualDismount=true to lock the player onto the mount. The client's dismount packet is silently dropped until DismountPlayer is called. DismountPlayer always clears the lock, dismounts the player, and removes the NPC entity from the world by default (RemoveNpc=true). Filter by NpcRoleId if multiple mount types are active at the same time.

Block Placement

PlaceBlocks fills an inclusive world-coordinate cuboid with one block type. Configure BlockId, X1, Y1, Z1, X2, Y2, and Z2; coordinates can be provided in either corner order.

The effect clamps Y to the valid world range 0..319. Use MaxBlocks when a fill intentionally exceeds the default 32768 block guard.

Kill Scoring

AwardKillScore is configured on a normal trigger volume, but scoring is applied by the minigame death system rather than by volume enter/exit/tick. The volume must cover the area where deaths should count and should use the normal MinigameId, MapId, and optional VariantId tags for runtime routing.

Use TargetIds = ["Player"] for player kills, NPC role ids such as fox for specific NPC kills, or ["*"] for any supported target. Friendly kills use FriendlyFireKillScoreMode on the MinigameDefinition.

Runtime Resolution

Effects and conditions resolve a runtime in this order:

1. The triggering player's active runtime.
2. A runtime matching the triggering volume's MinigameId, MapId, and VariantId tags.
3. The configured MinigameId as a fallback.