玩家数据格式

玩家数据格式是游戏内用于存储玩家数据规定的数据格式。

数据格式

玩家数据属于一种实体数据。除普通实体具有的数据外，还包含了很多玩家的特有数据。

玩家数据具有下列的NBT结构：

• 根标签

• • 实体共通标签，见Template:Nbt inherit/entity/source[显示]
  • 生物共通标签，见Template:Nbt inherit/living entity/source[显示]
  • *DataVersion：保存此存档基础数据存储文件的游戏的数据版本。如果此项不存在则游戏认为此项是-1。
  • *abilities：玩家拥有的能力。
    • *
      *flying：玩家是否正在飞行。
    • *flySpeed：玩家的飞行速度。如果此项不存在则游戏认为此项是0.05。
    • *
      *instabuild：玩家是否可以立刻摧毁方块、选取方块时是否允许保存方块实体数据、使用铁砧是否不消耗经验值且不会过于昂贵、是否立刻破坏载具等。
    • *
      *invulnerable：玩家是否能抵抗绝大多数伤害。如果为true，玩家不消耗饥饿值、通过下界传送门的时间被改变、身上的火可以快速熄灭，且只会受到带有#bypasses_invulnerability标签的伤害。
    • *mayBuild：玩家是否可以摧毁、放置和调整方块和盔甲架。如果此项不存在则游戏认为此项是true。
    • *
      *mayfly：玩家是否能飞行，阻止玩家因为飞行而被服务器踢出。
    • *walkSpeed：步行速度。如果flySpeed不存在则游戏认为此项是0.1。
  • current_explosion_impact_pos：玩家被任何爆炸击退时，此数据才存在，表示被爆炸击退时的坐标。当玩家落地、陷入方块、切换为创造模式、使用末影珍珠和紫颂果传送时此值被清除。
    • ：击退时的X坐标。玩家使用重锤猛击时，如果Y坐标高于玩家当前位置，则会被设置为玩家当前的X坐标。
    • ：击退时的Y坐标。玩家使用重锤猛击时，如果此值高于玩家当前位置，则会被设置为玩家当前的Y坐标。
    • ：击退时的Z坐标。玩家使用重锤猛击时，如果Y坐标高于玩家当前位置，则会被设置为玩家当前的Z坐标。
  • equipment^{[新增：JE 1.21.5]}：玩家除主手槽位外的装备槽位的物品。
    • <装备槽位>：指定装备槽位上拥有的物品。
  • *
    *current_impulse_context_reset_grace_time：爆炸击退减少摔落伤害的最长时间，按游戏刻计。玩家被风弹物品风弹所产生的风爆击退或使用重锤时此值被设置为40游戏刻（2秒），被其他爆炸波及、或current_explosion_impact_pos被清除时设置为0。此值达到0时清除current_explosion_impact_pos和ignore_fall_damage_from_current_explosion。
  • Dimension：（命名空间ID）玩家所处维度。
  • ender_pearls：与玩家绑定的末影珍珠数据。如果玩家没有绑定的末影珍珠，则此项不存在。
    • ：一个末影珍珠的信息。与玩家绑定的末影珍珠将在玩家上线时被加载加入世界，并对所在区块添加标签以保持加载，下线时会被强制移除出世界。
      • ender_pearl_dimension：末影珍珠所在的维度。
      • 剩余标签见末影珍珠/ED。
  • *EnderItems：玩家末影箱里的物品。末影箱中一共有27个槽位，超出槽位范围的物品不会被加载。
    • ：末影箱里的一个物品。
      • 物品共通标签，见Template:Nbt inherit/item/source[显示]
  • enteredNetherPosition^{[失效：JE 1.21.5]}：在玩家进入下界时，记录传送前在主世界的位置，用于进度触发器nether_travel中。当玩家传送到非下界维度时此值被删除。
    • x：X坐标。
    • y：Y坐标。
    • z：Z坐标。
  • entered_nether_pos^{[新增：JE 1.21.5]}：在玩家进入下界时，记录传送前在主世界的位置，用于进度触发器nether_travel中。当玩家传送到非下界维度时此值被删除。内部的三个双精度浮点数分别对应X、Y、Z坐标。
    • ：一个坐标。
  • *foodExhaustionLevel：玩家的消耗度。如果foodLevel不存在游戏默认为0。
  • *foodLevel：玩家的饥饿值。如果此项不存在游戏默认为20。
  • *foodSaturationLevel：玩家的饱和度。如果foodLevel不存在游戏默认为5。
  • *foodTickTimer：玩家的食物计刻器。如果foodLevel不存在游戏默认为0。
  • *
    *ignore_fall_damage_from_current_explosion：玩家是否受到爆炸冲击且可以因为冲击减少摔落伤害，当玩家被风弹物品风弹所产生的风爆击退或使用重锤时此值被设置为true，在重置时间后、被其他爆炸波及、或current_explosion_impact_pos被清除时此值被设置为false。此值为true代表摔落伤害会根据current_explosion_impact_pos减少或免除。
  • *
    *Inventory：玩家的物品栏。其中槽位0-8代表快捷键槽，槽位9-35代表物品存放槽，槽位100-103代表靴子、护腿、胸甲和头盔，槽位150（表示为-106）代表副手^{[失效：JE 1.21.5]}。在无效槽位的物品无法被加载。
    • ：物品栏中的一个物品。
  • *LastDeathLocation：玩家上次死亡的地点。
    • *
      *dimension：（命名空间ID）死亡地点的维度。
    • *
      *pos：死亡地点的坐标。内部的三个整数分别代表了位置的XYZ坐标值。
  • *playerGameType：玩家的游戏模式。0为生存模式，1为创造模式，2为冒险模式，3为旁观模式。如果此项不存在则游戏会使用存档中的游戏模式。如果存档强制指定游戏模式则此项无效。
  • previousPlayerGameType：玩家的上一个游戏模式，用于F3 + N在上一个模式和旁观模式中切换。可用枚举值与playerGameType相同。
  • raid_omen_position：玩家触发袭击之兆的位置，当袭击之兆结束时被清除，用于计算袭击发生点。内部3个整数分别代表XYZ坐标。
  • *recipeBook：玩家已解锁的配方。
    • 见配方书 § 数据值。
  • respawn^{[新增：JE 1.21.5]}：玩家的重生数据。仅在玩家设置重生点后存在，在重生时检查重生点无效时被清除。
    • pos：玩家重生点所处的方块位置。
    • angle：（默认为0.0）玩家重生时的角度。
    • dimension：（命名空间ID）玩家重生点所处的维度。此项不存在时游戏默认为minecraft:overworld（主世界）。
    • forced：（默认为false）玩家是否将被强制复活在重生点上，而不是在重生点无法重生时查找临近位置。此值也控制重生点是否永远有效。
  • RootVehicle：玩家骑乘的根实体的数据。根实体即递归查找骑乘实体，直到找到不骑乘实体的实体。根实体的所有乘客（包括递归）中只有一个玩家时此项才存在，其他数量均不存在。
    • *
      *Attach：（UUID）玩家直接骑着的实体。
    • *
      *Entity：玩家骑乘的根实体数据。
      • 见实体数据格式。
  • *
    *Score：玩家在死亡画面中显示的分数。
  • *
    *seenCredits：玩家是否曾通过返回传送门前往主世界，即是否看过鸣谢界面。
  • SelectedItem：（不会被加载也不会被保存，仅能通过实体谓词中的NBT谓词、实体选择器中的nbt选项或/data get访问）玩家当前选中的物品。
    • 物品共通标签，见Template:Nbt inherit/itemnoslot/source[显示]
  • *
    *SelectedItemSlot：玩家当前选中的快捷栏编号。
  • ShoulderEntityLeft：玩家左肩上的实体。永远显示为一只鹦鹉。
    • 见实体数据格式。
  • ShoulderEntityRight：玩家右肩上的实体。永远显示为一只鹦鹉。
    • 见实体数据格式。
  • *
    *SleepTimer：自玩家开始睡觉之后经过的时间。控制渲染效果和猫给予礼物。
  • spawn_extra_particles_on_fall：玩家落地时是否产生大范围的额外粒子。当使用重锤猛击击中在地面上的实体时被设置为true，落地时设置为false。
  • SpawnAngle^{[失效：JE 1.21.5]}：玩家重生时的角度。仅在玩家设置重生点后存在，在重生时检查重生点无效时被清除。
  • SpawnDimension^{[失效：JE 1.21.5]}：（命名空间ID）玩家重生点所处的维度。仅在玩家设置重生点后存在，在重生时检查重生点无效时被清除。
  • SpawnForced^{[失效：JE 1.21.5]}：玩家是否将被强制复活在重生点上，而不是在重生点无法重生时查找临近位置。此值也控制重生点是否永远有效。
  • SpawnX^{[失效：JE 1.21.5]}：玩家的重生点的X坐标。仅在玩家设置重生点后存在，在重生时检查重生点无效时被清除。
  • SpawnY^{[失效：JE 1.21.5]}：玩家的重生点的Y坐标。仅在玩家设置重生点后存在，在重生时检查重生点无效时被清除。
  • SpawnZ^{[失效：JE 1.21.5]}：玩家的重生点的Z坐标。仅在玩家设置重生点后存在，在重生时检查重生点无效时被清除。
  • *warden_spawn_tracker：追踪该玩家在监守者生成机制中的进程。
    • *cooldown_ticks：（值≥0）警告等级能够再次增加前的冷却时间。每游戏刻减少1。警告等级增加后会被重置为200游戏刻（10秒）。当此值不存在时游戏默认为0。
    • *ticks_since_last_warning：（值≥0）距玩家上次被监守者生成机制警告后的时间。每游戏刻增加1。12000游戏刻（10分）后会被重置为0，并将警告等级减少1。当此值不存在时游戏默认为0。
    • *warning_level：（0≤值≤4）警告等级。监守者会在大于等于4级时生成。当此值不存在时游戏默认为0。
  • *
    *XpLevel：玩家的经验等级。
  • *
    *XpP：提升到下一经验等级的进度。
  • *XpSeed：附魔台选取附魔使用的随机数种子。当此值不存在时游戏会随机产生一个新的种子。
  • *
    *XpTotal：玩家所获得的经验值总数。

