# 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

```bash
gradlew.bat shadowJar
```

### Run with the local Hytale server

```bash
gradlew.bat runServer
```

### Create a minigame definition
Manually by adding a file under `src/main/resources/Server/Minigames/`:
or via the asset editor.


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

```text
/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

```text
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](docs/architecture.md) | How the Hytale-native pieces fit together |
| [Minigame Definition](docs/minigame-definition.md) | `MinigameDefinition` JSON fields |
| [Events, Conditions & Effects](docs/events-conditions-effects.md) | Current trigger condition/effect reference |
| [Volumes](docs/volumes.md) | How to use normal Hytale trigger volumes for minigames |
| [Trigger Volume Tags](docs/tags.md) | Complete tag reference for maps, spawns, and signals |
| [Commands](docs/commands.md) | `/minigame` command reference |
| [Examples](docs/examples.md) | Small setup patterns |

## Build Commands

```bash
gradlew.bat compileJava
gradlew.bat processResources
gradlew.bat shadowJar
```