定义

类型定义

全部发向网络的数据都遵守大端序，这意味着字节将按照高位到地位的顺序发送。大部分现在的计算机都是使用的小端序，所以有可能需要在发送信息前交换字节顺序。

除了字符串类型和元数据以外的类型，将会被使用一个自定义的方法解码，这些数据类型将会使用Java的DataInputStream和DataOutputStream

坐标

被分成三部分的64位长整形

x: 26位最高有效位

z: 26位最低有效位

y: 其中的12位

按照以下方式编码

((x & 0x3FFFFFF) << 38) | ((y & 0xFFF) << 26) | (z & 0x3FFFFFF)

可以按照以下方式解码

long val; // val是一个坐标
x = val >> 38;
y = (val >> 26) & 0xFFF
z = val << 38 >> 38

定点小数

一些数据是以定点小数存储的, 前面几位数表示整数部分 (小数点左边的数字) 剩下的部分表示小数部分（小数点右边的）。相比之下浮点数（浮点和双精度）保存自身的数字（尾数）在一个区块中，小数点的位置 (幂)则存在它旁边。

基本上，定点小数比浮点数有更小的范围，它分数展示对更高的值有利。这使得他们很完美的全局用坐标表示minecraft实体的位置，在一个单独的方块（或meter）中，准确存储其整数部分比定位它们更重要。

坐标一般以一个32位整数显示，前面五位是分数部分，剩下存储的是整数部分。

Java缺乏对分数整数的支持，但你可以以整数形式显示它们。若要将双精浮点数转为整数形式，可以用以下公式：

 abs_int = (int)double * 32;

也可以通过以下公式算回来：

 double = (double)abs_int / 32;

协议版本

请查看协议版本号来获取旧版本的信息。

其他定义

数据包格式

未压缩数据包

Minecraft1.7的数据包,以及未启用压缩的Minecraft1.8服务器的数据包采用这种格式:

压缩的数据包

启用了压缩的Minecraft1.8数据包格式如下:

启用压缩时,压缩数据在解压完毕后长度必须大于或等于预先约定的压缩阀值,否则服务器/客户端会断开连接.

可以通过将阀值设为负数如-1来关闭压缩.

握手

服务端

握手

Ping和登陆都是先以一次握手开始,唯一的区别在于两者的”Next state”字段.

游戏中

客户端

保持在线

服务端将会不断发送包含了一个随机数字标识符的保持在线，客户端必须以相同的数据包回复。如果客户端超过30s没有回复，服务端将会踢出玩家。反之，如果服务端超过20s没有发送任何保持在线，那么客户端将会断开连接并产生一个“Timed out”（超时）异常。

加入游戏

更多关于“登陆游戏”的信息请参照“协议加密”。

非法的维度(Dimension)将使客户端崩溃！

聊天消息

区分聊天消息和系统消息对于尊重（实现）使用者的聊天可见设置是十分重要的，2号位置可以同时接受Json格式或是老的格式。

非法的Json数据将使客户端崩溃！

时间更新

时间是基于tick(刻)的，1s = 20 ticks，游戏中一天共24000刻，大约相当于现实中的20分钟。

时间是通过总tick数对24000去模得到的，0是日出。6000是正午，1200是日落，1800是午夜。

服务器默认每秒将tick数增加20

实体装备

出生点

服务器在客户端登陆后发送的指定玩家出生点（包括出生位置和指南针指向），它也可以在任何时候被发送，不过那只会影响指南针的指向。

更新生命值

服务器发送给玩家以设置或更新他们的生命值

饱食度是作为食品值的过饱和度，食品值在饱食度大于0时不会降低，登陆的玩家会自动获得5.0的饱食度，进食将同时增加饱食度和食品值。

重生

要更改玩家的维度(dimension=[主世界/下界/末地])，需要发送一个包含了合适的维度的重生数据包，紧跟着新维度的区块数据，最后是一个“坐标视点“包，你不需要卸载区块，客户端会自动处理这些问题。

非法的维度(Dimension)客户端崩溃

避免更改玩家的维度到他们原来所在的维度，将会出现奇怪的错误：比如这些玩家将无法攻击其他的玩家（在死亡重生后恢复）

玩家坐标和视点

