Use this skill when building or modifying Minecraft server plugins for Paper, Spigot, or Bukkit, including plugin.yml setup, commands, listeners, schedulers, player state, team or arena systems, persistent progression, economy or profile data, configuration files, Adventure text, and version-safe API usage. Trigger for requests like "build a Minecraft plugin", "add a Paper command", "fix a Bukkit listener", "create plugin.yml", "implement a minigame mechanic", "add a perk or quest system", or "debug server plugin behaviour".
Instrucciones de origen · Vista previa de solo lectura
name
minecraft-plugin-development
description
Use this skill when building or modifying Minecraft server plugins for Paper, Spigot, or Bukkit, including plugin.yml setup, commands, listeners, schedulers, player state, team or arena systems, persistent progression, economy or profile data, configuration files, Adventure text, and version-safe API usage. Trigger for requests like "build a Minecraft plugin", "add a Paper command", "fix a Bukkit listener", "create plugin.yml", "implement a minigame mechanic", "add a perk or quest system", or "debug server plugin behaviour".
metadata
{"skill-author":"Marie-Lynne Block"}
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/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:
Identify the server API and version target.
Identify the build system and Java version.
Inspect plugin.yml, the main plugin class, and command or listener registration.
Map the gameplay flow before editing code:
player lifecycle
game phases
timers and scheduled tasks
team, arena, or match state
config and persistence
Make the smallest coherent change that keeps registration, config, and runtime behaviour aligned.
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
generated resource output such as target/classes, build/resources, or copied plugin jars
scheduler usage through Bukkit scheduler APIs
any player data, team state, arena state, or match state containers
Core Rules
Prefer the concrete server API in the repo
If the project already targets Paper APIs, keep using Paper-first APIs instead of downgrading to generic Bukkit unless compatibility is explicitly required.
Do not assume an API exists across all versions. Check the existing dependency and surrounding code style first.
Keep registration in sync
When adding commands, permissions, or listeners, update the relevant registration points in the same change:
plugin.yml
plugin startup registration in onEnable
any permission checks in code
any related config or message keys
Respect main-thread boundaries
Do not touch world state, entities, inventories, scoreboards, or most Bukkit API objects from async tasks unless the API explicitly permits it.
Use async tasks for external I/O, heavy computation, or database work, then switch back to the main thread before applying gameplay changes.
Model gameplay as state, not scattered booleans
For gameplay plugins, prefer explicit state objects over duplicated flags:
match or game phase
player role or class
cooldown state
team membership
arena assignment
alive, eliminated, spectating, or queued state
When the feature affects match-heavy minigames or persistent-brawl gameplay, look for hidden state transitions first before patching symptoms.
For multi-arena plugins, isolate per-game visibility, chat recipients, scoreboards, loot, and entity ownership. Do not let one arena observe or mutate another arena by accident.
Favour config-driven values
When the feature includes damage, cooldowns, rewards, durations, messages, map settings, or toggles:
prefer config-backed values over hardcoding
provide sensible defaults
keep key names stable and readable
validate or sanitize missing values
Be careful with reload behaviour
Avoid promising safe hot reload unless the code already supports it well.
On config reload, ensure in-memory caches, scheduled tasks, and gameplay state are handled consistently.
Implementation Patterns
Commands
For new commands:
add the command to plugin.yml
implement executor and tab completion when needed
validate sender type before casting to Player
separate parsing, permission checks, and gameplay logic
send clear player-facing feedback for invalid usage
clean up on quit, kick, death, match end, and plugin disable
avoid memory leaks from stale maps keyed by Player
prefer UUID for persistent tracking unless a live player object is strictly needed
Text and Messages
When the project uses Adventure or MiniMessage:
follow the existing formatting approach
avoid mixing legacy colour codes and Adventure styles without a reason
keep message templates configurable when messages are gameplay-facing
High-Risk Areas
Pay extra attention when editing:
damage handling and custom combat logic
death, respawn, spectator, and elimination flow
arena join and leave flow
scoreboard or boss bar updates
inventory mutation and kit distribution
async database or file access
economy, quest, perk, and profile mutation
custom event dispatch or extension registries
version-sensitive API calls
shutdown and cleanup in onDisable
cross-arena visibility, chat, and broadcast isolation
map copy, unload, and folder deletion logic
mob, NPC, projectile, or temporary entity ownership
chest or resource refill systems
Output Expectations
When implementing or revising plugin code:
produce runnable Java code, not pseudo-code, unless the user asks for design only
mention any required updates to plugin.yml, config files, build files, or resources
call out version assumptions explicitly
point out thread-safety or API-compatibility risks when they exist
preserve the project's existing conventions and folder structure
When the requested change touches plugin startup, async data, match flow, class systems, or rotating maps, consult the matching reference file before editing.
Validation Checklist
Before finishing, verify as many of these as the task allows:
the command, listener, or feature is registered correctly
plugin.yml matches the implemented behaviour
imports and API types match the targeted server stack
scheduler usage is safe
config keys referenced in code exist or have defaults
state cleanup paths exist for match end, player quit, and plugin disable
per-arena chat, visibility, scoreboards, and broadcasts are isolated
temporary worlds, mobs, tasks, and generated resources are cleaned up
there are no obvious null, cast, or lifecycle hazards
Common Gotchas
Casting CommandSender to Player without checking
Updating Bukkit state from async tasks
Forgetting to register listeners or declare commands in plugin.yml
Using Player objects as long-lived map keys when UUID is safer
Leaving repeating tasks alive after a round, arena, or plugin shutdown
Hardcoding gameplay constants that should live in config
Assuming Paper-only APIs in a Spigot-targeted plugin
Treating reload as free even though stateful plugins often break under reload
Broadcasting, showing players, or applying scoreboard changes across unrelated game instances
Loading or mutating chest/container blocks before their chunks are available
Forgetting to unregister spawned mobs or temporary entities from the owning game
Editing generated files under target/classes or build/resources instead of source files under src/main/resources
Preferred Response Shape
For substantial requests, structure work like this:
Current plugin context and assumptions
Gameplay or lifecycle impact
Code changes
Required registration or config updates
Validation and remaining risks
For small requests, keep the answer concise but still mention any needed plugin.yml, config, or lifecycle updates.
