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

4.3 KiB Raw Blame History