更新玩家在服务器上的坐标。如果服务器上次已知的玩家坐标和最新发送的数据包的数据的坐标位置相差超过100单位的话，将导致玩家因“移动速度太快 :( (使用作弊器?)”而提出服务器。一般来说如果定点小数的X轴或Z轴的值大于3.2E7D将导致客户端被踢出并显示“无效的坐标”。

偏航（yaw）以角度计算，而且会遵循经典三角规则。偏航的圆单位是在XZ平面上以(0,1)为原点绕逆时针旋转，90度为(-1,0)，180度时为(0,-1)，270度时为(1,0)。

另外，偏航的数值不一定要在0到360之间；任意数字都是有效的，包括负数和大于360的数字。 仰角（pitch）是以角度计算，0代表直视前方，-90表示看正上方，而90表示看正下方。 玩家的偏航（以角度计），站在点(x0,y0)并看点(x,z)可以通过以下方式计算： 　　

 l = x-x0
 w = z-z0
 c = sqrt( l*l + w*w )
 alpha1 = -arcsin(l/c)/PI*180
 alpha2 =  arccos(w/c)/PI*180
 if alpha2 > 90 then
   yaw = 180 - alpha1
 else
   yaw = alpha1

你可以从以下方式通过所给的仰角/偏航而得到向量值：

 x = -cos(pitch) * sin(yaw)
 y = -sin(pitch)
 z =  cos(pitch) * cos(yaw)

关于标记字段：

 <Dinnerbone> It's a bitfield, X/Y/Z/Y_ROT/X_ROT. If X is set, the x value is relative and not absolute.

更换手持物品

发送数据包来改变玩家所选择的物品槽

床的使用

这个数据包将告诉玩家上床了。 有匹配的实体ID的客户端将会进入床模式。 这个数据包将发送给所有附近的玩家（包括已经在床上的玩家）

动作

发送任何一个实体都将改变动作。

动作ID可以为以下值：

生成玩家

这个包会在玩家到达可见区域发送，不是在玩家加入时发送。 服务器可以，然而，安全的不在可见范围内生成玩家实体。 客户端将会正确控制它。 当服务器的online-mode（正版模式），UUID必须有效而且要有有效的皮肤，在离线模式下需要UUID v3。

  <+Grum> i will never confirm this as a feature you know that :)

在这个示例UUID,xxxxxxxx-xxxx-Yxxx-xxxx-xxxxxxxxxxxx中，UUID版本是通过Y来指定的。所以对于UUID v3来说，Y的值一直都为3；对UUID v2来说，Y的值一直为2。

如果没有元数据发送客户端将崩溃

捡拾物品

服务器将在玩家捡起一个落在地上的物品时发出这个包。 -这个包的意义是向你展示这个东西飞向你。它不会摧毁客户端实体占用的的内存。 而且它不会加到你的背包中。服务器只会在每次客户端发送的玩家位置坐标[以及玩家的位置和所看的方向]发生改变后检查物品是否捡起。

生成对象

当服务端生成一个实体/交通工具时发送。

生成生物

当服务端生成一个生物实体的时候发送。

生成画

这个包含有坐标，名称，以及画的类型。 计算一个画框的中心可以这样：指定一个(宽x高)的格子，以(0,0)点作为左上角，中心则为(max(0, 宽 / 2 - 1), 高 / 2)。例如：2x1 (1, 0) 4x4 (1, 2)

生成经验球

生成一个或多个经验球。

实体速率

速度是以1/8000方块每刻（tick,1tick=50ms）；例如，-1343将会移动(-1343 / 8000) = −0.167875每刻（或-3,3575方块每秒）

破坏实体

服务端在一列实体被客户端破坏时发送。

实体

大多数与实体相关的数据包是这个包的一个小类别。当从服务器发送到客户端时，它将初始化实体。 对玩家实体而言，这个包或其他任何移动/改变视点包都是每一刻(tick)会发送的。 所以这个包存在的基本意义是服务器收到实体的包后才会移动/改变视点。

实体相对运动

服务器将会在实体移动距离小于4个方块时发送；如果一个实体移动距离大于4个方块，服务器将会发送实体传送而不是实体相对移动。 这个数据包允许任意方向不超过四个方向的移动，因为字节的范围是从-128到127。

实体视点

这个数据包服务器在实体转向时发送。例如：偏航(yaw)字段值为64意为转90度。

实体相对移动并且视点改变

这个数据包服务器在实体旋转且移动的时候发送。由于字节的范围限制在-128到127， 偏移量为定点小数，这个数据包允许任意方向最多四个方块距离的移动 (-128/32 == -4)。

实体传送

这个数据包服务器在实体移动距离超过四个方块时发送。

实体头部移动

改变实体面朝方向。

实体状态

依附实体

这个数据包在玩家衣服于一个实体时发送。（例如矿车）

实体元数据

实体药水效果

移除实体药水效果

设置经验

服务器在客户端应该更改经验等级的时候发送。

实体设置

已知键值：

区块数据

区块不会由客户端自动卸载。如需卸载区块，发送含有 ground-up continuous=true 并且没有 16^3 区块的数据包（如primary bit mask=0）。服务器不会发送下界地图区块的光照信息，这使得客户端知道玩家正处于下界。你也可以通过主位掩码和发送的未压缩的字节数的数量来推断这些信息。 请参阅：SMP地图格式

在1.8版本中的改变：

• 移除了数据值部分
• 移除了扩展ID部分
• 现在每个方块的id选择变成了一个无符号短整数（从小到大）
• 方块id现在相当于 (id << 4) | data

多个方块更新

记录值 位掩码| 宽度| 意义 ———|———|———- 00 FF |8 bits |Y坐标 0F 00 |4 bits |Z坐标，与区块有关 F0 00 |4 bits |X坐标，与区块有关 ? |VarInt |方块ID

方块更新

方块表现

这个数据包将会用于以下情况：

• 箱子的大开恶化关闭
• 活塞的推拉
• 音符盒播放音乐
• 信标的更新

请参阅：方块表现

方块破坏动画

0-9将显示方块的破坏程度，其他数字意为这个坐标上没有动画。. 你也可以对空气方块设置动画！破坏动画仍然可见！ 如果你想同时显示多个破坏动画的话，你需要给它们每个独立的实体ID。 当然如果你设置坐标为水之类的方块的话。它将不会显示真实的破坏动画而是其他一些很有意思的东西。（比如水方块将失去它的透明度）

地图区块传送

请参阅：SMP地图格式

1.8版的改变在：区块数据

降低数据包的字节数用于将区块一起发送以获得更好的压缩效果。

Meta

爆炸

当爆炸发生的时候发送（爬行者，TNT，恶魂的火球） 每个方块的记录都将被设置为空气。每个轴上的坐标信息将会以 int(X) + record.x 来记录

效果

在客户端产生声音或者药水效果的时候发出。

默认，minecraft客户端通过距离来调整声音效果的音量。最终由布尔值来禁用它后，声音将会由你当前方向前两个方块发出。现在这个只能用于影响1013(mob.wither.spawn)，而且会被客户端的其他任意值忽略。

各种效果

音效

用来播放客户端中的音效

所有已知的音效名可以在这里查到。

资源包中可能会加入自定义声音。

颗粒

显示已命名的颗粒

颗粒ID表

修改游戏状态

这将在床不可作为出生点或下雨状态改变的时候使用。

这个键值有连接到原因代码的字段 0, 1, 2, and 3 但是代码1，2是无效的.

生成全局实体

通过这个包，服务端可以通知客户端玩家半径512范围内有雷。坐标会指定雷击中的具体坐标。

打开窗口

这个包会在打开背包的时候发送给客户端，比如打开箱子、工作台或熔炉。这个信息在任何时候都发送使客户端打开玩家自己的背包的包。

栏位数据设置

服务端在一个栏位的东西被增加/移除的时候发送。

窗口物品

服务端在窗口中的一个栏位的物品被增加/移除的时候发送。这包括主背包，携带装备以及合成栏位。

更新牌子

这个信息服务端在牌子被覆盖或创建的时候发送给客户端。这信息不会再牌子被损坏或者卸载的时候发送。

地图

更新方块实体

从本质上来说一个方块的更新是一个方块实体的更新。

行为

• 1：设置刷怪笼的刷怪概率
• 2：设置命令方块文本（命令和最后执行的状态）
• 3：设置信标的等级，第一效果和第二效果
• 4：设置生物的头的方向和皮肤
• 5：设置花盆上的花类型
• 6：设置气质的基本颜色和样式

