mirror of
https://github.com/MCCTeam/Minecraft-Console-Client
synced 2026-08-15 13:04:36 +00:00
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
This commit is contained in:
copilot-swe-agent[bot]
parent
c8c9f9ada5
commit
6d6d1105eb
4 changed files with 1198 additions and 0 deletions
|
|
@ -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"
|
||||
],
|
||||
|
|
|
|||
527
docs/guide/websocket/Commands.md
Normal file
527
docs/guide/websocket/Commands.md
Normal file
|
|
@ -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, ... }`.
|
||||
544
docs/guide/websocket/Events.md
Normal file
544
docs/guide/websocket/Events.md
Normal file
|
|
@ -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.
|
||||
118
docs/guide/websocket/README.md
Normal file
118
docs/guide/websocket/README.md
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue