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](references/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: ```powershell npm install -g @plugdev/cli ``` Or one-shot: `npx @plugdev/cli@latest <command>`. 2. **Initialize the project** if there is no `plugdev.yml`: ```powershell 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: ```powershell plugdev agent install --codex ``` 4. **Boot the loop:** ```powershell 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](references/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 | Goal | Command | |------|--------| | Interactive TUI | `plugdev` / `plug` | | One-shot test loop | `plug run` | | Wipe worlds | `plug clean` | | Cold run folder | `plug clean --all` | | Multi-module pick | `plugdev module list|use` | | Test deps | `plugdev deps add|remove|list` | | Headless (agents) | `plugdev server start|stop|status|command|logs` | | Listing shots/GIFs (Windows) | `plugdev capture run` / `shot` / `gif` | | Scripting | add `--json` | 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 | Item | Value | |------|--------| | Bins | `plug` and `plugdev` (same CLI) | | Config | `plugdev.yml` | | Run dir | `.plugdev/run/` | | Cache | `~/.plugdev/` | | Modules | `plugdev module list|use` (multi-module Maven/Gradle) | | Deps | `plugdev deps add|remove|list` (+ TUI Dependencies) | | Reload | Safe JAR reload (not `/reload`); optional `--hotswap` for method bodies | | Folia | Prefer full restart over safe reload | | Headless | `plugdev server start|stop|status|command|logs` + `--json` | | MCP | `npx @plugdev/mcp` — structured tools for the same loop | | Skill install | `npx skills add mattbaconz/plugdev --skill plugdev` | | Docs | https://pluglabs.app/plugdev |