player.dat format

From Minecraft Wiki
Jump to: navigation, search

Information icon.svg
This feature is exclusive to Java Edition.

<player>.dat files are used by servers to store the state of individual players. The format is also used within level.dat files to store the state of the singleplayer player, which overrides any <player>.dat files with the same name as the singleplayer player. These files are in NBT format.

NBT structure[edit]

  • The root tag. In level.dat files, this tag is called "Player".
    • Tags common to all entities see Template:Nbt inherit/entity/template except the id, CustomName and CustomNameVisible
    • Tags common to all mobs see Template:Nbt inherit/mob/template except HandItems, ArmorItems, HandDropChances, ArmorDropChances, CanPickUpLoot, PersistenceRequired and Leash
    •  DataVersion: Version of the player NBT structure. Is increased with every new snapshot and release.
    •  playerGameType: The game mode of the player. 0 is Survival, 1 is Creative, 2 is Adventure and 3 is Spectator.
    •  previousPlayerGameType: The previous game mode of the player.
    •  Score: The Score displayed upon death.
    •  Dimension: A namespaced ID of the dimension the player is in. Used to store the players last known location along with Pos.
    •  SelectedItemSlot: The selected hotbar slot of the player.
    •  SelectedItem: Data of the item currently being held by the player, excluding the Slot tag.
    •  SpawnDimension: May not exist. The dimension of the player's bed or respawn anchor. These tags are only removed if the player attempts to respawn with no valid bed or respawn anchor to spawn at at these coordinates. They are unaffected by breaking a bed or respawn anchor at these coordinates, and are unaffected by the player's death.
    •  SpawnX: See below.
    •  SpawnY: May not exist. The coordinates of the player's bed or respawn anchor. These tags are only removed if the player attempts to respawn with no valid bed or respawn anchor to spawn at at these coordinates. They are unaffected by breaking a bed or respawn anchor at these coordinates, and are unaffected by the player's death.
    •  SpawnZ: See above.
    •  SpawnForced: 1 or 0 (true/false) - May not exist. True if the player should spawn at the above coordinates even if no bed can be found.
    •  SleepTimer: The number of ticks the player had been in bed. No effect.
    •  foodLevel: The value of the hunger bar; 20 is full. See Hunger.
    •  foodExhaustionLevel: See Hunger.
    •  foodSaturationLevel: See Hunger.
    •  foodTickTimer: See Hunger.
    •  XpLevel: The level shown on the XP bar.
    •  XpP: The progress/percent across the XP bar to the next level.
    •  XpTotal: The total amount of XP the player has collected over time; used for the Score upon death.
    •  XpSeed: The seed used for the next enchantment in enchantment tables.
    •  Inventory: Each compound tag in this list is an item in the player's inventory. (Note: when empty, list type may have unexpected value.)
    •  EnderItems: Each compound tag in this list is an item in the player's 27-slot ender chest inventory. (Note: when empty, list type may have unexpected value.)
      • An item in the inventory, includes the Slot tag - slots are numbered 0 to 26, inclusive.
    •  abilities: The abilities this player has.
      •  walkSpeed: The walking speed, always 0.1.
      •  flySpeed: The flying speed, always 0.05.
      •  mayfly: 1 or 0 (true/false) - true if the player can fly.
      •  flying: 1 or 0 (true/false) - true if the player is currently flying.
      •  invulnerable: 1 or 0 (true/false) - true if the player is immune to all damage and harmful effects except for void damage. (damage caused by the /kill command is void damage)
      •  mayBuild: 1 or 0 (true/false) - true if the player can place and destroy blocks.
      •  instabuild: 1 or 0 (true/false) - true if the player can instantly destroy blocks.
    •  enteredNetherPosition: Optional. The Overworld position from which the player entered the Nether, for use with the minecraft:nether_travel advancement trigger. The tag is set every time the player passes through a portal from the Overworld to the Nether. Passing through a portal back to the Overworld does not remove or update the tag. Entering the Nether without using a portal does not update the tag. If a portal is hacked into the End, using it to enter the Nether removes this tag.
      •  x: The X coordinate.
      •  y: The Y coordinate.
      •  z: The Z coordinate.
    •  RootVehicle: The root entity that the player is riding. Optional.
      •  Attach: The UUID of the entity the player is riding, stored as four ints.
      •  Entity: The NBT data of the root vehicle.
    •  ShoulderEntityLeft: The entity that is on the player's left shoulder. Always displays as a parrot.
    •  ShoulderEntityRight: The entity that is on the player's right shoulder. Always displays as a parrot.
    •  seenCredits: 1 or 0 (true/false) - true if the player has traveled to the Overworld via an End portal.
    •  recipeBook: Contains a JSON object detailing recipes the player has unlocked.

