Plugdev

PlugDev test loop

PlugDev is the local test environment for Minecraft plugins. Prefer it over manually starting Paper and copying JARs.

For agent work, use structured MCP tools when available or CLI --json from the plugin project directory. Check plug -V first: background capture and native player controls require CLI 1.4.0+ (MCP 0.5.0+). Read capture.md for screenshots, GIFs, animated cursors, GUI clicks, movement and test players. Reuse the user's configured client; do not replace their Prism instance or move desktop focus. If the installed skill contains references/local-preferences.md, read it for preferences specific to that machine.

First moves (agent: set up the best env)

Inspect the project instructions, configuration, selected module and running server first. Reuse the installed CLI and working environment. For setup requested by the user:

1. Install CLI if plugdev / plug is missing from PATH:

   npm install -g @plugdev/cli
   

   Or one-shot: npx @plugdev/cli@latest <command>.

2. Initialize the project if there is no plugdev.yml:

   plugdev init --setup
   

   This writes project config and prefetches the selected runtime into ~/.plugdev/. Agent rules and MCP are optional separate setup; do not overwrite working project instructions. agent install --mcp merges .cursor/mcp.json and .mcp.json. After the first MCP write, the editor needs to reload MCP.

3. If Codex project wiring is requested:

   plugdev agent install --codex
   

4. Boot the loop:

   plug run
   

5. If boot or detection fails, run plug doctor and fix what it reports (Java 21+, Node 22+, Gradle/Maven). Paper/Folia 26.x needs Java 25+.

6. Multi-module reactors: plugdev module list then plugdev module use <name> (or TUI Module).

7. Background screenshots/GIFs (Windows): read capture.md. Start the local server, then use capture shot|gif|run. Select an existing Fabric 26.1.2 Prism instance with client start --instance "FO 26.1.2" for native screenshots, animated cursors, GUI clicks and player control. Otherwise automatic launch uses an isolated Minecraft 1.21.4 profile with capped rendering and idle shutdown; existing clients can be bound explicitly. Capture never activates a window or injects desktop input. Requires FFmpeg gfxcapture and FFprobe. Bots cannot render screenshots.

Day loop

After the server is ready, joining players are auto-OP when dev.op is true (default). Type console commands in the same terminal (RCON), e.g. list, gamemode creative @a.

MCP (optional structured tools)

When .cursor/mcp.json or .mcp.json includes PlugDev (via init --mcp / agent install --mcp), prefer MCP tools for headless control:

• plugdev_doctor, plugdev_setup, plugdev_init
• plugdev_build_plugin, plugdev_sync_plugin
• plugdev_start_server, plugdev_stop_server, plugdev_get_server_status
• plugdev_tail_logs, plugdev_run_server_command, plugdev_op_player
• plugdev_list_modules, plugdev_use_module
• plugdev_list_deps, plugdev_add_dep, plugdev_remove_dep
• plugdev_agent_install, plugdev_cache_prefetch, plugdev_cache_status, plugdev_clean
• plugdev_list_configs, plugdev_get_config, plugdev_set_config
• plugdev_open_client — embedded client join
• plugdev_capture_doctor, plugdev_capture_shot, plugdev_capture_gif, plugdev_capture_run
• plugdev_run_test_loop — build → sync → start → OP

CLI remains primary for interactive plug run (server + watch + client join). MCP is the same loop without a TTY.

Install MCP alone: npx -y @plugdev/mcp (stdio).

Hard rules

• Prefer plug run over manually starting Paper.
• Do not use Bukkit /reload — PlugDev uses safe JAR reload via bootstrap.
• On Folia, prefer full restart over safe reload.
• Optional --hotswap / watch.reload.java: hotswap is method-body JDWP redefine only; structural changes fall back to safe reload.
• Do not delete ~/.plugdev unless the user asks (plugdev cache clear).
• Background capture needs a non-minimized rendered Windows client and unlocked desktop. Never refocus Minecraft or substitute desktop capture. Use capture client for background startup; open --client is the interactive launcher. Do not claim headless or untested platform support.

Facts