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.

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:

   MCC.LoadBot(new WebSocketBot("127.0.0.1", 8043, "CHANGE_THIS_PASSWORD"));
   • Replace 127.0.0.1 with the IP to bind (use + or * for all interfaces).
   • Replace 8043 with your preferred port.
   • Replace CHANGE_THIS_PASSWORD with a strong, unique password.
3. Optionally enable debug logging:

   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:

{
  "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:

{
  "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:

{ "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:

{ "command": "InteractEntity", "requestId": "abc", "parameters": [42, "Interact", "MainHand"] }

or:

{ "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 - full list of available commands
• Events - 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 and any WebSocket client library.