MinigameFramework

What is this?

MinigameFramework is a required dependency, not a minigame by itself. It adds no gameplay on its own. If a minigame plugin like HideAndSeek listed this as a dependency and sent you here, you're in the right place: install this JAR and that plugin, and you're set.

It's the shared foundation minigame plugins are built on top of: phases, teams, spectators, GUIs, stats, and progression, so plugin authors (myself included) don't rebuild the same infrastructure every time. If you're a plugin developer building your own minigame, see the "For developers" section below.

Why it exists

Every Minecraft minigame needs roughly the same scaffolding: game phases, teams, spectator mode, scoreboards, custom items, GUIs, stats and progression, translations. Building that from scratch for every project is a waste of time. MinigameFramework provides all of it as a shared base, your minigame plugin extends MinigameFramework instead of JavaPlugin and gets a working game skeleton immediately.

What's included

• Phase-based game state machine: define lobby/playing/ended (or your own) phases, each with its own rule set for PvP, block interaction, damage, hunger, weather, and more, configurable per-material or per-entity
• Teams, spectators, and world management: team colors and boss bars, spectator mode, world create/import/delete
• Custom items & GUIs: cooldowns, limited uses, item variants, plus a full inventory/menu framework (teams, worlds, settings, rewards, cosmetics) and an interactive in-world map picker
• Progression system: XP/coin levels, boosters, and a reward system (titles, badges, cosmetics, permissions, custom rewards) gated by level or PlaceholderAPI conditions
• Persistent stats: SQL storage (MySQL or SQLite) with async repositories, global and per-minigame stats, leaderboards, and optional Redis-backed cache invalidation for multi-server setups
• In-game wiki: YAML-driven, with a standalone HTML editor included so you're not hand-writing wiki pages
• Full i18n: English and German ship out of the box, per-player language preferences, PlaceholderAPI expansions for stats/settings/boosters/rewards

Requirements

Component	Version
Server software	Paper 1.21 (API 1.21.10+)
Java	21
PlaceholderAPI	2.11.6+ (optional)
Redis	optional, only for cross-server stat caching

Installing

1. Drop MinigameFramework.jar into plugins/
2. Drop the minigame plugin(s) that require it into plugins/ too (e.g. HideAndSeek)
3. Start the server: you should see MinigameFramework library loaded successfully! in the console On Modrinth, plugins built on this framework list it as a required dependency, so if you got here via that link, this step is exactly what you're supposed to do.

Storage is disabled by default (nothing persists). Enable SQLite or MySQL under framework.storage in config.yml if you want stats and progression to actually save.

For developers

Full API docs, architecture notes, and a getting-started guide (including a minimal working minigame example) are in the GitHub README. Source is open, contributions and issue reports welcome.