core-minigames

A Hytale-native minigame extension for server-side minigame definitions, runtime state, and trigger-volume logic.

The mod mirrors Hytale's own asset and trigger systems instead of maintaining a separate minigame-only registry layer. Minigames are MinigameDefinition assets, trigger logic is registered as real TriggerEffect and TriggerCondition codec entries, and runtime events are dispatched on Hytale's event bus.

Features

• Asset-driven minigame definitions in Server/Minigames/
• Hytale Asset Editor support through MinigameDefinition.CODEC
• Hytale trigger-volume integration through native TriggerEffect and TriggerCondition types
• Asset-backed MinigameId picker fields in the trigger-volume editor
• Runtime lifecycle commands for creating, enabling, starting, stopping, and resetting minigames
• Multi-map runtime support using Hytale trigger-volume tags
• Player, team, score, lives, counter, status, and phase runtime state
• Hytale event-bus dispatch through MinigameEvent

Quick Start

Build

gradlew.bat shadowJar

Run with the local Hytale server

gradlew.bat runServer

Create a minigame definition

Manually by adding a file under src/main/resources/Server/Minigames/: or via the asset editor.

{
  "Id": "My_Minigame",
  "Name": "My Minigame",
  "Description": "A short description shown in menus.",
  "Enabled": true,
  "MinPlayers": 2,
  "MaxPlayers": 8,
  "TeamMode": "SOLO",
  "WinCondition": "HIGHEST_SCORE",
  "RoundLengthSeconds": 180,
  "CountdownSeconds": 10
}

Or create one from the server (saved into the named asset pack, so it survives restarts):

/minigame create MyAssetPack My_Minigame "My Minigame"
/minigame enable My_Minigame
/minigame start My_Minigame

Note: a game can only start once a trigger volume with a SetMinigamePhase(ACTIVE) effect exists for it — see docs/architecture.md (Lifecycle Contract).

Trigger Volume Logic

Use normal Hytale trigger volumes for the area shape and interaction point, then attach the minigame trigger conditions and effects.

For multi-map minigames, tag volumes with MinigameId=<id>, MapId=<map>, optional VariantId=<variant>, and MapRole=MainArena on the primary arena volume. Team spawn volumes use SpawnRole=TeamSpawn and TeamId=<team>. MapSelectionMode controls whether a queued match uses votes or random selection.

Available condition types:

• MinigamePhase
• PlayerInMinigame
• PlayerStatus
• PlayerScore
• TeamScore
• Counter
• CurrentRound
• PlayerLives
• TeamCondition
• TimerElapsed
• ObjectiveStatus
• WinConditionMet

Available effect types:

• StartMinigame
• JoinMinigameQueue
• LeaveMinigameQueue
• VoteForMap
• StartQueuedMinigame
• SpawnItem
• AwardKillScore
• EndMinigame
• ResetMinigame
• SetMinigamePhase
• ResetScores
• ModifyPlayerScore
• ModifyTeamScore
• ModifyCounter
• ModifyPlayerLives
• SetPlayerStatus
• SetRound
• StartTimer
• StopTimer
• SetSpawnPoint
• RespawnPlayer
• SendMinigameMessage
• AssignTeam
• SaveInventory
• RestoreInventory
• ClearInventory
• SetObjectiveStatus
• ModifyObjectiveProgress

Fields named MinigameId use an editor dropdown backed by registered MinigameDefinition assets.

Project Structure

core-minigames/
|-- src/main/java/net/kewwbec/minigames/
|   |-- MinigameCorePlugin.java
|   |-- command/
|   |-- event/
|   |-- model/
|   |-- runtime/
|   |-- service/
|   `-- volume/
|       |-- condition/
|       `-- effect/
|-- src/main/resources/Server/
|   |-- Languages/en-US/
|   `-- Minigames/
|-- docs/
`-- wiki/

Documentation

Doc	Description
Architecture	How the Hytale-native pieces fit together
Minigame Definition	MinigameDefinition JSON fields
Events, Conditions & Effects	Current trigger condition/effect reference
Volumes	How to use normal Hytale trigger volumes for minigames
Trigger Volume Tags	Complete tag reference for maps, spawns, and signals
Commands	/minigame command reference
Examples	Small setup patterns

Build Commands

gradlew.bat compileJava
gradlew.bat processResources
gradlew.bat shadowJar