# Architecture

## Overview

core-minigames extends Hytale's existing asset, trigger-volume, and event systems. It does not run a separate minigame logic registry beside Hytale's trigger-volume registry.

```text
Server/Minigames/*.json
        |
        v
MinigameDefinition asset store
        |
        v
MinigameRuntimeService
        |
        +--> Hytale event bus: MinigameEvent
        |
        +--> TriggerEffect.CODEC entries
        |
        `--> TriggerCondition.CODEC entries
```

## Asset Store

`MinigameDefinition` is registered as a Hytale asset store in `MinigameCorePlugin.setup()`.

Important details:

- Path: `Server/Minigames/`
- Codec: `MinigameDefinition.CODEC`
- Key function: `MinigameDefinition::getId`
- Editor dropdown source: `MinigameDefinition`

The trigger-volume editor can use this asset source for fields named `MinigameId`, so minigame trigger effects and conditions can pick from loaded minigame assets instead of free-typing IDs.

## Runtime

`DefaultMinigameRuntimeService` owns active `MinigameRuntime` instances keyed by runtime ID. A single minigame ID can have multiple active runtimes when multiple discovered maps or variants are started.

Runtime state includes:

- Current `MinigamePhase`
- Player state, score, lives, team, tags, and status
- Team membership and team score
- Objective state
- Counter and variable state
- Spectator and eliminated-player sets
- Runtime ID, map ID, and variant ID

`DefaultMinigameService` handles definition-level actions and delegates live actions to the runtime service.

## Events

`MinigameEvent` implements Hytale's `IEvent<String>`.

Runtime events dispatch through:

```java
HytaleServer.get()
        .getEventBus()
        .dispatchFor(MinigameEvent.class, event.minigameId())
        .dispatch(event);
```

This keeps minigame events available to Hytale's event system instead of routing them through a custom `EventRegistry`.

## Trigger Conditions

Minigame trigger conditions extend Hytale's `TriggerCondition` and are registered directly into `TriggerCondition.CODEC`.

Current condition type IDs:

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

## Trigger Effects

Minigame trigger effects extend Hytale's `TriggerEffect` and are registered directly into `TriggerEffect.CODEC`.

Current effect type IDs:

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

## Volumes

There are no custom minigame volume classes after the refactor. Hytale trigger volumes provide the region shape, enter/exit behavior, tags, and trigger effect assets.

To define a minigame area, create a normal Hytale trigger volume and tag it with `MinigameId=<id>`, `MapId=<map>`, optional `VariantId=<variant>`, and optionally `MapRole=MainArena`. Then attach minigame trigger conditions and effects to that trigger volume or to reusable Hytale trigger effect assets.

## Removed Layer

The following old architecture pieces were removed because they duplicated Hytale systems:

- `BuiltinRegistries`
- `ConditionRegistry`
- `EventRegistry`
- `MinigameRegistries`
- `TemplateRegistry`
- `VolumeRegistry`
- `VolumeTypeDefinition`

Future minigame features should keep following the same pattern: use Hytale asset stores, Hytale trigger codec registration, and Hytale event dispatch unless there is a concrete engine gap that requires a local adapter.