Player.dat format

<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

• The root tag. In level.dat files, this tag is called "Player".
  • All tags from Entities except the id, CustomName, and CustomNameVisible tags.
  • All tags from Mobs except Equipment, DropChances, CanPickUpLoot, PersistenceRequired, Leashed, and Leash.
  •  DataVersion: Version of the player NBT structure.
  •  Dimension: The dimension the player is in. -1 is the Nether, 0 is the Overworld, 1 is the End. Other values are interpreted as 0.
  •  playerGameType: The game mode of the player. 0 is Survival, 1 is Creative, 2 is Adventure and 3 is Spectator.
  •  Score: The Score displayed upon death.
  •  SelectedItemSlot: The selected hotbar slot of the player.
  •  SelectedItem: Data of the item currently being held by the player, excluding the Slot tag.
    • See Item Format.
  •  SpawnX: See below.
  •  SpawnY: May not exist. The coordinates of the player's bed. These tags are only removed if the player attempts to respawn with no valid bed to spawn at at these coordinates. They are unaffected by breaking beds at these coordinates, and are unaffected by the player's death.
  •  SpawnZ: See above.
  •  SpawnForced: 1 or 0 (true/false) - True if the player should spawn at the above coordinates even if no bed can be found.
  •  Sleeping: 1 or 0 (true/false) - true if the player was in a bed; has no effect on whether the player is in a bed when they log in.
  •  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.
    • An item in the inventory, includes the Slot tag.
      • See Item Structure below.
  •  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.
      • See Item Structure below.
  •  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.
  •  RootVehicle^{(since 15w41a)}: The root entity that the player is riding.
    •  AttachLeast: The UUIDLeast of the entity the player is riding.
    •  AttachMost: The UUIDMost of the entity the player is riding.
    •  Entity: The NBT data of the root vehicle.
      • See Entity Format.

Item structure

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.

• The item's root tag. Some instances may give this tag a name, other times it is nameless because it is in a list.
  •  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: May not exist. The inventory slot the item is in.
  •  Damage: The data value for this item. The name "Damage" comes from when only tools used this value, now many other items use this value for other purposes. For blocks, it is the 4-bit "block data" tag that determines a variant of the block. Defaults to 0.
  •  id: Item/Block ID (This is a Short tag prior to 1.8.) If not specified, Minecraft changes the item to stone (setting ID to 1 and Damage to 0, and ignoring any existing Damage value) when loading the chunk or summoning the item .
  •  tag: Additional information about the item, discussed in the below sections. This tag is optional for most items.

General Tags

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

•  tag: The tag tag.
  •  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.
    • : The block ID.

Block Tags

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: The tag 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. Used to store data on banners or on blocks obtained in creative by holding ctrl and pressing pick block on a block containing a block entity.
    • See Tile Entity Format. Excludes x, y, z, and id tags.

Enchantments

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: The tag tag.
  •  ench: Contains enchantments on this item that affect the way the item works.
    • : A single enchantment.
      •  id: ID of the enchantment.
      •  lvl: Level of the enchantment, where 1 is level 1.
  •  StoredEnchantments: Contains enchantments for enchanted books.
    • : A stored enchantment, identical structure to each enchantment in ench.
  •  RepairCost: Number of enchantment levels to add to the base level cost when repairing, combining, or renaming this item with an Anvil.

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

Attribute Modifiers

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 will cease to exist if this tag is added (e.g. a Diamond Sword given an empty AttributeModifiers list will no longer provide a boost to damage). Also note that the default vanilla AttributeModifiers do not actually use this tag, and as such, it will not appear on a natural item.

•  tag: The tag 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 will have no effect).
    • : A single Attribute Modifier.
      •  AttributeName: The name of the Attribute this Modifier is to act upon.
      •  Name: Name of the Modifier
      •  Slot: Slot the item must be in for the modifier to take effect. "mainhand", "offhand", "feet", "legs", "torso", or "head".
      •  Operation: Modifier Operation. See Attribute Modifiers for info.
      •  Amount: Amount of change from the modifier.
      •  UUIDMost: Uppermost bits of the modifier's UUID.
      •  UUIDLeast: Lowermost bits of the modifier's UUID.

Potion Effects

