How to Build Custom Minigames in Hytale: Server Developer's Guide

Hytale's server-side architecture makes it uniquely suited for custom minigames. Unlike Minecraft where game mode plugins fight against the vanilla sandbox, Hytale's plugin API and ECS give you direct control over entity behavior, world state, and game flow. If you've built Bukkit minigames, the concepts translate — but the implementation is cleaner. This guide covers the core systems every minigame needs: game state management, arena instances, player tracking, scoring, matchmaking, and deployment. Architecture: How Minigame Plugins Work in Hytale Before diving into code, understand the high-level architecture of a Hytale minigame: LayerPurposeImplementation Game ManagerOrchestrates everything — creates arenas, manages lobbies, routes playersSingleton service in your plugin Arena InstanceOne running game session with its own state, players, and world regionClass managing a world or region Game State MachineControls the phase flow — waiting, countdown, playing, endingEnum + timer logic per arena Player DataTracks per-player state — score, team, alive/dead, statsECS Components attached to player entities Event HandlersReact to player actions — kills, block breaks, zone entryEventBus + ECS event systems Step 1: Game State Machine Every minigame needs a state machine. This is the backbone that controls what happens and when. public enum GameState { WAITING, // Lobby, waiting for players STARTING, // Countdown before game begins PLAYING, // Active gameplay DEATHMATCH, // Optional: final showdown phase ENDING // Game over, showing results } Each arena instance holds its own GameState. Transitions happen based on conditions: WAITING → STARTING: Minimum player count reached STARTING → PLAYING: Countdown timer expires PLAYING → DEATHMATCH: Time limit or player threshold PLAYING/DEATHMATCH → ENDING: Win condition met (last player alive, score reached, etc.) ENDING → WAITING: Results displayed, arena reset public class Arena { private GameState state = GameState.WAITING; private final List&lt;PlayerRef&gt; players = new ArrayList&lt;&gt;(); private int countdown = 10; public void tick() { switch (state) { case WAITING -> { if (players.size() >= MIN_PLAYERS) { state = GameState.STARTING; countdown = 10; } } case STARTING -> { countdown--; broadcastCountdown(countdown); if (countdown { checkWinCondition(); } case ENDING -> { displayResults(); resetArena(); state = GameState.WAITING; } } } } Step 2: Player Data with ECS Components Use Hytale's Entity Component System to attach game-specific data to player entities. This is cleaner than maintaining external HashMap&lt;UUID, PlayerData&gt; maps — the data lives on the entity itself. public class MinigamePlayer implements Component&lt;EntityStore&gt; { public String arenaId = ""; public String team = ""; public int kills = 0; public int deaths = 0; public int score = 0; public boolean alive = true; public long lastDeath = 0; @Override public MinigamePlayer clone() { MinigamePlayer copy = new MinigamePlayer(); copy.arenaId = this.arenaId; copy.team = this.team; copy.kills = this.kills; copy.deaths = this.deaths; copy.score = this.score; copy.alive = this.alive; copy.lastDeath = this.lastDeath; return copy; } } Attach this component when a player joins an arena, read it during gameplay for scoring and team logic, and remove it when they leave. Step 3: Event Handling for Game Logic Minigames need to react to player actions. Use the appropriate event system for each type: EventBus Events (Global) // Player joins the server — show them the lobby getEventRegistry().registerGlobal( PlayerReadyEvent.class, event -> teleportToLobby(event.getPlayer()) ); // Player disconnects — remove from arena getEventRegistry().registerGlobal( PlayerDisconnectEvent.class, event -> handlePlayerLeave(event.getPlayer()) ); // Chat commands — /join, /leave, /spectate getEventRegistry().registerAsyncGlobal( PlayerChatEvent.class, future -> future.thenAccept(event -> { String msg = event.getMessage(); if (msg.startsWith("/join")) { event.setCancelled(true); handleJoinCommand(event.getSender()); } }) ); ECS Events (Entity-Specific) For block breaks, damage, and other entity-level actions, create EntityEventSystem subclasses: // Track kills for scoring public class KillTracker extends RefChangeSystem&lt;EntityStore, DeathComponent&gt; { @Override public void onComponentAdded(EntityStore store, Ref entity, DeathComponent death) { // Entity died — find the killer, update scores Ref killer = death.getKiller(); if (killer != null) { MinigamePlayer killerData = getComponent( killer, MinigamePlayer.class); if (killerData != null) { killerData.kills++; killerData.score += KILL_POINTS; } } } } Remember: ECS events must be cancelled in the filter phase, not the inspect phase. If you want to prevent block breaking during the lobby phase, the filter must check the game state and cancel before the action executes. Step 4: Arena Management For games that need isolated play spaces (Hunger Games, Bed Wars), you need arena instances: Multi-Arena Pattern public class ArenaManager { private final Map&lt;String, Arena&gt; arenas = new HashMap&lt;&gt;(); public Arena createArena(String id, Location center) { Arena arena = new Arena(id, center); arenas.put(id, arena); return arena; } public Arena findAvailableArena() { return arenas.values().stream() .filter(a -> a.getState() == GameState.WAITING) .filter(a -> a.getPlayerCount() < a.getMaxPlayers()) .findFirst() .orElse(null); } public void tickAll() { arenas.values().forEach(Arena::tick); } } Arena Reset After each game, the arena needs to return to its original state. Two approaches: Snapshot restore: Save the arena region's block data before the game starts, restore it after. Uses more memory but is reliable. Prefab reload: Use Hytale's built-in Prefab System to store the arena as a prefab structure and re-place it after each game. Cleaner and integrates with Hytale's native tools. Step 5: Teams and Scoring Team Assignment public void assignTeams(Arena arena) { List&lt;PlayerRef&gt; players = arena.getPlayers(); Collections.shuffle(players); String[] teams = {"Red", "Blue", "Green", "Yellow"}; for (int i = 0; i < players.size(); i++) { MinigamePlayer data = getComponent( players.get(i), MinigamePlayer.class); data.team = teams[i % teams.length]; } } Scoreboard Display Use Hytale's Message class for formatted score displays. The Message system supports color formatting, bold/italic styles, and parameter substitution: public void broadcastScores(Arena arena) { StringBuilder sb = new StringBuilder("§6=== Scoreboard ===\n"); arena.getPlayers().stream() .sorted((a, b) -> getScore(b) - getScore(a)) .forEach(p -> { MinigamePlayer data = getComponent( p, MinigamePlayer.class); sb.append(String.format("§f%s: §e%d kills §7| §a%d pts\n", p.getUsername(), data.kills, data.score)); }); arena.broadcast(sb.toString()); } Step 6: Win Conditions Common minigame win conditions and how to implement them: Game TypeWin ConditionCheck In Last Man Standing1 player/team aliveDeath handler — count alive players Score TargetFirst to X pointsScore update — check threshold Time LimitHighest score when time expiresGame tick — check timer ObjectiveComplete specific task (capture flag, destroy bed)Custom ECS event for objective interaction RoundsBest of N roundsRound end handler — check series score Step 7: Matchmaking and Queues For servers running multiple concurrent games, implement a queue system: public class MatchmakingQueue { private final Queue&lt;PlayerRef&gt; queue = new LinkedList&lt;&gt;(); private final int requiredPlayers; public void addPlayer(PlayerRef player) { queue.add(player); checkQueue(); } private void checkQueue() { if (queue.size() >= requiredPlayers) { Arena arena = arenaManager.findAvailableArena(); if (arena != null) { for (int i = 0; i < requiredPlayers; i++) { PlayerRef player = queue.poll(); arena.addPlayer(player); } } } } } Hytale's built-in Party System lets players group up and stay together across server transfers. Your matchmaking should respect party groups — queue party members together and place them on the same team when possible. Existing Minigame Mods to Study Don't build from scratch — study what's already on CurseForge: ModTypeKey Features to Study Hunger GamesLast Man StandingMulti-arena management, lobby system, countdown, PvP phases, auto-reset BossArenaPvE ArenaNPC contract shops, per-player loot chests, configurable bosses Wave Combat ArenasHorde ModeWave spawning, difficulty scaling, reward systems SkyblockIsland SurvivalPer-player world instances, progression tracking, boss encounters The Hunger Games mod is particularly worth studying — it demonstrates the full lifecycle of a competitive minigame: lobby → countdown → PvP → deathmatch → results → reset. Built-in Platform Features for Minigame Servers Hytale provides several features out of the box that Minecraft servers need plugins for: Discovery Catalogue: Built into the main menu — players can find your minigame server without external listing sites Party System: Native friend grouping that persists across server transfers Payment Gateway: Built into the client for servers that want to monetize cosmetics or perks Permissions Framework: User-level, group-based, and wildcard permission matching Deployment Checklist Build your JAR: ./gradlew build Test locally: Drop into %AppData%/Roaming/Hytale/UserData/Mods/ Test with multiple clients: Update 4 allows multiple Hytale instances on one PC — test multiplayer scenarios locally Deploy to server: Upload JAR to /opt/hytale/Server/mods/ Publish on CurseForge: Package as a Plugin with proper manifest.json List your server: Add it to HytaleCharts with the "Minigames" tag so players can find you For the foundational plugin API concepts this guide builds on, read our Modding API Guide. And for no-code content creation that complements your plugins, check out our Visual Scripting Guide. Building a minigame server? Share it on our Discord — we feature community creations regularly.