First commit

2026-06-07 14:34:30 -07:00
commit 8eb6e563c5
130 changed files with 8412 additions and 0 deletions
@@ -0,0 +1,139 @@
+# 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.