打开木牌编辑窗

在放置牌子的时候发送。

统计信息

玩家列表

notchian服务器在用户列表更新的时候发送（客户端的键列表）

玩家能力

后面的两个浮点数是用来分别表示玩家走路/飞行速度的， 第一个字节用来表示四个布尔值。

这些标记有玩家是否可以受到伤害 (god mode, 8, bit 3), 玩家是否可以飞行 (4, bit 2), 玩家是否在飞 (2, bit 1),以及玩家是否处于创造模式 (1, bit 0).

如需获得这些布尔值的信息， simply AND (&) the byte with 1,2,4 and 8 respectively, to get the 0 or 1 bitwise value. To set them OR (|) them with their repspective masks.

Tab补全

服务端会根据最后发送的单词来回应给客户端一个自动完成列表。在平常聊天时，这个列表是玩家的用户名。同时它也支持命令和参数。

计分板容器

服务端在新建或删除一个计分板的时候发送给客户端。

更新积分

当计分板内容更新的时候发送给客户端。

显示计分板

在客户端需要显示计分板的时候发给客户端。

队伍

创建和更新队伍。

插件信息

Mod和插件可以用它来发送它们自己的数据。Minecraft自身使用一系列plugin channels。这些内部频道都前置于MC|. 更多信息可见此：http://dinnerbone.com/blog/2012/01/13/minecraft-plugin-channels-messaging/

断开连接

服务端在断开客户端的连接时发送。服务端假设发送者在收到这个包后已经关闭连接。

服务器难度

在客户端的设置菜单中改变游戏难度。

格斗事件

相机

世界边框

标题

设置压缩

玩家列表首尾

发送资源包

更新实体NBT

服务端

保持在线

服务器会频繁向客户端发送保持在线数据包。每一个包都包含着一个随机的ID。客户端必须将数据包原封不动的发送回来。

聊天信息

默认的服务器会检查消息是否以‘/’开头。若不是，则将发送者的名字添加到消息前并将它发送给所有客户端端（包括发送者自己）。如果是以‘/’开头，服务器将认为它是一个指令并尝试处理它。如果一条消息长度超过100个字符将导致服务器将客户端踢出。这个改动起初是通过允许客户端不切分超过119个字符的消息（以前的限制），但在服务端上并未做改变。因此，原版服务器端保留了在119个字符的位置切分字符串的代码，不过这并不是协议的限制而且这个限制可以被忽略。
更多信息请参阅聊天。

使用实体

客户端会在玩家攻击或右键一个实体(比如玩家,马,矿车…)时发送此数据包给服务器.

原版服务器只会在实体距离玩家不超过4单位长度,并且两者之间视线不受阻碍时,才会处理此数据包.
(译注:在1.8中的规则是:若两者之间没有视线,则距离不能超过3. 若视线通畅,则距离不能超过6.)

注意在创造模式中,鼠标中间选取是在客户端进行,但它也会发送给服务器一个创造模式物品栏动作数据包.

玩家

这个数据包是用来表示玩家是在地上(包括游泳),还是在空中(包括跳起和下落).

当从一定高度落下时,跌落伤害会在此项从False变为True时施加在玩家身上. 伤害程度是根据上次此项由True变False时,玩家站立的地点的高度来决定. 注意:并非只有此数据包会引起跌落伤害计算,其他的几种跟移动相关的数据包也能引发跌落伤害.

玩家位置

