Restore websocket docs and add sidebar navigation

Co-authored-by: milutinke <441903+milutinke@users.noreply.github.com> Agent-Logs-Url: https://github.com/MCCTeam/Minecraft-Console-Client/sessions/c762752f-46be-44f6-a05d-8c5effc8ef43
2026-08-15 13:04:36 +00:00 · 2026-03-25 13:51:10 +00:00 · 2026-03-25 13:51:10 +00:00 · 6d6d1105eb
commit 6d6d1105eb
parent c8c9f9ada5
4 changed files with 1198 additions and 0 deletions
--- a/docs/guide/websocket/README.md
+++ b/docs/guide/websocket/README.md
@ -0,0 +1,118 @@
+# WebSocket Bot
+
+The WebSocket Bot is an **external example bot** that lets you remotely control MCC over WebSocket.
+It runs a local WebSocket server inside your MCC session, accepts commands as JSON messages, and pushes game events back to connected clients in real time.
+
+::: warning External Bot
+This bot is **not** built into MCC.
+You load it as a standalone script with `/script ChatBots/WebSocketBot.cs`.
+:::
+
+## Quick Start
+
+1. Copy `config/ChatBots/WebSocketBot.cs` into your MCC `config/ChatBots/` folder (it ships in the repo under that path).
+2. Open the file and edit the line near the top:
+   ```csharp
+   MCC.LoadBot(new WebSocketBot("127.0.0.1", 8043, "wspass12345"));
+   ```
+   - Replace `127.0.0.1` with the IP to bind (use `+` or `*` for all interfaces).
+   - Replace `8043` with your preferred port.
+   - Replace `wspass12345` with a strong password.
+3. Optionally enable debug logging:
+   ```csharp
+   MCC.LoadBot(new WebSocketBot("127.0.0.1", 8043, "mypassword", debugMode: true));
+   ```
+4. In MCC, run: `/script ChatBots/WebSocketBot.cs`
+
+The bot starts a WebSocket server. Connect to `ws://127.0.0.1:8043/` with any WebSocket client.
+
+## Protocol Overview
+
+All communication uses JSON over WebSocket text frames.
+
+### Authentication Flow
+
+```
+Connect via WebSocket
+        |
+        v
+(Optional) Send "ChangeSessionId" to set a friendly session name
+        |
+        v
+Send "Authenticate" with the configured password
+        |
+        v
+Send commands and receive events
+```
+
+### Sending Commands
+
+Commands are JSON objects with this shape:
+
+```json
+{
+  "command": "CommandName",
+  "requestId": "any-unique-string",
+  "parameters": [1, "text", true]
+}
+```
+
+- `command` - the procedure name (case-sensitive)
+- `requestId` - a client-generated ID so you can match responses to requests
+- `parameters` - an ordered array of arguments (types depend on the command)
+
+Every command produces an `OnWsCommandResponse` event with `success`, `requestId`, and optionally `message`.
+
+### Sending Plain Text
+
+You can also send plain text directly:
+- Text starting with `/` is forwarded to MCC as an internal command (e.g., `/move north`).
+- Other text is sent as chat.
+
+### Receiving Events
+
+Events arrive as JSON:
+
+```json
+{
+  "event": "EventName",
+  "data": "{ ... serialized payload ... }"
+}
+```
+
+The `data` field is a JSON string that you parse separately to get the event payload.
+
+## Enum Serialization (String Names)
+
+All enum values (ItemType, EntityType, Direction, Hand, etc.) are serialized as **string names**, not numeric IDs.
+
+For example, an entity of type `Zombie` appears as:
+```json
+{ "type": "Zombie", "location": { "x": 10, "y": 64, "z": -20 } }
+```
+
+When sending commands that accept enum parameters, you can pass **either** a string name or a numeric value:
+```json
+{ "command": "InteractEntity", "requestId": "abc", "parameters": [42, "Interact", "MainHand"] }
+```
+or:
+```json
+{ "command": "InteractEntity", "requestId": "abc", "parameters": [42, 0, 0] }
+```
+
+Two dedicated commands let you query the full mapping tables:
+- `GetItemTypeMappings` returns `{ "DiamondSword": 798, "Stone": 1, ... }`
+- `GetEntityTypeMappings` returns `{ "Player": 128, "Zombie": 119, ... }`
+
+These are useful if your client needs a name-to-ID lookup for the current MCC version.
+
+## Reference
+
+- [Commands](Commands.md) - full list of available commands
+- [Events](Events.md) - full list of emitted events
+
+## Compatibility
+
+- Requires any MCC version that supports `/script` (standalone MCCScript 1.0 bots).
+- Uses only `System.Text.Json` (built into .NET), so no extra DLLs are needed.
+- Compatible with [MCC.js](https://github.com/milutinke/MCC.js) and any WebSocket client library.