--- name: minecraft-rcon description: >- Execute live Minecraft server commands against mc-forge-server via RCON (rcon-cli), including batched commands, server inspection, and LuckPerms administration. --- # Minecraft RCON Runbook Shared procedure and helper script for running live server commands on the Docker Forge 1.20.1 server (`mc-forge-server`) via `rcon-cli`. --- ## Quick Usage Ensure `mc-forge-server` is running (`docker compose ps`), then use [rcon.py](file:///home/wakaria/dev/minecraft-server/.agents/plugins/minecraft-manager/skills/minecraft-rcon/scripts/rcon.py): ```bash # Preview without executing: python3 .agents/plugins/minecraft-manager/skills/minecraft-rcon/scripts/rcon.py --dry-run "list" # Run a single command: python3 .agents/plugins/minecraft-manager/skills/minecraft-rcon/scripts/rcon.py "list" # Batch multiple commands in a single docker exec call: python3 .agents/plugins/minecraft-manager/skills/minecraft-rcon/scripts/rcon.py "save-all" "say Server saved!" ``` --- ## Common Server Commands | Task | Command | | :--- | :--- | | Check online players | `list` | | Broadcast message | `say ` | | Force world save | `save-all` | | Set time / weather | `time set day`, `weather clear` | | Whitelist management | `whitelist add `, `whitelist remove `, `whitelist list` | | LuckPerms group permission | `lp group permission set true` | | LuckPerms user group | `lp user parent set ` | --- ## Operational Notes & Gotchas - **LuckPerms stdout on Forge 1.20.1:** `lp` commands execute asynchronously and return empty stdout over `rcon-cli`. To verify LuckPerms state, run `lp export ` and inspect `server/data/config/luckperms/.json.gz` (and remove the temporary export afterward). - **Offline-mode player UUIDs:** Because the server runs in offline mode, LuckPerms cannot look up Mojang UUIDs for players who have not joined since LuckPerms was installed. Resolve the player's UUID from [usercache.json](file:///home/wakaria/dev/minecraft-server/server/data/usercache.json) when targeting offline players. - **Connection refused on port `25575`:** If `mc-forge-server` just restarted, wait for `docker compose ps` to report `healthy` before retrying RCON. - **Docker socket in sandboxed runs:** If `docker compose ps` or `rcon.py` fails with `dial unix /var/run/docker.sock: connect: no such file or directory`, `/var/run/docker.sock` is likely blocked by sandbox isolation rather than Docker being stopped. Try sandboxed first, then re-run outside the sandbox with user approval if blocked. - **Safety guardrails:** Confirm with the user before running disruptive commands (`stop`, `kick`, `ban`, `pardon`, `whitelist off`, `difficulty`, or `gamerule` changes).