Minecraft Plugin Development

Minecraft plugin development

Build and modify Java Minecraft server plugins in the Paper, Spigot, and Bukkit ecosystem, including gameplay-heavy, cooldown-based, config-driven, multi-arena, match-heavy, and persistent-brawl systems. Keep runtime registration, thread safety, gameplay state, configuration, persistence, and validation aligned with the project’s targeted server API.

When to invoke

• "Build a Minecraft plugin."
• "Add a Paper command and plugin.yml entry."
• "Fix this Bukkit listener."
• "Implement a minigame mechanic with arenas and phases."
• "Add a perk, quest, economy, or persistent profile system."

Limits

• In scope: Paper, Spigot, Bukkit plugin development; plugin.yml; commands; tab completion; listeners; schedulers; configs; permissions; Adventure text; player state; minigame flow; arena instances; map copies; loot; waves; persistent profiles; perks; buffs; quests; economy; PvP/PvE game loops; Java-based architecture, debugging, refactoring, and feature implementation.
• Out of scope by default: Fabric mods, Forge mods, client mods, and Bedrock add-ons.
• If the user says "Minecraft plugin" but the stack is unclear, determine whether the project is Paper/Spigot/Bukkit or a modding stack before editing.

Project discovery

Check these files and concepts before changing behavior:

• plugin.yml
• pom.xml, build.gradle, or build.gradle.kts
• main class extending JavaPlugin
• command executors and tab completers
• listener classes
• config bootstrap for config.yml, messages, kits, arenas, or custom YAML files
• generated resource output such as target/classes, build/resources, or copied plugin jars
• scheduler usage through Bukkit scheduler APIs
• player data, team state, arena state, or match state containers

Identify the server API and version target, build system, Java version, startup registration, gameplay lifecycle, timers, scheduled tasks, teams, arenas, match state, config, and persistence before making a coherent change.

Core implementation rules

Commands, listeners, tasks, and state

For commands, add the plugin.yml declaration, implement executor and tab completion when needed, validate CommandSender before casting to Player, separate parsing from permission and gameplay logic, and send clear feedback.

commands:
  arena:
    description: Join or leave an arena
    usage: /arena <join|leave>

@Override
public void onEnable() {
    ArenaCommand command = new ArenaCommand(gameService);
    PluginCommand arena = getCommand("arena");
    if (arena != null) {
        arena.setExecutor(command);
        arena.setTabCompleter(command);
    }
}

For listeners, guard early, verify player/arena/phase ownership, avoid expensive work in hot events such as move, damage, or interact spam, and centralize repeated checks.

For scheduled tasks, store task handles when cancellation matters, cancel tasks in onDisable and when a match or arena ends, avoid overlapping tasks for the same concern, prefer one authoritative game loop, and make countdown or refill tasks self-cancel when the game leaves the expected state.

Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
    PlayerData data = repository.load(playerId);
    Bukkit.getScheduler().runTask(plugin, () -> {
        Player player = Bukkit.getPlayer(playerId);
        if (player != null && player.isOnline()) {
            scoreboard.update(player, data);
        }
    });
});

For per-player, per-match, and long-lived player state, define ownership clearly, clean up on quit, kick, death, match end, and plugin disable, avoid stale maps keyed by Player, and prefer UUID for persistent tracking unless a live player object is strictly needed.

When the project uses Adventure or MiniMessage, follow the existing formatting approach for player-facing and game-specific text, avoid mixing legacy color codes and Adventure styles without a reason, and keep gameplay-facing messages configurable.

High-risk areas

Pay extra attention when editing damage handling, custom combat logic, death/respawn/spectator/elimination flow, arena join/leave flow, scoreboards, boss bars, inventory mutation, kit distribution, async database or file access, economy, quest, perk and profile mutation, custom event dispatch, extension registries, version-sensitive API calls, shutdown and cleanup in onDisable, cross-arena visibility/chat/broadcast isolation, map copy/unload/folder deletion, mob/NPC/projectile/temporary entity ownership, and chest/container or resource refill systems, and in-memory caches.

Procedure

1. Identify the server API/version, build system, Java version, main plugin class, plugin.yml, commands, listeners, and relevant config.
2. Map player lifecycle, game phases, scheduled tasks, team/arena/match state, persistence, and generated resources before editing.
3. Read bundled references on demand for the feature area named below.
4. Implement the smallest coherent code, resource, and registration change.
5. Validate build output, resource generation, config defaults, and runtime lifecycle paths.

Progressive disclosure and bundled resources

Load these references only when the task touches the named area:

• references/project-patterns.md: high-level architecture patterns seen in real gameplay plugins.
• references/bootstrap-registration.md: onEnable, command wiring, listener registration, and shutdown expectations.
• references/state-sessions-and-phases.md: player session modeling, game phases, match state, and reconnect-safe logic.
• references/config-data-and-async.md: config managers, database-backed player data, async flushes, and UI refresh tasks.
• references/maps-heroes-and-feature-modules.md: map rotation, hero/class systems, and modular feature growth.
• references/minigame-instance-flow.md: arena instances, countdowns, loot refreshes, wave systems, visibility isolation, and entity-to-game ownership.
• references/persistent-progression-and-events.md: long-running PvP servers with profiles, perks, buffs, quests, economy, custom domain events, and extension registries.
• references/build-test-and-runtime-validation.md: Maven or Gradle packaging, shaded dependencies, generated resources, soft dependencies, config validation commands, and first-round server test plans.

Gotchas

• Never cast CommandSender to Player without checking: console and command blocks can execute commands.
• Never mutate Bukkit world state from async tasks: use the scheduler to hand off to the main thread.
• Forgetting listener registration or plugin.yml command declarations makes correct Java code unreachable.
• Long-lived maps keyed by Player can leak; use UUID for persistent state.
• Repeating tasks must stop after round, arena, or plugin shutdown.
• Hardcoded gameplay constants should usually live in config.
• Paper-only APIs break Spigot targets unless compatibility is explicit.
• Stateful plugins often break under reload; treat reload as a lifecycle feature, not a free operation.
• Broadcasting, showing players, or applying scoreboards across unrelated game instances breaks arena isolation.
• Generated files under target/classes or build/resources are not source; edit src/main/resources instead.

Output expectations

Produce runnable Java code, not pseudo-code, unless the user asks for design only. For substantial requests, report current plugin context and assumptions, gameplay or lifecycle impact, code changes, required registration or config updates, validation, remaining risks, and thread-safety notes.

Output template

## Minecraft plugin change — <feature or bug>

**Status:** implemented | design only | blocked
**Server API:** Paper | Spigot | Bukkit | unknown
**Version assumptions:** <API and Java version>

### Current plugin context
- Main class: `<class extending JavaPlugin>`
- Registration touched: `plugin.yml`, `onEnable`, listeners, commands, permissions
- Gameplay lifecycle impact: <players, arenas, tasks, persistence>

### Changes
| File | Change | Reason |
| --- | --- | --- |
| `src/main/java/...` | <code behavior> | <why> |
| `src/main/resources/plugin.yml` | <command/permission> | <why> |

### Validation
- Build: pass | fail | not run
- Runtime registration: verified | not verified
- Thread-safety and cleanup paths: verified | risks listed

Quality gate

• The targeted server API and version assumptions are explicit.
• plugin.yml matches implemented commands, permissions, and main class behavior.
• Command sender types are checked before casting to Player.
• Listener and command registration is wired through onEnable.
• Scheduler usage respects Bukkit main-thread boundaries.
• Config keys exist or have defaults and validation.
• State cleanup covers player quit, kick, death, match end, and onDisable where relevant.
• Per-arena chat, visibility, scoreboards, broadcasts, temporary worlds, mobs, tasks, and generated resources are isolated or cleaned up.
• Build/test/runtime validation from the project’s existing Maven or Gradle setup was run when available.