下图为玩家物品栏槽位编号：

存储格式

在存档中，玩家数据存储在两个位置：

• 对于单人游戏存档，玩家数据保存在level.dat内的Player标签内。
• 在<存档根目录>/playerdata/<玩家UUID>.dat内存储了各个玩家的数据。此文件可能具有副本。

对于单独存储玩家数据的玩家数据存储文件，它使用GZip压缩的NBT文件格式保存，其NBT结构与玩家数据结构一致。

存储行为

对于单人游戏存档，level.dat内的Player标签内的玩家数据优先级高于存档目录内playerdata中的玩家数据的优先级。

与level.dat类似，单独保存的玩家数据也很重要，所以也具有备份文件。当玩家数据被保存时，游戏按照下列步骤创建备份：

1. 先将新的数据写入到<玩家UUID>-<随机字符串>.dat内。
2. 将原先的<玩家UUID>.dat移动到<玩家UUID>.dat_old。
3. 删除<玩家UUID>.dat。
4. 将刚才写入的<玩家UUID>-<随机字符串>.dat移动到<玩家UUID>.dat。
5. 如果有任何一步出错，都将<玩家UUID>.dat_old移动回<玩家UUID>.dat。

加载时如果主文件损坏，那么游戏会尝试使用旧版本自动修复文件：