Potions, splash potions, lingering potions and tipped arrows ^{(since 15w31a)} can have multiple, customized effects via the tag tag, bypassing using the data value of the item. The data value is used only for the way the potion looks if these tags are present.

•  tag: The tag tag.
  •  CustomPotionEffects: The custom Potion effects this potion has.
    • One of these for each effect.
      •  Id: The ID of the effect.
      •  Amplifier: The amplifier of the effect, with 0 being level 1.
      •  Duration: The duration of the effect in ticks.
      •  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. This tag is optional and defaults to 0. Due to a bug, it has no effect on splash potions.
      •  ShowParticles: 1 or 0 (true/false) - whether or not this effect produces particles. This tag is optional and defaults to 1. Due to a bug, it has no effect on splash potions.
  •  Potion ^{(since 15w31a)}: The name of the default potion effect. This name differs from the potion effect name. For example, the value for an "Instant Health II" potion is "minecraft:strong_healing".

Display Properties

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

•  tag: The tag tag.
  •  display: Display properties.
    •  color: The color of the leather armor. Color codes are calculated from the Red, Green and Blue components using this formula:
      Red<<16 + Green<<8 + Blue If this is specified for an item other than leather armor, the tooltip will say "Dyed" but the appearance won't be affected.
    •  Name: The name to display for an 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 "ench", 2 for "AttributeModifiers", 4 for "Unbreakable", 8 for "CanDestroy", 16 for "CanPlaceOn", and 32 for various other information (including potion effects, "StoredEnchantments", written book "generation" and "author", "Explosion", "Fireworks", and map tooltips). For example, setting to 3 would hide both "ench" and "AttributeModifiers" tags, and setting to 63 would hide everything.

Written Books

Both book and quill and written book use the tag tag to store information about the book. Only written books store the title, author, and generation of the book; pages is stored in both varieties.

•  tag: The tag tag.
  •  resolved: Optional. Created and set to 1 when the book (or a book from the stack) is opened for the first time after signing. Used to determine whether to parse target selectors (including which player is selected by {score:{name:"*", ...}}) within JSON, because their selections become fixed at that point.
  •  generation: 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.
  •  author: The author of the written book.
  •  title: The title of the written book.
  •  pages: The list of pages in the book.
    • A single page in the book. If generated by writing in a book and quill in-game, each page is a string in double quotes and uses the escape sequences \" for a double quote, \n for a line break and \\ for a backslash. If created by commands or external tools, a page can be a serialized JSON object or an array of strings and/or objects (see Commands#Raw JSON text) or an unescaped string.

Player Heads

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: The tag tag.
  •  SkullOwner: The username of the player this is a skull of for pre-1.8. Note that SkullOwner is for the item in inventories, whereas ExtraType is for skull blocks placed on the ground.
  •  SkullOwner: 1.8's definition for the skull's owner.
    •  Id: UUID of owner. 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 will appear 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.
            •  timestamp: Optional: Unix time in milliseconds.
            •  profileId: Optional: Player 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

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

•  tag: The tag tag.
  •  Explosion: One of these may appear on a firework star.
    •  Flicker: 1 or 0 (true/false) - true if this explosion will have the Twinkle effect (glowstone dust). May be absent.
    •  Trail: 1 or 0 (true/false) - true if this explosion will have 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 will be 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 will render it as "Custom" in the tooltip, but the proper color will be 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). While this value can be anything from -128 to 127, values of -2 and under almost never detonate at all.
    •  Explosions: List of compounds representing each explosion this firework will cause.
      • Same format as 'Explosion' compound on a firework star, as described above.

Armor Stands

Armor stands may contain potential entity data.

•  tag: The tag tag.
  •  EntityTag: Stores entity data that is applied to the armor stand when placed.
    • See Entity Format.

Maps

Maps may be scaled.

•  tag: The tag tag.
  •  map_is_scaling: 1 or 0 (true/false) - true if map is scaled. May not exist if map is not scaled. Map number is stored as Damage, scale value is stored in Map item format.
  •  Decorations: A list of optional decorations. It will display defined symbols on the map
    • An individual Decoration
      •  id: Identifier of the symbols
      •  type: Type of the symbol (see texture/map/map_icons.png)
      •  x: X position
      •  z: Z position
      •  rot: Rotation of the symbols

Notes

Inventory Slot Numbers

In the minecraft 1.9 pre-release, the off-hand slot is #-106.

References