Item structure[edit]

Items are used both in the player's inventory and Ender inventory, and in chest tile entities, dropped item entities, furnace tile entities, brewing stand tile entities, and Villager trading recipes. Sometimes a Slot tag is used to specify the slot the item is in, such as with chests; other times there is no Slot tag, such as with dropped items.

    •  Count: Number of items stacked in this inventory slot. Any item can be stacked, including tools, armor, and vehicles. Range is -128 to 127. Values of 1 are not displayed in-game. Values below 1 are displayed in red.
    •  Slot: The inventory slot the item is in.
    •  id: Item/Block ID. If not specified, Minecraft changes the item to stone when loading the chunk or summoning the item.[verify]
    •  tag: Additional information about the item, discussed more in the subsections of the item structure section. This tag is optional for most items. Unlike other entity or block NBT, this tag is never deserialized and can hold user defined tags that are not used by the game by standard.

General Tags[edit]

Items with durability can be made unbreakable and never lose any durability. Additionally, items can have specifications for Adventure mode to describe which blocks may be broken with them.

  •  tag: Parent tag.
    •  Damage: The damage value for this item. Defaults to 0.
    •  Unbreakable: 1 or 0 (true/false) - if true, the item doesn't lose durability when used.
    •  CanDestroy: The only blocks this item may break when used by a player in adventure mode.
    •  CustomModelData: A value used in the "custom_model_data" item tag in the overrides of item models.

Block Tags[edit]

Blocks can be given tags to specify what blocks they may be placed against in Adventure mode, and to specify what Tile Entity NBT tags to apply to them when placed.

  •  tag: Parent tag
    •  CanPlaceOn: Determines which blocks that blocks with this tag can be placed against in adventure mode.
      • : The block ID.
    •  BlockEntityTag: Block entity NBT tags which are applied when this block is placed.[1] Used to store data on banners and shields or on blocks obtained in creative by holding ctrl (or ⌘ Cmd on mac) and pressing pick block on a block containing a block entity.
    •  BlockStateTag: A compound where each key is a block state key, and the value is the block state value to force place for this block.
      •  Block state key: The block state value of the block to edit, for example facing: "east".

Enchantments[edit]

There are two ways enchantments are associated with items; the first way is that the item is actually enchanted and the enchantment affects the behavior of the item, and the second way is that the item is an enchanted book which simply stores the enchantments without actually affecting the behavior of the item. There is also the RepairCost tag which tracks anvil usage for items, making them more costly with every use of the anvil.

  •  tag: Parent tag.
    •  Enchantments: Contains enchantments on this item that affect the way the item works.
      • : A single enchantment.
        •  id: The name of the enchantment.
        •  lvl: The level of the enchantment, where 1 is level 1. Saved as short when created by enchanting tables or loot tables, but read as an int and supports full int range.
    •  StoredEnchantments: Contains enchantments for enchanted books.
      • : A stored enchantment, identical structure to each enchantment in Enchantments.
    •  RepairCost: Number of experience levels to add to the base level cost when repairing, combining, or renaming this item with an Anvil.

StoredEnchantments tooltips are not displayed if edited onto an item other than an enchanted book. Enchantments stored in Enchantments, however, are always displayed in the tooltip and cause the item to glow, even if they cannot have any effect.

Attribute Modifiers[edit]