1. 将原先的<玩家UUID>.dat复制到<玩家UUID>_corrupted_<时间戳>.dat。
2. 加载<玩家UUID>.dat_old。

历史

Java版
1.12			pre1				对玩家加入了enteredNetherPosition，用于进度触发器nether_travel。
1.16			20w12a				对玩家加入了SpawnDimension、SpawnForced、SpawnX、SpawnY和SpawnZ标签，用于控制玩家重生点。
			20w21a				对玩家加入了Dimension标签表示玩家所在的维度。
			pre6				对玩家加入了SpawnAngle标签表示玩家重生时的角度。
1.16.2			20w29a				对玩家加入了previousPlayerGameType标签表示切换之前的游戏模式。
1.19			22w14a				对玩家加入了LastDeathLocation标签。
1.19.3			22w42a				对玩家加入了warden_spawn_tracker标签控制监守者的生成。
1.20.5			24w06a				对玩家加入了ignore_fall_damage_above_y标签控制摔落伤害。
			24w11a				对玩家加入了spawn_extra_particles_on_fall标签指定摔落时是否有额外粒子。
			24w12a				移除了ignore_fall_damage_above_y，使用新的current_explosion_impact_pos和ignore_fall_damage_from_current_explosion代替。
			24w13a				对玩家加入了raid_omen_position标签保存触发袭击之兆的位置。
1.21			pre1				对玩家加入了current_impulse_context_reset_grace_time记录current_explosion_impact_pos的有效时间。
1.21.2			24w37a				对玩家加入了ender_pearls标签记录与玩家绑定的末影珍珠数据。
Java版（即将到来）
1.21.5			25w06a				现在玩家除主手槽位外的装备数据移到equipment标签内。
			25w07a				将enteredNetherPosition重做为entered_nether_pos。
							修改了玩家重生数据的格式。