First commit

2026-06-07 14:34:30 -07:00
commit 8eb6e563c5
130 changed files with 8412 additions and 0 deletions
@@ -0,0 +1,155 @@
+# 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:
+
+```text
+/minigame create My_Minigame "My Minigame"
+/minigame enable My_Minigame
+/minigame start My_Minigame
+```
+TODO make this into its own UI in game.
+
+
+## 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
+```