All items can be given Modifiers which affect various Attributes of the player/mob which wears or holds them. Note that if an item has vanilla default AttributeModifiers, these cease to exist if this tag is added (e.g. a Diamond Sword given an empty AttributeModifiers list no longer provides a boost to damage). Also note that the default vanilla AttributeModifiers do not actually use this tag, and as such, it does not appear on a natural item.

  •  tag: Parent tag.


    •  AttributeModifiers: Contains Attribute Modifiers on this item which modify Attributes of the wearer or holder (if the item is not in the hand or armor slots, it has no effect).
      • : A single Attribute Modifier.
        •  AttributeName: The name of the Attribute this Modifier is to act upon.
        •  Name: The name of the Modifier. Has no known effect.
        •  Slot: Slot the item must be in for the modifier to take effect. "mainhand", "offhand", "feet", "legs", "chest", or "head".
        •  Operation: Modifier Operation. See Attribute Modifiers for info.
        •  Amount: Amount of change from the modifier.
        •  UUID: The modifier's UUID, stored as four ints. Used when equipping and unequipping the item to identify which modifier to add or remove from the entity.

Potion Effects[edit]

Potions, splash potions, lingering potions, and tipped arrows can have multiple, customized effects via the CustomPotionEffects tag. These effects are added to the default effect under the Potion tag if present. In addition the color can be overridden with the CustomPotionColor tag.

  •  tag: Parent tag.
    •  CustomPotionEffects: The custom potion effects (status effects) this potion or tipped arrow has.
      • One of these for each effect.
        •  Id: The numeric ID of the effect.
        •  Amplifier: The amplifier of the effect, with level I having value 0. Negative levels are discussed here. Optional, and defaults to level I.
        •  Duration: The duration of the effect in ticks. Values 0 or lower are treated as 1. Optional, and defaults to 1 tick.
        •  Ambient: 1 or 0 (true/false) - whether or not this is an effect provided by a beacon and therefore should be less intrusive on the screen. Optional, and defaults to false.
        •  ShowParticles: 1 or 0 (true/false) - whether or not this effect produces particles. Optional, and defaults to true.
        •  ShowIcon: 1 or 0 (true/false) - true if effect icon is shown. false if no icon is shown.
    •  Potion: The name of the default potion effect. This name differs from the status effect name. For example, the value for an "Instant Health II" potion is "minecraft:strong_healing". A potion or tipped arrow getting its effects from this tag is named with the proper effect. The default value is "minecraft:empty", which gives it the "Uncraftable" name.
    •  CustomPotionColor: The item uses this custom color, and area-of-effect clouds, arrows, and splash and lingering potions use it for their particle effects. This color does not extend, however, to the particles given off by entities who ultimately receive the effect. The numeric color code are calculated from the Red, Green and Blue components using this formula: Red<<16 + Green<<8 + Blue. For positive values larger than 0x00FFFFFF, the top byte is ignored. All negative values produce white.

Crossbows[edit]

Crossbows use NBT data to save what item is charged in the crossbow

  •  tag: Parent tag.
    •  ChargedProjectiles: The items this crossbow has charged, normally one entry (three if enchanted with multishot)
    •  Charged: If the crossbow is charged.

Display Properties[edit]

Leather armor can be colored, and all items can have custom display names and lore. Various tooltips can also be hidden.

  •  tag: Parent tag.
    •  display: Display properties.
      •  color: The color of the leather armor. The tooltip displays "Dyed" if advanced tooltips are disabled, otherwise it displays the hexadecimal color value. Color codes are calculated from the Red, Green and Blue components using this formula:
        Red<<16 + Green<<8 + Blue[2]
      •  Name: The JSON text component to use to display the item.
      •  Lore: List of strings to display as lore for the item.
        • A line of text for the lore of an item.
    •  HideFlags: Bit field determining which parts of the tooltip to hide on an item. 1 for "Enchantments", 2 for "AttributeModifiers", 4 for "Unbreakable", 8 for "CanDestroy", 16 for "CanPlaceOn", 32 for various other information (including potion effects, "StoredEnchantments", written book "generation" and "author", "Explosion", "Fireworks", and map tooltips), and 64 for "Dyed" on leather armors. For example, setting to 3 (1 + 2) would hide both "Enchantments" (1) and "AttributeModifiers" (2) tags, and setting to 127 would hide everything.

