Managing Games & Worlds

MiniModes treats games and worlds as first‑class concepts so you can run many mini‑games safely on a single Minecraft server.

This guide is for server owners (and technically minded admins) who want to understand:

• How MiniModes discovers and loads games (extensions)
• How game instances are created and tracked
• How worlds/maps are managed and cleaned up
• Operational best practices so your server stays stable over time

---

1. Games in MiniModes

1.1 Game types vs. game instances

MiniModes separates:

• Game type
  “A kind of game” (e.g. Spleef, Bridges, Duels).
  Defined inside an extension with metadata: name, description, icons, min/max players, Mashup compatibility, etc.

• Game instance
  “One running match” of that game type.
  Bound to a party, a set of players, a world/map, and chosen settings.

The engine’s GameManager:

• Registers game types from all loaded extensions
• Creates game instances when a party starts a game from /minimodes
• Tracks which players belong to which game instance
• Stops games and cleans up associated resources (like temporary worlds)

From a server operations perspective:

• Game types change when you add/remove/update extensions
• Game instances change every time players start/finish a round

---

2. Where games come from: extensions

2.1 Extensions overview

MiniModes doesn’t ship a fixed set of mini‑games. Instead, it discovers extensions:

• Each extension is packaged as a .mmx extension (containing game logic, assets, configuration)
• Extensions are loaded by ExtensionLoader during plugin startup
• Every extension can contribute one or more game types

Core behaviors:

• If an extension is missing or broken, only that extension’s games fail to load
• The core MiniModes commands and party system continue to work
• Extensions can declare:
  • Display metadata (name, description, icon)
  • Player limits (min/max)
  • Mashup compatibility flags
  • Settings definitions (for pre‑game voting and runtime settings)

2.2 Loading and reloading games

Common operations:

• On server start / plugin enable

  • ExtensionLoader scans for extensions
  • GameManager registers all game types exposed by those extensions
  • The /minimodes menu lists those game types

• On plugin reload (if supported by your setup)

  • Extensions may be re‑scanned
  • New games appear, removed games disappear
  • Existing game instances will typically be ended or migrated safely

Operational tips

• When updating an extension:
  • Stop or restart the server (or fully reload the plugin, if supported by your environment)
  • Make sure no game instances from that extension are running
• Keep a staging/test server where you validate new game extensions before pushing them to production

---

3. Starting and stopping games

3.1 Starting a game

A typical “start” flow for players:

1. A party leader runs /minimodes or /mm
2. The Game Selection GUI lists all registered game types from extensions
3. The leader clicks a game:
   • MiniModes checks:
     • Are you the party leader?
     • Is your party size within the game’s allowed range?
     • Is anyone already in a game?
   • If valid:
     • Optional Team Selection GUI appears (for team games)
     • Optional Settings Voting GUI appears
     • A new game instance is registered and allocated a world

Under the hood, GameManager:

• Creates an internal representation of the game instance
• Binds the instance to:
  • The starting party
  • The selected settings (maps, options, etc.)
  • A world/map handled by WorldManager
• Teleports players and hooks required event listeners

3.2 Stopping a game

Games end when:

• The game logic finishes normally (e.g., a team wins)
• A leader or admin stops the game manually via commands like:
  • /mm game stop
  • /mm game win <players...> (marks winners and ends the game)
• A safety or shutdown condition kicks in (plugin disable, server stop)

When a game ends, MiniModes:

1. Marks the game instance as finished
2. Returns players to a safe location (e.g., lobby or prior world)
3. Notifies RematchManager so /party rematch can reconstruct the prior setup
4. Delegates world cleanup to WorldManager (for temporary worlds)

---

4. Worlds & maps: how MiniModes keeps things clean

MiniModes uses a dedicated WorldManager to control game worlds. The goal is:

• Make it easy for game developers to ask for worlds/maps
• Keep server owners safe from world clutter and memory leaks

4.1 Types of worlds

In a typical MiniModes setup you’ll encounter three categories:

1. Permanent source worlds / templates

   • Hand‑built worlds or maps used as templates for games
   • Usually live in your regular world/ directory or dedicated map folders
   • Not modified directly by games; instead, they’re copied or cloned

2. Temporary game worlds

   • Created per game instance (or per few instances) by WorldManager
   • Based on a template map or a dynamically generated layout
   • Used only for the duration of one match or a short series of matches

3. Your regular server worlds

   • Lobby, survival world, hub, etc.
   • MiniModes teleports players to/from these worlds but does not own them

4.2 Creating worlds for games

When a game instance starts, it typically asks WorldManager for a world:

• The request includes:

  • Which map or template to use
  • Any special flags (e.g., void world, flat pre‑generated area)
  • Whether the world can be safely reused for multiple rounds

• WorldManager ensures:

  • The world is generated or cloned if it doesn’t exist
  • The world is loaded before players join
  • Game‑specific rules (PVP, mob spawning, etc.) can be applied by the game extension

As a server owner, you mostly care about:

• Making sure map templates are in the correct place and correctly configured
• Ensuring your hardware can handle the number and size of temporary worlds

4.3 Cleaning up worlds

World cleanup is critical to avoid:

• Disk clutter from thousands of old temporary worlds
• Memory usage spikes from many loaded but unused worlds

