Getting Started

A fully GUI-driven Minecraft mini-game lobby plugin built for Spigot / Paper 1.21 – 1.21.6. All 15 games are bundled inside the main jar — no extra modules needed. Drop it into plugins/ and you're ready to play.

Main Class & Version

Main class: me.nikl.gamebox.GameBox · Version: 1.0 · Build: Maven shade (dependencies relocated to me.nikl.gamebox.common.*)

Inspiration & Acknowledgements

JoyMart is entirely independently designed and developed by the author. All code, game logic, GUI interactions, and data storage in this repository are original implementations.

In terms of product shape, gameplay concepts, and user experience, this project draws inspiration from — and pays tribute to — the following two excellent Spigot community projects:

• JukeBox - Music Plugin — Inspired the "music player + NBS song" concept. The built-in MusicPlayer of this project (NBS song parsing + note-block sequence playback) is a from-scratch re-implementation inspired by this work.
• GameBox - Inventory Games Collection — Inspired the overall "aggregate multiple mini-games via a chest GUI" product shape. The 15 games, token system, high-score table, multiplayer invitations, and AI opponents in this project are all independently rewritten and do not reuse any of their code.

TIP

The links above point to the SpigotMC resource pages — click to view the original works. Thanks to the original authors for their excellent contributions to the community.

Features at a Glance

Category	Description
Pure GUI	Pick games through chest inventories; players never need to memorize commands.
15 Built-in Games	Single-player: 2048, Minesweeper, Whack-a-Mole, Bejeweled, Lottery, Slot Machine, Maze, Snake, Dino Run; Two-player: Battleship, Connect 4, Tic-Tac-Toe, Rock-Paper-Scissors, Chess; Multiplayer: Monopoly (2–3 players, with AI and betting modes).
Token System	Built-in JoyMart tokens with optional Vault economy hook (coins).
High-Score Table	Automatically records the top score of every game; supports cross-server MySQL sync.
Two-Player + AI	Two-player games support inviting a friend or playing against a built-in AI (no waiting for an opponent).
Configurable Prize Pools	Lottery / Slot Machine share a prize pool. Admins can add/remove prizes, adjust weights, and configure token/money/command rewards via the in-game GUI.
Lobby Mode	Automatically distributes a hotbar shortcut item in configured worlds; clicking it opens the main menu.
Dual Storage	YAML files (default) or MySQL (HikariCP connection pool, BungeeCord-ready).
Custom Events	Run configured console commands when a player enters / leaves JoyMart.
Public API	Exposed via GameBoxAPI or Bukkit ServicesManager for other plugins.
Hook Support	PlaceholderAPI, bStats, CalendarEvents (auto-detected).
Multi-Language	Built-in English / Chinese / German / Spanish.
Scoreboard	During a game, the sidebar shows the current game, score, high score, and tokens.

Installation & Build

Option A: Build from source (recommended)

Requires JDK 21+ and Maven 3.6+:

git clone https://github.com/myzer121/JoyMart.git
cd JoyMart
mvn clean package

Build output: target/JoyMart-1.0.jar

Option B: Use a prebuilt jar

If you have a release JoyMart-1.0.jar, just drop it into your server's plugins/ directory.

Server Requirements

• Paper / Spigot 1.21 – 1.21.6 (Paper recommended)
• Java 21+
• Optional: Vault + any economy plugin
• Optional: PlaceholderAPI
• Optional: CalendarEvents (seasonal easter eggs)

First Run

1. Place JoyMart-1.0.jar into plugins/, start the server once to let it generate the default config.
2. Edit plugins/JoyMart/config.yml as needed (economy, lobby, invitations, sounds, scoreboard, etc.).
3. Edit plugins/JoyMart/games.yml to toggle each game and configure sub-commands.
4. Edit plugins/JoyMart/tokenShop.yml to add/remove shop items.
5. Run /gba reload or restart the server.
6. Players run /gamebox to open the main menu.

What's next?

• Browse every game in Game Modes.
• Learn the full command set in Commands & Permissions.
• Tune your server in Configuration Files.