Written Books[edit]

Written books use NBT data to save their contents as well as miscellaneous extra information.

  •  tag: Parent tag.
    •  resolved: Optional. Created and set to 1 when the book (or a book from the stack) is opened for the first time after being created. Used to determine whether to resolve advanced components within JSON, because their values become fixed at that point.
    •  generation: Optional. The copy tier of the book. 0 = original, 1 = copy of original, 2 = copy of copy, 3 = tattered. If the value is greater than 1, the book cannot be copied. Does not exist for original books. If this tag is missing, it is assumed the book is an original. 'Tattered' is unused in normal gameplay, and functions identically to the 'copy of copy' tier.
    •  author: The author of the written book.
    •  title: The title of the written book. Lower priority than the item name set by tag.display.Name. Can not be used to open locked containers.
    •  pages: The list of pages in the book.
      • : A single page in the book. Each page is a serialized JSON text.

Book and Quills[edit]

Book and Quills use NBT data to save their contents.

  •  tag: Parent tag.
    •  pages: The list of pages in the book.
      • : A single page in the book. Each page is a string and uses the escape sequence \n for a line break. However, the command parser does not accept \n, because of which line breaks need to be set by a player or using loot tables.

Player Heads[edit]

Heads of the player variety can be associated with a specific username to take on the skin of that player when placed. The hand-held item is also updated with the new skin. Within this section, the "owner" of a head means the player whose head it is a copy of, and a player whose inventory contains a head is called the "holder".

  •  tag: Parent tag.
    •  SkullOwner: The username of the player this is a skull of. This gets converted to the compound version on almost any action.
    •  SkullOwner: Different definition for the skull's owner.
      •  Id: UUID of owner, stored as four ints. Optional. Used to update the other tags when the chunk loads or the holder logs in, in case the owner's name has changed.
      •  Name: Username of owner. If missing or empty, the head appears as a Steve head. Otherwise, used to store or retrieve the downloaded skin in the cache. Need not be a valid player name, but must not be all spaces.
      •  Properties
        •  textures
          • : An individual texture.
            •  Signature: Optional.
            •  Value: A Base64-encoded JSON object.[3]
              •  timestamp: Optional: Unix time in milliseconds.
              •  profileId: Optional: The hexadecimal text form of the player's UUID, without hyphens.
              •  profileName: Optional: Player name.
              •  isPublic: Optional.
              •  textures
                •  SKIN
                  •  url: URL of a player skin on textures.minecraft.net.
                •  CAPE: Optional.
                  •  url: URL of a player cape (64x32 PNG).


Fireworks[edit]

Fireworks use the tag tag to store information about their effects.

  •  tag: Parent tag.
    •  Explosion: One of these may appear on a firework star.
      •  Flicker: 1 or 0 (true/false) - true if this explosion has the Twinkle effect (glowstone dust). May be absent.
      •  Trail: 1 or 0 (true/false) - true if this explosion has the Trail effect (diamond). May be absent.
      •  Type: The shape of this firework's explosion. 0 = Small Ball, 1 = Large Ball, 2 = Star-shaped, 3 = Creeper-shaped, 4 = Burst. Other values are named "Unknown Shape" and render as Small Ball.
      •  Colors: Array of integer values corresponding to the primary colors of this firework's explosion. If custom color codes are used, the game renders it as "Custom" in the tooltip, but the proper color is used in the explosion. Custom colors are integers in the same format as the color tag from Display Properties.
      •  FadeColors: Array of integer values corresponding to the fading colors of this firework's explosion. Same handling of custom colors as Colors. May be absent.
    •  Fireworks: One of these may appear on a firework rocket.
      •  Flight: Indicates the flight duration of the firework (equals the amount of gunpowder used in crafting the rocket). Can be anything from -128 to 127.
      •  Explosions: List of compounds representing each explosion this firework causes.
        • Same format as 'Explosion' compound on a firework star, as described above.

Armor Stands and Spawn Eggs[edit]

Armor stands and spawn eggs may contain potential entity data.

  •  tag: Parent tag.
    •  EntityTag: Stores entity data that is applied to the entity when created.

