教程/WebSocket

本页面是指基岩版/connect命令连接的WebSocket（该服务器不是多人游戏所使用的服务器，以下简称服务器）。 本教程展示的是客户端与服务端的数据包，不涉及WebSocket服务端的开发，但你可以参考底部的链接来进行服务端的开发。

数据包

Websocket服务器需要向mcbe发送数据包来进行交互。

Websocket服务器可以向游戏发送json格式的数据包，目前已知的有三种：

• 订阅请求
• 取消订阅请求
• 命令请求

这里有几个示例数据包。

subscribe（订阅请求）

订阅事件就是服务器向游戏说明自己要监听哪些事件，当游戏发生该事件后游戏就会向服务器发送该事件的相关信息，下面是一个订阅事件数据报的例子。

注意:目前有一部分事件在新版本当中是无效的

{
	"body": {
		"eventName": "PlayerMessage"
	},
	"header": {
		"requestId": "00000000-0000-0000-0000-000000000000",
		"messagePurpose": "subscribe",
		"version": 1,
		"messageType": "commandRequest"
	}
}

这将对PlayerMessage事件进行监听，玩家在聊天栏发的消息以及其他相关信息将被通过数据包发回。看一看这个包，你会发现requestId的value是一些0，这不是固定的，你完全可以对它进行更改。

unsubscribe（取消订阅请求）

Unsubscribe包是用来在监听事件之后取消监听。

{
	"body": {
		"eventName": "PlayerMessage"
	},
	"header": {
		"requestId": "00000000-0000-0000-0000-000000000000",
		"messagePurpose": "unsubscribe",
		"version": 1,
		"messageType": "commandRequest"
	}
}

这是一个对PlayerMessage事件进行unsubscribe的数据包，取消订阅后玩家在聊天栏发送的消息将不再会被服务器监听。

CommandRequest（命令请求）

该数据包会在游戏内执行指定的命令。

{
	"body": {
		"origin": {
			"type": "player"
		},
		"commandLine": "say Hello",
		"version": 1
	},
	"header": {
		"requestId": "00000000-0000-0000-0000-000000000000",
		"messagePurpose": "commandRequest",
		"version": 1,
		"messageType": "commandRequest"
	}
}

这将在客户端执行commandLine项（say Hello）的命令，执行结果会被发回。

• commandRequest能执行一些游戏内无法执行的命令，例如: /agent create（创建agent）

返回数据包

返回的数据包指的是游戏向服务器发送的数据包，这些数据包有两种类型:

• 对服务器订阅的事件的响应
• 对服务器发送的命令事件的反馈

event包（订阅事件响应）

标准Event包示例

{
	"body": {
        "eventName": "",
        "measurements":null,
        "properties": {
        }
    },
	"header": {
        "messagePurpose": "event",
        "requestId": "00000000-0000-0000-0000-000000000000",
        "version":1
    }
}

• 不同的事件在"body"和"properties"字段中填入的数据有些许不同（不同的事件会有不同的包含关键信息的字段），上方是一个标准数据包的例子

PlayerMessage event示例

示例：

{
  "body": {
    "eventName": "PlayerMessage",
    "measurements": {
      "Count": 1,
      "RecordCnt": 1,
      "SeqMax": 1355,
      "SeqMin": 1355
    },
    "properties": {
      "AccountType": 1,
      "ActiveSessionID": "a9f8087b-2e3d-495c-b3c3-aef515b7e19a",
      "AppSessionID": "43408684-6cb0-4896-b89d-66a2a1e48a73",
      "Biome": 1,
      "Build": "1.13.1",
      "BuildPlat": 7,
      "Cheevos": false,
      "ClientId": "0ceeb3a3-f96c-34b0-895f-b0d4ca7b129a",
      "CurrentInput": 1,
      "DeviceSessionId": "43408684-6cb0-4896-b89d-66a2a1e48a73",
      "Dim": 0,
      "GlobalMultiplayerCorrelationId": "0694aabd-ddde-466d-ae99-1f88faf1580a",
      "Message": "a",
      "MessageType": "chat",
      "Mode": 1,
      "MultiplayerCorrelationId": "ab4e37fe-2836-18a0-6d21-a85f781f8e70",
      "NetworkType": 0,
      "Plat": "Win 10.0.18362.1",
      "PlayerGameMode": 1,
      "SchemaCommitHash": "19b6ec0744c3c83a00ecbd840f48cb080c7bc64d",
      "Sender": "hhhxiao",
      "ServerId": "raknet:11376205654463177128",
      "Treatments": "mc-perf-plat-12-20:mc-perf-plat-1-20:mc-perf-plat-2-20:mc-perf-plat-4-20:mc-perf-plat-7-20:mc-perf-plat-13-20:mc-perf-plat-11-1:mc-rp-frozenbuttonandpanel:mc-rp-playfab",
      "UserId": "2535451099196973",
      "WorldFeature": 0,
      "WorldSessionId": "f7d8ca20-4be0-4d01-aa83-3c2c64dabc88",
      "editionType": "win10",
      "isTrial": 0,
      "locale": "zh_CN",
      "vrMode": false
    }
  },
  "header": {
    "messagePurpose": "event",
    "requestId": "00000000-0000-0000-0000-000000000000",
    "version": 1
  }
}

这是一个PlayerMessage返回包示例。

• body.properties.Message是用户发出的消息
• body.properties.MessageType是消息类型（say、me、chat等）
• body.properties.Sender是发送者名称
• body.properties.locale是设备使用的语言
• body.properties.UserId 与用户Xbox Live相关，登录同一Xbox Live时总为一个值，未登录时为空或未定义。

CommandResponse （CommandRequest返回）

一般格式:

{
  "body":{
    "statusCode": 0,
    "statusMessage": ""
  },
  "header": {
    "messagePurpose":"commandResponse",
    "requestId": "00000000-0000-0000-000000000000"
  }
}

示例：

list命令

{
    "body":{
        "currentPlayerCount":1,
        "maxPlayerCount":5,
        "players":"LNSSPsd",
        "statusCode":0,
        "statusMessage":"There are 1/5 players online:\nLNSSPsd"
    },
    "header":{
        "messagePurpose":"commandResponse",
        "requestId":"00000000-0000-0000-000000000000",
        "version":1
     }
}

• body.currentPlayerCount、body.maxPlayerCount、body.players是/list命令特有的，在执行其他命令时不存在。

say命令

本示例使用了/say oh命令

{
    "body":{
        "message":"oh",
        "statusCode":0
    },
    "header":{
        "messagePurpose":"commandResponse",
        "requestId":"00000000-0001-0000-000000000000",
        "version":1
    }
}

• body.message是/say特有的，而/say命令没有statusMessage项。

tp命令

本示例使用了/tp Steve ~ ~ ~命令

{
  "body": {
    "destination": {
      "x": 73.37560272216797,
      "y": 71.12252044677734,
      "z": 36.96865081787109
    },
    "statusCode": 0,
    "statusMessage": '已将 Steve 传送至 73.38, 71.12, 36.97',
    "victim": [ 'Steve' ]
  },
  "header": {
    "messagePurpose": 'commandResponse',
    "requestId": '00000000-0000-0000-0000-000000000000',
    "version": 1
  }
}

• body.destination、body.victim、header.version 是/tp特有的。

注释

• body.statusCode 是命令完成状态，成功时为0，失败时小于0。
• body.statusMessage 是状态消息，相当于执行命令后聊天里的命令返回，少数命令（如/say命令）无返回显示，故无此项。
• 返回请求的 header.requestId 与发送请求时附带的 header.requestId 相同。

事件表

下面是目前已知的所有可订阅事件，写了触发条件的是确认可用或者已知触发条件的。

事件名称	触发条件
AdditionalContentLoaded	附加包加载
AgentCommand	agent实体执行命令（移动,攻击等等）
AgentCreated	创建agent
ApiInit
AppPaused	游戏暂停
AppResumed	游戏继续
AppSuspended	游戏中止
AwardAchievement	玩家获得游戏成就
BlockBroken	玩家破坏方块
BlockPlaced	玩家放置方块
BoardTextUpdated
BossKilled	杀死boss（命令无效）
CameraUsed	使用相机
CauldronUsed	炼药锅交互
ChunkChanged
ChunkLoaded	区块加载完成
ChunkUnloaded
ConfigurationChanged
ConnectionFailed
CraftingSessionCompleted	关闭工作台界面或者背包界面
EndOfDay	在一天自然结束（命令修改时间将不会触发）
EntitySpawned	通过命令生成实体
FileTransmissionCancelled
FileTransmissionCompleted
FileTransmissionStarted
FirstTimeClientOpen	首次启动游戏
FocusGained
FocusLost
GameSessionComplete
GameSessionStart	进入存档（世界加载的时候）
HardwareInfo
HasNewContent	商城上新
ItemAcquired	捡起掉落物,拿起合成的物品
ItemCrafted	物品从工作台拿出
ItemDestroyed	物品损坏或耗尽
ItemDropped	玩家扔出物品
ItemEnchanted	物品被附魔
ItemSmelted	玩家取出熔炉内物品
ItemUsed	使用物品（吃东西，放置方块，扔鸡蛋，使用弓箭等）
JoinCanceled
JukeboxUsed	CD放入音符盒
LicenseCensus
MascotCreated	智能体创建（失效）
MenuShown
MobInteracted	实体交互
MobKilled	玩家击杀生物
MultiplayerConnectionStateChanged
MultiplayerRoundEnd
MultiplayerRoundStart
NpcPropertiesUpdated
OptionsUpdated
performanceMetrics
PackImportStage
PlayerBounced	玩家被床和黏液块弹起
PlayerDied	玩家死亡
PlayerJoin	玩家进入游戏
PlayerLeave	玩家离开游戏
PlayerMessage	玩家收到一条消息
PlayerTeleported	玩家被传送
PlayerTransform	玩家移动
PlayerTravelled	玩家移动时（和PlayerTransform几乎同时）
PortalBuilt	玩家创建传送门（下界和末地）
PortalUsed	玩家使用传送门
PortfolioExported
PotionBrewed	从酿造台拿出药水的时候
PurchaseAttempt	支付尝试
PurchaseResolved	支付确认
RegionalPopup
RespondedToAcceptContent
ScreenChanged	打开任何UI，点击任何设置页面
ScreenHeartbeat
SignInToEdu	登录教育版
SignInToXboxLive	点击登录Xbox的按钮
SignOutOfXboxLive	注销Xbox
SpecialMobBuilt
StartClient	游戏启动
StartWorld	主菜单进入世界
TextToSpeechToggled	文字转语音选中
UgcDownloadCompleted
UgcDownloadStarted
UploadSkin	玩家更新皮肤
VehicleExited	玩家离开矿车
WorldExported	世界导出
WorldFilesListed	世界列表列出
WorldGenerated	创建一个新世界
WorldLoaded	世界载入
WorldUnloaded

历史

携带版Alpha
0.16.0		build 1			加入了/connect命令，可以连接WebSocket了。
基岩版
1.2					commandRequest包格式发生改变。

参考

• https://github.com/lZiMUl/Mcbbsmis.git
• https://github.com/mcpews/MyAgent.git
• https://github.com/CAIMEOX/FastBuilder.git
• https://github.com/liumingedwin/Minecraft-Mod-Configer.git