MiniModes helps by:

• Tracking which worlds belong to active game instances
• Unloading and deleting those worlds when games finish
• Running cleanup passes when:
  • The plugin is disabled
  • The server stops
  • A game crashes or fails unexpectedly (best‑effort clean)

Recommended practices

• Avoid running too many concurrent games that each create a full world copy
• Use lightweight templates (small arenas, compact maps) where possible
• Periodically check your world folders for unexpected leftovers, especially after crashes
• Use backup tools that exclude temporary worlds, or schedule cleanups before backups

---

5. Mashup, rematches, and their impact on worlds

5.1 Mashup mode

Mashup mode automatically starts random games for a party:

• Commands:
  • /party mashup start
  • /party mashup stop
• Behavior:
  • Picks from all Mashup‑compatible game types that fit the party size
  • Avoids repeating the exact same game twice in a row when possible
  • Auto‑randomizes settings for games that support it (no pre‑game voting)

From a world management perspective:

• Each Mashup round behaves like a standard game instance:
  • WorldManager allocates a world
  • The game runs
  • The world is cleaned up afterward
• Mashup can be more world intensive because:
  • Players might chain many short matches in a row
  • Different game types may need different world templates

Tip:
If Mashup is a core feature on your server, test the performance impact of a full Mashup session with a typical party size and track:

• Memory usage
• TPS during world create/unload cycles
• Disk I/O

5.2 Rematches

The RematchManager stores information about the last game setup for a party:

• Game type
• Party composition and teams
• Selected settings (maps, options, modifiers)

When players run:

• /party rematch

MiniModes:

1. Reconstructs a new game instance with the same configuration
2. Requests fresh worlds from WorldManager (usually not reusing old ones)
3. Starts the pre‑game or directly launches the match, depending on the game

Operationally, rematches are just new game instances:

• Old worlds stay cleaned up
• New worlds are allocated as needed
• Disk and memory impact are similar to starting a new game manually

---

6. Capacity planning and performance tips

6.1 Estimate concurrent load

Capacity depends on:

• Number of concurrent parties running games
• Number and size of worlds each game uses
• Game complexity (entities, redstone, custom mechanics)

Questions to ask yourself:

• How many concurrent games do you realistically expect?
• Which games are world heavy (big maps, many chunks)?
• Which games are lightweight (small arenas, few entities)?

Aim to:

• Keep the number of concurrent large‑world games low
• Mix them with lighter games in Mashup playlists

6.2 Hardware guidelines

While every environment is different, some general rules:

• Memory

  • Allocate enough RAM for:
    • Persistent worlds (lobby, survival, etc.)
    • A buffer of temporary worlds
    • Plugins and basic headroom
  • Monitor memory during busy periods:
    • If garbage collection becomes frequent or severe, reduce concurrent game count

• CPU

  • World generation and chunk loading cost CPU
  • Avoid starting many new world‑heavy game instances at the exact same time
  • Consider staggering Mashup or scheduled events slightly

• Disk

  • Use SSDs for faster world cloning/loading
  • Keep an eye on disk usage, especially if:
    • You run many large maps
    • Extensions generate worlds dynamically

6.3 Operational knobs

Ways to keep things under control:

• Limit concurrent parties for certain game types (via permissions or event scheduling)
• Prefer compact maps for high‑traffic games
• Offer a separate “arena cluster” server just for heavy games
• Use monitoring (TPS, RAM, disk I/O) and adjust game offerings based on real data

---

7. Troubleshooting common issues

7.1 Players stuck in a game world

Symptoms:

• A game crashes or fails to end cleanly
• Some players remain in a game world with no active match

Steps:

1. Use /mm game leave to let them exit cleanly if possible
2. If that fails, teleport them manually to a lobby or safe spawn
3. Check logs for game or extension errors
4. Consider restarting the plugin or server if multiple games are in a bad state

7.2 Worlds not being deleted

Symptoms:

• Directories like world_minimodes_* or game‑specific world folders accumulate
• Disk space fills over time

Actions:

1. Confirm MiniModes’ version and check its changelog for cleanup fixes
2. Verify the server has permission to delete those directories
3. Look for crash or shutdown logs where cleanup may have been interrupted
4. Safely stop the server, back up, and manually delete obviously temporary worlds

7.3 Performance drops during heavy play

Symptoms:

• Lag spikes when new games start
• TPS drops when many worlds are active

Mitigations:

• Reduce the number of concurrent high‑map‑load games
• Disable or restrict certain extensions that are particularly heavy
• Test Mashup with fewer allowed game types
• Allocate more RAM, or move heavy games to a dedicated server instance

---

8. Summary

MiniModes gives you a structured, predictable way to manage games and worlds:

• GameManager tracks game types and running instances
• ExtensionLoader discovers games from extensions
• WorldManager creates, assigns, and cleans up worlds
• RematchManager and MashupManager build on top of this to offer powerful flows without sacrificing stability

As a server owner, your key responsibilities are:

• Choose and manage trustworthy extensions
• Provide suitable world templates and hardware
• Monitor performance and adjust concurrency and game offerings

Done right, MiniModes lets you run a rich library of mini‑games on a single server with clean worlds and happy players.