From 6d6d1105ebc68585d8148d8b7a0125dc03213eee Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 25 Mar 2026 13:51:10 +0000
Subject: [PATCH] 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
---
 docs/.vuepress/configs/l10n_configs/en.ts |   9 +
 docs/guide/websocket/Commands.md          | 527 +++++++++++++++++++++
 docs/guide/websocket/Events.md            | 544 ++++++++++++++++++++++
 docs/guide/websocket/README.md            | 118 +++++
 4 files changed, 1198 insertions(+)
 create mode 100644 docs/guide/websocket/Commands.md
 create mode 100644 docs/guide/websocket/Events.md
 create mode 100644 docs/guide/websocket/README.md

diff --git a/docs/.vuepress/configs/l10n_configs/en.ts b/docs/.vuepress/configs/l10n_configs/en.ts
index 795a765b..90cac2cc 100644
--- a/docs/.vuepress/configs/l10n_configs/en.ts
+++ b/docs/.vuepress/configs/l10n_configs/en.ts
@@ -62,6 +62,15 @@ export const defaultThemeConfig_en: DefaultThemeLocaleData = {
         "/guide/creating-text-script.md",
         "/guide/chat-bots.md", 
         "/guide/creating-bots.md", 
+        {
+            text: "WebSocket Bot",
+            collapsible: true,
+            children: [
+                "/guide/websocket/README.md",
+                "/guide/websocket/Commands.md",
+                "/guide/websocket/Events.md",
+            ],
+        },
         "/guide/ai-assisted-development.md",
         "/guide/contibuting.md"
     ],
