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.
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_game_rounds_complete	The final configured round ends.
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.
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.
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	Assigns a player to a team in the runtime.
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.

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

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.

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.