Buckets of Fish[edit]

Buckets of Fish may contain potential entity data.

  •  tag: Parent tag.
    •  BucketVariantTag: The variant data of the tropical fish in the bucket. Only applies to Bucket of Tropical Fish.
    •  EntityTag: Stores entity data that is applied to the fish when it's poured out. If this data includes a tropical fish variant, it overrides the one provided in BucketVariantTag.
      • See Fish entity format.

Maps[edit]

Maps may be scaled.

  •  tag: Parent tag.
    •  map: The map number.
    •  map_scale_direction: Only internally used when scaling a map, after that directly removed: The amount to increase the current map scale by when crafting. Always 1.
    •  Decorations: A list of optional icons to display on the map. Decorations that are removed or modified do not update until the world is reloaded.
      • An individual decoration.
        •  id: An arbitrary unique string identifying the decoration.
        •  type: The ID of the map icon to display.
        •  x: The world X position of the decoration.
        •  z: The world Z position of the decoration.
        •  rot: The rotation of the symbol, ranging from 0.0 to 360.0, measured clockwise. A rotation of 0 displays the icon upside-down compared to its appearance in the icon texture.
    •  display: The display tag.
      •  MapColor: The color of the markings on the item's texture.

Suspicious Stew[edit]

Suspicious stews store their potion effects.

  •  tag: Parent tag.
    •  Effects: The status effects this suspicious stew has.
      • One of these for each effect.
        •  EffectId: The numeric ID of the effect.
        •  EffectDuration: The duration of the effect in ticks. Values 0 or lower are treated as 1. Optional, and defaults to 160 ticks (8 seconds).

Debug Sticks[edit]

Debug sticks use the NBT to save the block state to edit for each block.

  •  tag: Parent tag.
    •  DebugProperty: A compound where each key is a block ID, and the value is the block state key to edit for that block ID. Block tags are not supported.
      •  Block ID: The block state key of the block to edit, for example "minecraft:oak_fence": "east".

Compasses[edit]

When used as a lodestone compass, compasses store information about their targeted lodestone.

  •  tag: Parent tag.
    •  LodestoneTracked: Optional. 1 or 0 (true/false) - true if the compass is connected to a lodestone. When false, LodestoneDimension and LodestonePos is not automatically removed when the lodestone is destroyed, but the compass still points to that location.
    •  LodestoneDimension: Optional. The dimension of the lodestone to which the compass is pointing.
    •  LodestonePos: Optional. The coordinates of the lodestone to which the compass is pointing.
      •  X: x coordinate
      •  Y: y coordinate
      •  Z: z coordinate

Inventory slot numbers[edit]

This shows the numbers used to specify the slot in the inventory while editing with an NBT editor.

History[edit]

Clock JE2 BE2.gif
This section needs to be updated.
The reason given is: Almost certainly missing a lot of prior history
Please update this section to reflect recent updates or newly available information.
Java Edition
1.7.2?Added Unbreakable tag for tools.
1.814w06aAdded CanDestroy for tools.
Added HideFlags to items.
14w07aAdded BlockEntityTag for all blocks.
14w10aAdded a 5th bit (value of 32) to HideFlags that hides potion effects.
14w33aAdded SelectedItem for all items.
1.12pre1Added enteredNetherPosition to players, for use with the minecraft:nether_travel advancement trigger.
1.1318w01aName tag is now a text component.
Removed the LocName tag. Instead of LocName:"gui.toTitle", use Name:"{\"translate\":\"gui.toTitle\"}".
18w21aench tag has been renamed Enchantments.
1.1418w43aLore tag is now a text component.
Added CustomModelData tag to set custom item model with resource packs.
19w06aAdded BlockStateTag for item forms of blocks.
1.16.220w27aAdded Flag 64 to HideFlags to hide "Dyed" on leather armor.[4]

References[edit]

  1. Assuming the block is of a type that creates a block entity at all. If not, BlockEntityTag has no effect.
  2. For positive values larger than 0x00FFFFFF, the top byte is ignored. All negative values produce white.
  3. FVbico and Steven W.d.V.'s comments on MC-51003.
  4. MC-49476