WebSocket Events

Events are JSON messages pushed to all authenticated WebSocket clients. Each event has this structure:

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

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

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

{
  "text": "Formatted text content",
  "json": "{ raw JSON from server }"
}

OnChatPublic

Sent when a public chat message is detected.

Payload:

{
  "sender": "PlayerName",
  "message": "Hello world",
  "rawText": "<PlayerName> Hello world"
}

OnChatPrivate

Sent when a private message is detected.

Payload:

{
  "sender": "PlayerName",
  "message": "Secret message",
  "rawText": "PlayerName whispers to you: Secret message"
}

OnTeleportRequest

Sent when a teleport request is detected.

Payload:

{
  "sender": "PlayerName",
  "rawText": "PlayerName has requested to teleport to you"
}

Connection Events

OnDisconnect

Sent when MCC disconnects from the server.

Payload:

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

{
  "entity": { ... },
  "animation": 0
}

OnEntityHealth

Sent when an entity's health changes.

Payload:

{
  "entity": { ... },
  "health": 20.0
}

OnEntityMetadata

Sent when entity metadata updates.

Payload:

{
  "entity": { ... },
  "metadata": { "0": ..., "1": ... }
}

OnEntityEquipment

Sent when an entity's equipment changes.

Payload:

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

{
  "entity": { ... },
  "effect": "Speed",
  "amplifier": 1,
  "duration": 600,
  "flags": 0
}

OnBlockBreakAnimation

Sent when a block break animation plays.

Payload:

{
  "entity": { ... },
  "location": { "x": 10, "y": 64, "z": -20 },
  "stage": 5
}

Player Events

OnPlayerJoin

Sent when a player joins the server.

Payload:

{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "PlayerName"
}

OnPlayerLeave

Sent when a player leaves the server.

Payload:

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

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

{
  "health": 20.0,
  "food": 20
}

OnSetExperience

Sent when experience updates.

Payload:

{
  "experienceBar": 0.5,
  "level": 10,
  "totalExperience": 200
}

Game Events

OnGamemodeUpdate

Sent when a player's gamemode changes.

Payload:

{
  "playerName": "Steve",
  "uuid": "...",
  "gamemode": 1
}

OnLatencyUpdate

Sent when a player's latency changes.

Payload:

{
  "playerName": "Steve",
  "uuid": "...",
  "latency": 42
}

OnHeldItemChange

Sent when the held item slot changes.

Payload:

{
  "slot": 0
}

OnExplosion

Sent when an explosion occurs.

Payload:

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

{
  "action": 0,
  "titleText": "Welcome",
  "subtitleText": "",
  "actionBarText": "",
  "fadeIn": 10,
  "stay": 70,
  "fadeOut": 20,
  "json": "..."
}

Server Events

OnServerTpsUpdate

Sent when the server TPS updates.

Payload:

{
  "tps": 20.0
}

OnTimeUpdate

Sent when the world time updates.

Payload:

{
  "worldAge": 1000000,
  "timeOfDay": 6000
}

OnInternalCommand

Sent when an MCC internal command is executed.

Payload:

{
  "commandName": "move",
  "commandParams": "north",
  "result": {
    "status": "Done",
    "result": ""
  }
}

Inventory Events

OnInventoryUpdate

Sent when an inventory's contents change.

Payload:

{
  "inventoryId": 0
}

OnInventoryOpen

Sent when an inventory window opens.

Payload:

{
  "inventoryId": 1
}

OnInventoryClose

Sent when an inventory window closes.

Payload:

{
  "inventoryId": 1
}

Scoreboard Events

OnScoreboardObjective

Sent when a scoreboard objective updates.

Payload:

{
  "objectiveName": "health",
  "mode": 0,
  "objectiveValue": "Health",
  "type": 0,
  "json": "...",
  "numberFormat": 0
}

OnUpdateScore

Sent when a scoreboard score updates.

Payload:

{
  "entityName": "Steve",
  "action": 0,
  "objectiveName": "health",
  "objectiveDisplayName": "Health",
  "value": 20,
  "numberFormat": 0
}

Map and Trade Events

OnMapData

Sent when map data updates.

Payload:

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

{
  "windowId": 1,
  "trades": [...],
  "villagerInfo": { ... }
}

Network Events

OnNetworkPacket

Sent for every network packet (when subscribed).

Payload:

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