Minecraft Plugin Development

Use this skill for Minecraft server plugin work in the Paper, Spigot, and Bukkit ecosystem.

This skill is especially useful for gameplay-heavy plugins such as combat systems, wave or boss encounters, war or team modes, arenas, kit systems, cooldown-based abilities, scoreboards, and config-driven game rules.

For grounded implementation patterns drawn from real Paper plugins, load these references as needed:

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

Scope

• In scope: Paper, Spigot, Bukkit plugin development
• In scope: 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, and PvP/PvE game loops
• In scope: Java-based server plugin architecture, debugging, refactoring, and feature implementation
• Out of scope by default: Fabric mods, Forge mods, client mods, Bedrock add-ons

If the user says "Minecraft plugin" but the stack is unclear, first determine whether the project is Paper/Spigot/Bukkit or a modding stack.

Default Working Style

When this skill triggers:

1. Identify the server API and version target.
2. Identify the build system and Java version.
3. Inspect plugin.yml, the main plugin class, and command or listener registration.
4. Map the gameplay flow before editing code:
   • player lifecycle
   • game phases
   • timers and scheduled tasks
   • team, arena, or match state
   • config and persistence
5. Make the smallest coherent change that keeps registration, config, and runtime behavior aligned.

If the plugin is gameplay-heavy or stateful, read references/project-patterns.md and references/state-sessions-and-phases.md before editing.

If the task touches arena isolation, map instances, chest or resource refills, wave spawning, route voting, spectator visibility, or game-specific chat, also read references/minigame-instance-flow.md.

If the task touches persistent player progression, profile saves, economy rewards, perks, buffs, quests, custom combat events, or long-running shared PvP servers, also read references/persistent-progression-and-events.md.

If the task touches build files, plugin.yml metadata, shaded dependencies, generated resource output, deployment to a test server, optional plugin integrations, or release validation, also read references/build-test-and-runtime-validation.md.

Project Discovery Checklist

Check these first when present:

• plugin.yml
• pom.xml, build.gradle, or build.gradle.kts
• the plugin main class extending JavaPlugin
• command executors and tab completers
• listener classes
• config bootstrap code for config.yml, messages, kits, arenas, or custom YAML files

…