mirror of
https://github.com/MCCTeam/Minecraft-Console-Client
synced 2026-08-15 13:04:36 +00:00
cb4eb15784
Co-authored-by: milutinke <441903+milutinke@users.noreply.github.com> Agent-Logs-Url: https://github.com/MCCTeam/Minecraft-Console-Client/sessions/3040312a-cbdf-43fe-918b-133ef19fc30f
124 lines
3.6 KiB
Markdown
124 lines
3.6 KiB
Markdown
# 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).
|
|
1. Open the file and edit the line near the top:
|
|
```csharp
|
|
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.
|
|
1. Optionally enable debug logging:
|
|
```csharp
|
|
MCC.LoadBot(new WebSocketBot("127.0.0.1", 8043, "mypassword", debugMode: true));
|
|
```
|
|
1. 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.
|