core-minigames/docs/minigame-definition.md

Minigame Definition Reference

Minigame definitions live in src/main/resources/Server/Minigames/<Id>.json. JSON keys use PascalCase. The filename should match the Id field.

Identity

Field	Type	Required	Default	Description
Id	String	Yes	none	Unique asset ID. Use underscores instead of spaces.
Name	String	Yes	none	Display name shown in commands and UI.
Description	String	No	""	Short display description.
Enabled	Boolean	No	true	Whether the minigame can be started.
Debug	Boolean	No	false	Enables verbose minigame debug messages when supported by runtime logic.
GameType	Enum	No	GENERIC	GENERIC, BATTLE, PUZZLE, RACE, CAPTURE, or SURVIVAL.

World Binding

Field	Type	Required	Default	Description
WorldId	String	No	""	Optional world identifier.
RequiredGameMode	String	No	"adventure"	Game mode expected for players.

Players

Field	Type	Required	Default	Description
MinPlayers	Integer	No	1	Minimum player count.
MaxPlayers	Integer	No	16	Maximum player count.
AllowJoinMidgame	Boolean	No	false	Whether players can join after the game starts.
AllowSpectators	Boolean	No	true	Whether spectators are allowed.

Teams

Field	Type	Required	Default	Description
TeamMode	Enum	No	SOLO	SOLO, TEAMS, or FREE_FOR_ALL.
TeamCount	Integer	No	0	Number of teams when team mode is enabled. 0 means automatic.
PlayersPerTeam	Integer	No	0	Maximum players per team. 0 means no explicit limit.

Timing

Field	Type	Required	Default	Description
RoundLengthSeconds	Integer	No	300	Active round duration.
TotalRounds	Integer	No	1	Number of rounds to run. Values less than or equal to 0 allow open-ended round progression.
CountdownSeconds	Integer	No	10	Pre-game countdown duration.
OvertimeEnabled	Boolean	No	false	Enables overtime handling.
SuddenDeathEnabled	Boolean	No	false	Enables sudden-death handling.

Win Condition

Field	Type	Required	Default	Description
WinCondition	Enum	No	HIGHEST_SCORE	How the winner is determined.
MapSelectionMode	Enum	No	VOTE	How a waiting session chooses a discovered map: VOTE or RANDOM.
FriendlyFireKillScoreMode	Enum	No	NO_POINTS	How same-team player kills affect kill scoring: OFF, LOSES_POINTS, or NO_POINTS.

Supported values:

Value	Description
HIGHEST_SCORE	Highest score at the end wins.
FIRST_TO_SCORE	First player or team to a target score wins.
LAST_ALIVE	Last active player or team wins.
OBJECTIVE_COMPLETE	Objective completion determines the winner.
CUSTOM	Trigger logic determines the winner.

World Rules

Field	Type	Required	Default	Description
AllowPvp	Boolean	No	false	Whether players can damage each other.
AllowBlockBreaking	Boolean	No	false	Whether blocks can be broken.
AllowBlockPlacing	Boolean	No	false	Whether blocks can be placed.

Inventory

Field	Type	Required	Default	Description
SavePlayerInventory	Boolean	No	true	Save player inventory on join.
RestorePlayerInventory	Boolean	No	true	Restore player inventory when the game ends.
ResetOnEnd	Boolean	No	true	Reset runtime state when the game ends.

Items

Field	Type	Required	Default	Description
StartItems	ItemStackConfig[]	No	[]	Items given to players at game start.
Rewards	RewardConfig[]	No	[]	Rewards distributed at game end.

ItemStackConfig

{
  "ItemId": "event_fishing_rod",
  "Amount": 1
}

Field	Type	Required	Description
ItemId	String	Yes	Hytale item ID.
Amount	Integer	Yes	Stack amount.

RewardConfig

{
  "Target": "winner",
  "Items": [
    { "ItemId": "gold_coin", "Amount": 25 }
  ]
}

Field	Type	Required	Description
Target	String	Yes	winner, participant, team_winner, or a team ID.
Items	ItemStackConfig[]	Yes	Items to grant.

Minimal Example

{
  "Id": "Quick_Brawl",
  "Name": "Quick Brawl",
  "Enabled": true,
  "MinPlayers": 2,
  "MaxPlayers": 8,
  "TeamMode": "SOLO",
  "WinCondition": "LAST_ALIVE",
  "RoundLengthSeconds": 120,
  "AllowPvp": true
}

Validation

Current validation is definition-focused:

• Name must not be blank.
• MinPlayers must be greater than or equal to 1.
• MaxPlayers must be greater than or equal to MinPlayers.
• RoundLengthSeconds must be greater than 0.
• CountdownSeconds must be greater than or equal to 0.

The old custom MinigameAreaVolume validation requirement no longer applies. Minigame areas are normal Hytale trigger volumes configured in the editor.