From 397ab07d1fcecc8f173ab7d061630cfd68e8b506 Mon Sep 17 00:00:00 2001 From: BruceChen Date: Sun, 22 Mar 2026 16:20:15 +0800 Subject: [PATCH] [skipci] docs: update MCC development workflow documentation - Revised the SKILL.md file to enhance clarity and detail regarding the development workflow for Minecraft Console Client (MCC). - Expanded sections on project structure, build commands, and debugging steps, including specific instructions for compiling, starting a test server, and running MCC. - Added environment setup details and a checklist for server configuration, improving usability for developers. - Included new tools and scripts for server management and decompilation processes, streamlining the development experience. These updates provide comprehensive guidance for developers working with MCC in WSL. --- .skills/mcc-dev-workflow/SKILL.md | 154 ++++++++++++++++++++++++++---- 1 file changed, 135 insertions(+), 19 deletions(-) diff --git a/.skills/mcc-dev-workflow/SKILL.md b/.skills/mcc-dev-workflow/SKILL.md index f0c3c5b9..eb2aff31 100644 --- a/.skills/mcc-dev-workflow/SKILL.md +++ b/.skills/mcc-dev-workflow/SKILL.md @@ -1,33 +1,149 @@ --- -name: mcc-development-workflow -description: Documentation of the typical development workflow for Minecraft Console Client (MCC), including project structure, build commands, and debugging steps. +name: mcc-dev-workflow +description: Build, run, and debug Minecraft Console Client (MCC) in WSL. Use when the user wants to compile MCC, start a Minecraft test server, connect MCC to a server, debug MCC protocol issues, or run MCC commands. --- # MCC Development Workflow ## Project Overview -- Repo: `~/Minecraft/Minecraft-Console-Client` (env var `$MCC_REPO`) + - Solution: `MinecraftClient.sln` (projects: `MinecraftClient` + `ConsoleInteractive`) - Build: `dotnet build MinecraftClient.sln -c Release` -- Servers: `~/Minecraft/Servers/` (env var `$MCC_SERVERS`) +- Output: `MinecraftClient/bin/Release/net10.0/MinecraftClient` +- Servers: `MinecraftOfficial/downloads//` — server.jar + runtime data (config, world, etc.) + +Environment: WSL Ubuntu, Java 21, .NET 10 SDK, tmux, python3. + +## Compile + +```bash +dotnet build MinecraftClient.sln -c Release +``` + +## Start a Test Server + +Servers live in `MinecraftOfficial/downloads/` with directories named by version (e.g. `1.20.6`, `1.21.11`). + +```bash +tools/start-server.sh 1.20.6 +``` + +Creates a tmux session `mc-1_20_6` with a named pipe `stdin.pipe` for command input. The server persists across Cursor sessions. + +```bash +echo "op CursorBot" > MinecraftOfficial/downloads/1.20.6/stdin.pipe # server command +tmux capture-pane -t mc-1_20_6 -p -S -50 # view output +echo "stop" > MinecraftOfficial/downloads/1.20.6/stdin.pipe # stop +``` + +### Server config checklist + +- `eula.txt`: `eula=true` +- `server.properties`: `online-mode=false` for offline testing + +## Run MCC + +ConsoleInteractive is patched for non-interactive terminals. + +```bash +MCC_FILE_INPUT=1 dotnet run --project MinecraftClient -c Release -- CursorBot - localhost 2>&1 +``` + +- Format: `MinecraftClient `, password `-` = offline mode +- Use `block_until_ms: 0` to background; `sleep 2` then read terminal to confirm join +- Config: `MinecraftClient.ini` (auto-generated). Set `MinecraftVersion = "auto"` unless pinning. + +### FileInputBot + +Set `MCC_FILE_INPUT=1` (shown above). MCC monitors `mcc_input.txt`: + +```bash +echo "inventory player list" >> mcc_input.txt +``` + +Polled every ~500ms. `sleep 1` then read terminal for response. + +### RCON + +```bash +tools/mc-rcon.sh "give CursorBot diamond_sword 1" +tools/mc-rcon.sh "op CursorBot" +tools/mc-rcon.sh "say hello" 25575 test123 # explicit port and password +``` + +## Verify Connection + +MCC output: `[MCC] Server was successfully joined.` +Server output: `CursorBot joined the game` + +## Server Lifecycle + +**Keep the server running** unless you need to restart/switch version/user asks to stop. + +Check before starting: `tmux list-sessions 2>/dev/null | grep "^mc-"` ## Typical Debug Workflow -1. `~/Minecraft/Servers/start-server.sh 1.20.6-Vanilla` (background) -2. Wait for "Done" in server output -3. Build: `dotnet build $MCC_REPO/MinecraftClient.sln -c Release` -4. Run MCC: `cd $MCC_REPO && MCC_FILE_INPUT=1 dotnet run --project MinecraftClient -c Release -- CursorBot - localhost 2>&1` -5. RCON: `mc-rcon "op CursorBot"` -6. MCC cmd: `echo "inventory player list" >> $MCC_REPO/mcc_input.txt` -7. Read terminal file to see output -8. Kill MCC → rebuild → repeat -## Timing Reference +1. `tools/start-server.sh 1.20.6` (background, `block_until_ms: 0`) +2. Wait for "Done": `tmux capture-pane -t mc-1_20_6 -p -S -5` +3. Build: `dotnet build MinecraftClient.sln -c Release` +4. Run MCC: `MCC_FILE_INPUT=1 dotnet run --project MinecraftClient -c Release --no-build -- CursorBot - localhost 2>&1` (background, `block_until_ms: 0`) +5. `sleep 2`, read terminal to confirm join +6. RCON: `tools/mc-rcon.sh "op CursorBot"` +7. MCC cmd: `echo "inventory player list" >> mcc_input.txt` +8. `sleep 1`, read terminal for output +9. `pkill -f MinecraftClient` → rebuild → repeat + | Operation | Typical Duration | |-----------|-----------------| -| MCC startup → join server | ~1s | -| FileInput command → response | <500ms | +| MCC startup → join | ~1s | +| FileInput → response | <500ms | -## Official Minecraft Server Source (Decompiled) -`$MCC_REPO/MinecraftOfficial/` contains decompiled official server code for protocol reference. -When investigating protocol details (packet structure, field order, NBT format, etc.), -look at the corresponding version's decompiled source as authoritative reference. +## Tools + +All in `tools/`: + +| Script | Purpose | +|--------|---------| +| `start-server.sh ` | Start MC server in tmux | +| `mc-rcon.sh "cmd" [port] [pw]` | RCON command (default: 25575, test123) | +| `decompile.sh --version ` | Decompile MC version + download server.jar | +| `mcc-env.sh` | Source for shell helpers (`mc-start`, `mcc-build`, etc.) | + +`mcc-env.sh` exports `$MCC_REPO` and `$MCC_SERVERS` and defines convenience functions. Source it in interactive shells or `~/.bashrc`. In Cursor's non-interactive Shell, use the standalone scripts directly. + +## Decompiled Server Source + +`MinecraftOfficial/` contains decompiled official server/client code: + +```bash +tools/decompile.sh --version 1.21.1 # server (default) +tools/decompile.sh --version 1.21.1 --side CLIENT # client +``` + +Auto-downloads `MinecraftDecompiler.jar` if missing; downloads `server.jar` into `MinecraftOfficial/downloads//` for SERVER side. + +## Key Code Paths + +| Area | Files | +|------|-------| +| Protocol version map | `Protocol/ProtocolHandler.cs` | +| Packet palette (ID mapping) | `Protocol/Handlers/PacketPalettes/PacketPalette*.cs` | +| Core packet handling | `Protocol/Handlers/Protocol18.cs` | +| Data serialization | `Protocol/Handlers/DataTypes.cs` | +| Structured components (1.20.6+) | `Protocol/Handlers/StructuredComponents/` | +| Client logic | `McClient.cs` | +| Config phase packets | `Protocol/Handlers/ConfigurationPacketTypesIn.cs` / `Out.cs` | +| Console I/O library | `ConsoleInteractive/` | + +## Debugging Tips + +- Debug output: `DebugMessages = true` in `[Logging]` of `MinecraftClient.ini` +- Protocol version shown during connection: `Server version : X.XX.X (protocol vNNN)` +- Server `EncoderException` = protocol mismatch +- Packet reference: https://minecraft.wiki/w/Java_Edition_protocol/Packets +- Use `block_until_ms: 0` for long-running processes, read terminal files for output + +## Git Commits + +Commit at meaningful milestones. Messages in English with sufficient context.