更新服务器中玩家的XYZ位置. 如果头部Y减去脚底Y小于0.1或大于1.65,服务器会以“Illegal Stance”为理由踢出玩家. 如果新位置到旧位置(以服务器数据为准)的距离超过100个单位长度的话,玩家会被以”You moved too quickly :( (Hacking?)”为理由踢出. 此外,如果X或Z的定点数(即浮点数的尾数部分)大于3.2E7D的话,服务器也会以”Illegal position”为理由踢出玩家.

玩家视点

更新玩家正在观察的方向.

Yaw(偏航,或叫偏角)代表物体围绕三维坐标中的Y轴旋转的角度(即左转右转),使用角度制,并且并不遵从传统的三角学规律. Yaw在XZ平面投影上的单位圆起始于(0,1),即0度时指向Z轴负方向. 绕Y轴逆时针旋转,即(-1,0)为90度,(0,-1)为180度,(1,0)为270度. 此外,Yaw不必被限制在0到360度,任何数,包括负数和大于360度的数,都是允许的.

Pitch(俯仰,或叫俯角)代表物体围绕三维坐标中的X轴旋转的角度(即上仰下伏),使用角度制,0代表向正前方看,-90代表朝正上方仰视裙底风光,90代表正在低头文明看腿.

对于一个站在点(x0,z0),观察点(x,z)的玩家的Yaw可以按如下伪代码的方法计算:

 l = x-x0;
 w = z-z0;
 c = sqrt( l*l + w*w );
 alpha1 = -arcsin(l/c)/PI*180
 alpha2 =  arccos(w/c)/PI*180
 if alpha2 > 90 then
   yaw = 180 - alpha1
 else
   yaw = alpha1

一组Yaw和Pitch可以被转化为单位向量:

 x = -cos(pitch) * sin(yaw)
 y = -sin(pitch)
 z =  cos(pitch) * cos(yaw)

玩家位置与视点

同时结合了玩家位置和观察的数据包.

玩家挖掘

当玩家试图采集一个砖块时发送. 原版服务器只接受距离玩家6个单位距离以内的挖掘.

目前Status有如下6种:

原版客户端会在开始敲一个砖块时发送0(开始挖掘),敲碎后发送2(完成挖掘). 如果挖掘中止,服务器会发送1(取消挖掘).

状态码4(丢下物品)是一个特例. 在游戏中,当你使用丢下物品指令(快捷键’q’),一个状态为4的挖掘数据包将发送向服务器,它的其余字段值均为0. 状态码3也类似,只不过丢下的是一整个物品栈.

状态码5(射箭/完成进食)也是个特例. X,Y,Z字段值均为0,face字段值为255.

Face代表敲击的砖块面,有如下6种值:

在1.7.3中,如果玩家使用左键开门的话,服务器会收到一个0xE打开窗户和0x7玩家挖掘(状态值为”开始挖掘”).

玩家放置砖块

在普通操作中(比如放置砖块),这个数据包只发送一次,字段值也没有特殊变化.

但在特殊情况下,这个包的X,Y,Z值为-1,Direction为255,Cursor position都为0.0f. (如果你把Y当成无符号数的话,那它就是255.)这种包用来指明需要更新玩家手上的物品的状态,比如吃食物,拉弓,使用水桶等.

在原版的Beta客户端中,砖块或物品ID等于客户端中玩家拿着的物品,并且客户端会在每次玩家对着砖块表面按右键时都发送一次这个数据包,因此对于ID的安全性没有保证. 然而,原版的服务器端似乎会忽略客户端发来的ID,只采用服务器的数据. 在1.2.5和1.3.2中,客户端在一次回话中会发送真实物品ID和一个字段值为-1的数据包. (译注:在1.7.2中,服务器确实会在大多数情况下忽略客户端发来的ID,唯一一种用到客户端发来的物品ID的情况是在检查物品是否耗尽的时候. 至于那个字段值为-1的情况,还没有被观测到…)

另外,在使用水桶时,原版客户端可能会发送两个数据包:一个正常的放置砖块数据包,然后是一个特殊情况的放置砖块数据包. 它们会在你使用水桶的时候依次发送. 第一个不会起任何作用,真正执行舀水动作的是第二个数据包,取水的位置是在服务器端根据玩家的位置和朝向来测算的.

持有物品改变

当玩家所持物品栏位发生改变时发送

动画

实体表现

在蹲着，离开床或者跑的时候发送。客户端用0x28来发送动作。客户端将发送自己的动作ID = 3 when “Leave Bed”已点击。

动作ID可以为下列值：

驾驶交通工具

关闭窗口

这个包会在客户端关闭一个窗口的时候发送。

注意，notchian客户端即使没有打开背包的信息时仍然发送一个关闭0号窗口的信息来关闭背包。

点击窗口

这个包会在玩家点击窗口中的栏位时发送

请参阅背包窗口来获取更多关于栏位索引的信息 当右键点击一组物品时，一半将拿出另一半留在栏位中。如果这个栏位的物品数量为奇数，稍微少的那一部分将留在栏位中。

Action number实际上是一个计数器，从1开始计数，这个数字被服务端用来当作一个事物ID来回发事物包 客户端是通过”模式“和”按键“这两个字段来区分点击事件。

从1.5版开始，”触屏模式“开始在背包窗口试用。它可以完成拿出一组物品（多于1），然后按住鼠标按键（左/右/中键）并且拖拽到空栏位（或和使用右键一样的方式）。在这情况下客户端会在松开鼠标后发出以下数据包（省略掉第一次拿出的包，它和平常拿出一样）

1. 数据包模式 5, 栏位 -999 , 按键 (0 for left | 4 for right);
2. 每个经过的栏位的数据包, 模式仍然为5, 按键 (1 | 5);
3. 数据包模式 5, 栏位 -999, 按键 (2 | 6);

如果其他任何除了”progress”painting数据包发送一旦导致顺序混乱(例如, 一个开始, 几个栏位, 然后另一个开始; 或者左键点中间) the painting 状态将会被重置.

确认事物

创造模式背包事件

当处于创造模式的玩家在普通背包窗口（举例，不是工作台）的时候，服务端将会发送以下包：

• 是否有物品掉落到快速物品栏里
• 是否有物品从快速物品栏中捡起（物品ID为-1）

附魔物品

修改木牌

这消息客户端将在玩家点击木牌窗口内的”完成“按钮后发送。

玩家能力

后面的两个浮点数是用来分别表示玩家走路/飞行速度的， 第一个字节用来表示四个布尔值。

这些标记有玩家是否可以受到伤害 (god mode, 8, bit 3), 玩家是否可以飞行 (4, bit 2), 玩家是否在飞 (2, bit 1),以及玩家是否处于创造模式 (1, bit 0).

如需计算这些布尔值, simply AND (&) the byte with 1,2,4 and 8 respectively, to get the 0 or 1 bitwise value. To set them OR (|) them with their repspective masks. 原版服务端会在玩家开始/停止飞行并且第二个参数也跟着改变。所有其他参数会被原版服务端无视。

Tab补全

当用户在输入文本时按下[tab]键时发送。有效负载包括光标后所有的文本。

客户端设置

当游戏连接或者更改游戏设置时发送。

聊天标记有许多值标记为一个字节。 开启聊天: 字节0-1.00：开启，01：仅命令，10：隐藏。 皮肤显示也同样将许多值标记为一个字节。 Bit 0: 披风开启 Bit 1: 衣物开启 Bit 2: 左袖开启 Bit 3: 右袖开启 Bit 4: 左裤腿开启 Bit 5: 右裤腿开启 Bit 6: 帽子开启 最显著的字节(bit 7)未被使用。

客户端状态

在客户端已经完成连接以及死亡准备复活时发送。

动作ID值：

插件信息

Mod和插件可以用它来发送它们自己的数据。Minecraft自身使用一系列plugin channels。这些内部频道都前置于MC|.

更多信息可见此：http://dinnerbone.com/blog/2012/01/13/minecraft-plugin-channels-messaging/

请注意数据长度是由数据包长度的值得，所以没必要发送长度件。

观察者模式

资源包状态

状态

客户端向服务器进行ping的流程如下:

    (C:客户端  S:服务器)
    C->S : 握手,"Next state"值为1
    C->S : 请求
    S->C : 响应
    C->S : Ping
    S->C : Ping

状态

客户端

响应

服务端

请求

Ping

登陆

登陆流程如下:

    (C:客户端  S:服务器)
    C->S : 握手,"Next state"值为2
    C->S : 登录开始
    S->C : 请求加密
        (客户端认证)
    C->S : 响应加密
        (服务器认证, 双方开始启用数据包加密)
    S->C : 登陆成功

对于不启用认证的服务器,或客户端连接来自本地的话,服务器会放弃使用数据包加密,登录流程也会跳过请求和响应加密这两个步骤.

(不启用认证的服务器有两种:在游戏内开的局域网服务器;online-mode为false的独立服务器.)

关于协议加密的详细信息可以见此.

登录

客户端

断开连接

请求加密

关于协议加密的详细信息可以见此.

登陆成功

启用压缩

数据包压缩是Minecraft1.8开始引入的东西.

服务端

登陆开始

响应加密

关于协议加密的详细信息可以见此.