diff --git a/docs/guide/websocket/Commands.md b/docs/guide/websocket/Commands.md
new file mode 100644
index 00000000..8fe8232b
--- /dev/null
+++ b/docs/guide/websocket/Commands.md
@@ -0,0 +1,527 @@
+# WebSocket Commands
+
+Commands are JSON objects sent over the WebSocket connection.
+Each command produces a response through the [`OnWsCommandResponse`](Events.md#onwscommandresponse) event.
+
+```json
+{
+  "command": "CommandName",
+  "requestId": "unique-id",
+  "parameters": []
+}
+```
+
+## Protocol Commands
+
+These commands manage the WebSocket session itself.
+
+### `Authenticate`
+
+Authenticate with the configured password.
+Must be called before any other command (except `ChangeSessionId`).
+
+**Parameters:**
+
+| Index | Type   | Description |
+|-------|--------|-------------|
+| 0     | string | Password    |
+
+**Example:**
+```json
+{
+  "command": "Authenticate",
+  "requestId": "auth-001",
+  "parameters": ["wspass12345"]
+}
+```
+
+### `ChangeSessionId`
+
+Rename the current session. Can be called without authentication.
+The new ID must be 1-32 characters and not already taken.
+
+**Parameters:**
+
+| Index | Type   | Description    |
+|-------|--------|----------------|
+| 0     | string | New session ID |
+
+**Example:**
+```json
+{
+  "command": "ChangeSessionId",
+  "requestId": "rename-001",
+  "parameters": ["my-bot"]
+}
+```
+
+## Logging Commands
+
+### `LogToConsole`
+
+Log a message to the MCC console.
+
+**Parameters:**
+
+| Index | Type   | Description |
+|-------|--------|-------------|
+| 0     | string | Message     |
+
+### `LogDebugToConsole`
+
+Log a debug message to the MCC console (only visible in debug mode).
+
+**Parameters:**
+
+| Index | Type   | Description |
+|-------|--------|-------------|
+| 0     | string | Message     |
+
+### `LogToConsoleTranslated`
+
+Log a translated message using an MCC translation key.
+
+**Parameters:**
+
+| Index | Type   | Description      |
+|-------|--------|------------------|
+| 0     | string | Translation key  |
+
+### `LogDebugToConsoleTranslated`
+
+Log a translated debug message.
+
+**Parameters:**
+
+| Index | Type   | Description      |
+|-------|--------|------------------|
+| 0     | string | Translation key  |
+
+## Session Commands
+
+### `ReconnectToTheServer`
+
+Reconnect to the Minecraft server.
+
+**Parameters:**
+
+| Index | Type | Description                         |
+|-------|------|-------------------------------------|
+| 0     | int  | Extra reconnect attempts (default 3)|
+| 1     | int  | Delay in seconds (default 0)        |
+
+### `DisconnectAndExit`
+
+Disconnect from the server and shut down MCC.
+No parameters.
+
+## Chat Commands
+
+### `SendPrivateMessage`
+
+Send a private message to a player.
+
+**Parameters:**
+
+| Index | Type   | Description   |
+|-------|--------|---------------|
+| 0     | string | Player name   |
+| 1     | string | Message       |
+
+## Script Commands
+
+### `RunScript`
+
+Run an MCC script file.
+
+**Parameters:**
+
+| Index | Type   | Description |
+|-------|--------|-------------|
+| 0     | string | File name   |
+
+## World and Terrain Commands
+
+### `GetTerrainEnabled`
+
+Check if terrain handling is enabled.
+No parameters. Returns `{ "enabled": true/false }`.
+
+### `SetTerrainEnabled`
+
+Enable or disable terrain handling.
+
+**Parameters:**
+
+| Index | Type | Description |
+|-------|------|-------------|
+| 0     | bool | Enabled     |
+
+### `GetWorld`
+
+Check if world data is available.
+No parameters. Returns `{ "available": true }` if terrain is enabled.
+
+### `DigBlock`
+
+Break a block at the given coordinates.
+Validates the block is within 6 blocks and is not air.
+
+**Parameters:**
+
+| Index | Type    | Description                    |
+|-------|---------|--------------------------------|
+| 0     | double  | X coordinate                   |
+| 1     | double  | Y coordinate                   |
+| 2     | double  | Z coordinate                   |
+| 3     | string  | Direction (optional, e.g. "Down") |
+
+The `Direction` parameter accepts string names: `Down`, `Up`, `North`, `South`, `West`, `East`.
+
+## Entity Commands
+
+### `GetEntityHandlingEnabled`
+
+Check if entity handling is enabled.
+No parameters. Returns `{ "enabled": true/false }`.
+
+### `GetEntities`
+
+Get all tracked entities.
+No parameters. Returns a dictionary of entity ID to entity object.
+
+Entity types are serialized as string names (e.g., `"Zombie"`, `"Player"`).
+
+### `InteractEntity`
+
+Interact with an entity.
+
+**Parameters:**
+
+| Index | Type   | Description                          |
+|-------|--------|--------------------------------------|
+| 0     | int    | Entity ID                            |
+| 1     | string | Interaction type (`Interact`, `Attack`, `InteractAt`) |
+| 2     | string | Hand (optional, `MainHand` or `OffHand`) |
+
+### `SendEntityAction`
+
+Send an entity action.
+
+**Parameters:**
+
+| Index | Type   | Description                  |
+|-------|--------|------------------------------|
+| 0     | string | Action type (e.g. `StartSneaking`, `StopSneaking`) |
+
+### `Sneak`
+
+Toggle sneaking.
+
+**Parameters:**
+
+| Index | Type | Description      |
+|-------|------|------------------|
+| 0     | bool | true to sneak, false to stop |
+
+## Movement Commands
+
+### `GetCurrentLocation`
+
+Get the player's current location.
+No parameters. Returns a location object with `x`, `y`, `z`.
+
+### `MoveToLocation`
+
+Move the player to a location using pathfinding.
+
+**Parameters:**
+
+| Index | Type   | Description                      |
+|-------|--------|----------------------------------|
+| 0     | double | X coordinate                     |
+| 1     | double | Y coordinate                     |
+| 2     | double | Z coordinate                     |
+| 3     | bool   | Allow unsafe (optional, false)   |
+| 4     | bool   | Allow direct teleport (optional) |
+| 5     | int    | Max offset (optional, 0)         |
+| 6     | int    | Min offset (optional, 0)         |
+
+### `ClientIsMoving`
+
+Check if the client is currently moving.
+No parameters. Returns `{ "moving": true/false }`.
+
+### `LookAtLocation`
+
+Make the player look at coordinates.
+
+**Parameters:**
+
+| Index | Type   | Description |
+|-------|--------|-------------|
+| 0     | double | X           |
+| 1     | double | Y           |
+| 2     | double | Z           |
+
+## Player Info Commands
+
+### `GetUsername`
+
+Get the player's username.
+No parameters. Returns `{ "username": "..." }`.
+
+### `GetUserUUID`
+
+Get the player's UUID.
+No parameters. Returns `{ "uuid": "..." }`.
+
+### `GetGamemode`
+
+Get the current gamemode.
+No parameters. Returns `{ "gamemode": 0 }`.
+
+### `GetYaw`
+
+Get the player's yaw rotation.
+No parameters. Returns `{ "yaw": 0.0 }`.
+
+### `GetPitch`
+
+Get the player's pitch rotation.
+No parameters. Returns `{ "pitch": 0.0 }`.
+
+### `GetOnlinePlayers`
+
+Get a list of online player names.
+No parameters. Returns a string array.
+
+### `GetOnlinePlayersWithUUID`
+
+Get online players with their UUIDs.
+No parameters. Returns a dictionary of UUID to player name.
+
+### `GetPlayersLatency`
+
+Get latency information for online players.
+No parameters.
+
+## Server Info Commands
+
+### `GetServerHost`
+
+Get the server hostname.
+No parameters. Returns `{ "host": "..." }`.
+
+### `GetServerPort`
+
+Get the server port.
+No parameters. Returns `{ "port": 25565 }`.
+
+### `GetServerTPS`
+
+Get the server TPS (ticks per second).
+No parameters. Returns `{ "tps": 20.0 }`.
+
+### `GetTimestamp`
+
+Get the current timestamp.
+No parameters. Returns `{ "timestamp": "..." }`.
+
+### `GetProtocolVersion`
+
+Get the Minecraft protocol version.
+No parameters. Returns `{ "protocolVersion": 769 }`.
+
+### `GetMaxChatMessageLength`
+
+Get the maximum chat message length.
+No parameters. Returns `{ "length": 256 }`.
+
+## Inventory Commands
+
+### `GetInventoryEnabled`
+
+Check if inventory handling is enabled.
+No parameters. Returns `{ "enabled": true/false }`.
+
+### `GetPlayerInventory`
+
+Get the player's inventory.
+No parameters. Returns the full inventory container with items.
+
+Item types are serialized as string names (e.g., `"DiamondSword"`, `"Stone"`).
+
+### `GetInventories`
+
+Get all open inventories.
+No parameters.
+
+### `WindowAction`
+
+Perform a window/inventory action.
+
+**Parameters:**
+
+| Index | Type   | Description                                       |
+|-------|--------|---------------------------------------------------|
+| 0     | int    | Inventory ID                                      |
+| 1     | int    | Slot ID                                           |
+| 2     | string | Action type (e.g. `LeftClick`, `RightClick`, `DropItemStack`) |
+
+### `ChangeSlot`
+
+Change the active hotbar slot.
+
+**Parameters:**
+
+| Index | Type  | Description       |
+|-------|-------|-------------------|
+| 0     | short | Slot number (0-8) |
+
+### `GetCurrentSlot`
+
+Get the currently selected hotbar slot.
+No parameters. Returns `{ "slot": 0 }`.
+
+### `SetSlot`
+
+Set the active slot (legacy command).
+
+**Parameters:**
+
+| Index | Type | Description |
+|-------|------|-------------|
+| 0     | int  | Slot number |
+
+### `ClearInventories`
+
+Clear tracked inventory state.
+No parameters.
+
+### `CloseInventory`
+
+Close an inventory window.
+
+**Parameters:**
+
+| Index | Type | Description  |
+|-------|------|--------------|
+| 0     | int  | Inventory ID |
+
+## Creative Mode Commands
+
+### `CreativeGive`
+
+Give an item in creative mode.
+
+**Parameters:**
+
+| Index | Type   | Description                                |
+|-------|--------|--------------------------------------------|
+| 0     | int    | Slot ID                                    |
+| 1     | string | Item type (e.g. `"DiamondSword"` or `798`) |
+| 2     | int    | Count                                      |
+
+### `CreativeDelete`
+
+Delete an item from a slot in creative mode.
+
+**Parameters:**
+
+| Index | Type | Description |
+|-------|------|-------------|
+| 0     | int  | Slot ID     |
+
+## Block Interaction Commands
+
+### `SendPlaceBlock`
+
+Place a block.
+
+**Parameters:**
+
+| Index | Type   | Description              |
+|-------|--------|--------------------------|
+| 0     | double | X coordinate             |
+| 1     | double | Y coordinate             |
+| 2     | double | Z coordinate             |
+| 3     | string | Direction (e.g. `"Up"`)  |
+| 4     | string | Hand (optional, `"MainHand"` or `"OffHand"`) |
+
+### `SendAnimation`
+
+Play arm swing animation.
+
+**Parameters:**
+
+| Index | Type   | Description                        |
+|-------|--------|------------------------------------|
+| 0     | string | Hand (optional, default `"MainHand"`) |
+
+### `UseItemInHand`
+
+Use the item currently held.
+No parameters.
+
+### `UpdateSign`
+
+Update text on a sign.
+
+**Parameters:**
+
+| Index | Type   | Description  |
+|-------|--------|--------------|
+| 0     | double | X coordinate |
+| 1     | double | Y coordinate |
+| 2     | double | Z coordinate |
+| 3     | string | Line 1       |
+| 4     | string | Line 2       |
+| 5     | string | Line 3       |
+| 6     | string | Line 4       |
+
+### `UpdateCommandBlock`
+
+Update a command block.
+
+**Parameters:**
+
+| Index | Type   | Description             |
+|-------|--------|-------------------------|
+| 0     | double | X coordinate            |
+| 1     | double | Y coordinate            |
+| 2     | double | Z coordinate            |
+| 3     | string | Command                 |
+| 4     | string | Mode (e.g. `"Sequence"`, `"Auto"`, `"Redstone"`) |
+| 5     | string | Flags                   |
+
+## Trading Commands
+
+### `SelectTrade`
+
+Select a villager trade.
+
+**Parameters:**
+
+| Index | Type | Description |
+|-------|------|-------------|
+| 0     | int  | Trade index |
+
+### `Respawn`
+
+Respawn after death.
+No parameters.
+
+## Mapping Commands (New)
+
+These commands address [issue #2805](https://github.com/MCCTeam/Minecraft-Console-Client/issues/2805), allowing clients to query enum mappings dynamically instead of maintaining hardcoded ID tables.
+
+### `GetItemTypeMappings`
+
+Get a dictionary of all ItemType names to their numeric IDs.
+No parameters. Returns `{ "DiamondSword": 798, "Stone": 1, ... }`.
+
+### `GetEntityTypeMappings`
+
+Get a dictionary of all EntityType names to their numeric IDs.
+No parameters. Returns `{ "Player": 128, "Zombie": 119, ... }`.
diff --git a/docs/guide/websocket/Events.md b/docs/guide/websocket/Events.md
new file mode 100644
index 00000000..310172fc
--- /dev/null
+++ b/docs/guide/websocket/Events.md
@@ -0,0 +1,544 @@
+# WebSocket Events
+
+Events are JSON messages pushed to all authenticated WebSocket clients.
+Each event has this structure:
+
+```json
+{
+  "event": "EventName",
+  "data": "{ ... serialized payload ... }"
+}
+```
+
+The `data` field is a JSON string. Parse it to access the event payload.
+
+All enum values are serialized as **string names** (e.g., `"Zombie"` instead of `119`).
+
+## Protocol Events
+
+### `OnWsCommandResponse`
+
+Sent after every command execution.
+
+**Payload:**
+```json
+{
+  "success": true,
+  "requestId": "your-request-id",
+  "message": "optional result or error message"
+}
+```
+
+Match the `requestId` to track which command produced this response.
+
+### `OnMccCommandResponse`
+
+Sent when a plain-text MCC command (starting with `/`) is executed.
+
+**Payload:**
+```json
+{
+  "command": "move north",
+  "status": "Done",
+  "result": ""
+}
+```
+
+### `OnGameJoined`
+
+Sent after the client joins the server and the game session starts.
+Payload: `"N/A"`
+
+### `OnWsRestarting`
+
+Sent when the WebSocket server is restarting (e.g., on reconnect).
+Payload: `"N/A"`
+
+### `OnWsConnectionClose`
+
+Sent when the WebSocket server is shutting down.
+Payload: `"N/A"`
+
+## Chat Events
+
+### `OnChatRaw`
+
+Sent for every incoming chat message, including the raw JSON.
+
+**Payload:**
+```json
+{
+  "text": "Formatted text content",
+  "json": "{ raw JSON from server }"
+}
+```
+
+### `OnChatPublic`
+
+Sent when a public chat message is detected.
+
+**Payload:**
+```json
+{
+  "sender": "PlayerName",
+  "message": "Hello world",
+  "rawText": "<PlayerName> Hello world"
+}
+```
+
+### `OnChatPrivate`
+
+Sent when a private message is detected.
+
+**Payload:**
+```json
+{
+  "sender": "PlayerName",
+  "message": "Secret message",
+  "rawText": "PlayerName whispers to you: Secret message"
+}
+```
+
+### `OnTeleportRequest`
+
+Sent when a teleport request is detected.
+
+**Payload:**
+```json
+{
+  "sender": "PlayerName",
+  "rawText": "PlayerName has requested to teleport to you"
+}
+```
+
+## Connection Events
+
+### `OnDisconnect`
+
+Sent when MCC disconnects from the server.
+
+**Payload:**
+```json
+{
+  "reason": "ConnectionLost",
+  "message": "Connection has been lost."
+}
+```
+
+Reason values: `ConnectionLost`, `UserLogout`, `InGameKick`, `LoginRejected`.
+
+## Entity Events
+
+Entity objects include their `type` as a string name (e.g., `"Zombie"`, `"Player"`).
+
+### `OnEntitySpawn`
+
+Sent when an entity spawns.
+
+**Payload:** Full entity object.
+
+### `OnEntityDespawn`
+
+Sent when an entity despawns.
+
+**Payload:** Full entity object.
+
+### `OnEntityMove`
+
+Sent when an entity moves.
+
+**Payload:** Full entity object with updated location.
+
+### `OnEntityAnimation`
+
+Sent when an entity plays an animation.
+
+**Payload:**
+```json
+{
+  "entity": { ... },
+  "animation": 0
+}
+```
+
+### `OnEntityHealth`
+
+Sent when an entity's health changes.
+
+**Payload:**
+```json
+{
+  "entity": { ... },
+  "health": 20.0
+}
+```
+
+### `OnEntityMetadata`
+
+Sent when entity metadata updates.
+
+**Payload:**
+```json
+{
+  "entity": { ... },
+  "metadata": { "0": ..., "1": ... }
+}
+```
+
+### `OnEntityEquipment`
+
+Sent when an entity's equipment changes.
+
+**Payload:**
+```json
+{
+  "entity": { ... },
+  "slot": 0,
+  "item": { "type": "DiamondSword", "count": 1, ... }
+}
+```
+
+Item types are string names (e.g., `"DiamondSword"`).
+
+### `OnEntityEffect`
+
+Sent when an entity gets an effect.
+
+**Payload:**
+```json
+{
+  "entity": { ... },
+  "effect": "Speed",
+  "amplifier": 1,
+  "duration": 600,
+  "flags": 0
+}
+```
+
+### `OnBlockBreakAnimation`
+
+Sent when a block break animation plays.
+
+**Payload:**
+```json
+{
+  "entity": { ... },
+  "location": { "x": 10, "y": 64, "z": -20 },
+  "stage": 5
+}
+```
+
+## Player Events
+
+### `OnPlayerJoin`
+
+Sent when a player joins the server.
+
+**Payload:**
+```json
+{
+  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "name": "PlayerName"
+}
+```
+
+### `OnPlayerLeave`
+
+Sent when a player leaves the server.
+
+**Payload:**
+```json
+{
+  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "name": "PlayerName"
+}
+```
+
+### `OnPlayerProperty`
+
+Sent when player properties update (e.g., speed, attack damage).
+
+**Payload:** Dictionary of property name to value.
+
+### `OnPlayerStatus`
+
+Sent when the player's status changes.
+
+**Payload:**
+```json
+{
+  "statusId": 0
+}
+```
+
+### `OnDeath`
+
+Sent when the player dies.
+Payload: `"N/A"`
+
+### `OnRespawn`
+
+Sent when the player respawns.
+Payload: `"N/A"`
+
+## Health and Experience Events
+
+### `OnHealthUpdate`
+
+Sent when the player's health or food level changes.
+
+**Payload:**
+```json
+{
+  "health": 20.0,
+  "food": 20
+}
+```
+
+### `OnSetExperience`
+
+Sent when experience updates.
+
+**Payload:**
+```json
+{
+  "experienceBar": 0.5,
+  "level": 10,
+  "totalExperience": 200
+}
+```
+
+## Game Events
+
+### `OnGamemodeUpdate`
+
+Sent when a player's gamemode changes.
+
+**Payload:**
+```json
+{
+  "playerName": "Steve",
+  "uuid": "...",
+  "gamemode": 1
+}
+```
+
+### `OnLatencyUpdate`
+
+Sent when a player's latency changes.
+
+**Payload:**
+```json
+{
+  "playerName": "Steve",
+  "uuid": "...",
+  "latency": 42
+}
+```
+
+### `OnHeldItemChange`
+
+Sent when the held item slot changes.
+
+**Payload:**
+```json
+{
+  "slot": 0
+}
+```
+
+### `OnExplosion`
+
+Sent when an explosion occurs.
+
+**Payload:**
+```json
+{
+  "location": { "x": 10, "y": 64, "z": -20 },
+  "strength": 4.0,
+  "recordcount": 12
+}
+```
+
+### `OnTitle`
+
+Sent when a title, subtitle, or action bar message is displayed.
+
+**Payload:**
+```json
+{
+  "action": 0,
+  "titleText": "Welcome",
+  "subtitleText": "",
+  "actionBarText": "",
+  "fadeIn": 10,
+  "stay": 70,
+  "fadeOut": 20,
+  "json": "..."
+}
+```
+
+## Server Events
+
+### `OnServerTpsUpdate`
+
+Sent when the server TPS updates.
+
+**Payload:**
+```json
+{
+  "tps": 20.0
+}
+```
+
+### `OnTimeUpdate`
+
+Sent when the world time updates.
+
+**Payload:**
+```json
+{
+  "worldAge": 1000000,
+  "timeOfDay": 6000
+}
+```
+
+### `OnInternalCommand`
+
+Sent when an MCC internal command is executed.
+
+**Payload:**
+```json
+{
+  "commandName": "move",
+  "commandParams": "north",
+  "result": {
+    "status": "Done",
+    "result": ""
+  }
+}
+```
+
+## Inventory Events
+
+### `OnInventoryUpdate`
+
+Sent when an inventory's contents change.
+
+**Payload:**
+```json
+{
+  "inventoryId": 0
+}
+```
+
+### `OnInventoryOpen`
+
+Sent when an inventory window opens.
+
+**Payload:**
+```json
+{
+  "inventoryId": 1
+}
+```
+
+### `OnInventoryClose`
+
+Sent when an inventory window closes.
+
+**Payload:**
+```json
+{
+  "inventoryId": 1
+}
+```
+
+## Scoreboard Events
+
+### `OnScoreboardObjective`
+
+Sent when a scoreboard objective updates.
+
+**Payload:**
+```json
+{
+  "objectiveName": "health",
+  "mode": 0,
+  "objectiveValue": "Health",
+  "type": 0,
+  "json": "...",
+  "numberFormat": 0
+}
+```
+
+### `OnUpdateScore`
+
+Sent when a scoreboard score updates.
+
+**Payload:**
+```json
+{
+  "entityName": "Steve",
+  "action": 0,
+  "objectiveName": "health",
+  "objectiveDisplayName": "Health",
+  "value": 20,
+  "numberFormat": 0
+}
+```
+
+## Map and Trade Events
+
+### `OnMapData`
+
+Sent when map data updates.
+
+**Payload:**
+```json
+{
+  "mapId": 0,
+  "scale": 1,
+  "trackingPosition": true,
+  "locked": false,
+  "icons": [],
+  "columnsUpdated": 128,
+  "rowsUpdated": 128,
+  "mapColumnX": 0,
+  "mapRowZ": 0,
+  "colors": "base64-encoded-string"
+}
+```
+
+Note: `colors` is base64-encoded when present, `null` otherwise.
+
+### `OnTradeList`
+
+Sent when a villager trade list is received.
+
+**Payload:**
+```json
+{
+  "windowId": 1,
+  "trades": [...],
+  "villagerInfo": { ... }
+}
+```
+
+## Network Events
+
+### `OnNetworkPacket`
+
+Sent for every network packet (when subscribed).
+
+**Payload:**
+```json
+{
+  "packetID": 42,
+  "data": "base64-encoded-packet-data",
+  "isLogin": false,
+  "isInbound": true
+}
+```
+
+Note: `data` is base64-encoded. This event generates heavy traffic and is mainly useful for debugging.
diff --git a/docs/guide/websocket/README.md b/docs/guide/websocket/README.md
new file mode 100644
index 00000000..45c45f1b
--- /dev/null
+++ 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.