# 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

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

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

## RewardConfig

```json
{
  "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

```json
{
  "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.