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

• [NBT Compound / JSON Object] The root tag. In level.dat files, this tag is called Player.
  • Tags common to all entities see Template:Nbt inherit/entity/template[show]
  • except for the tags: CustomName, CustomNameVisible, and Glowing.
  • Tags common to all mobs see Template:Nbt inherit/mob/template[show]
  • except for the tags:, CanPickUpLoot, PersistenceRequired, Leash, drop_chances.
  • [NBT Compound / JSON Object] abilities: The abilities this player has.
    • [Byte] flying: 1 or 0 (true/false) - true if the player is currently flying.
    • [Float] flySpeed: The flying speed, set to 0.05.
    • [Byte] instabuild: 1 or 0 (true/false) - If true, the player can place blocks without depleting them. This is true for Creative mode, and false for other game modes.
    • [Byte] invulnerable: 1 or 0 (true/false) - Behavior is not the same as the invulnerable tag on other entities. If true, the player is immune to all damage and harmful effects except for void damage and /kill. Also, all mobs, whether hostile or not, are passive to the player. true when in Creative or Spectator mode, and false when in Survival or Adventure mode.
    • [Byte] mayBuild: 1 or 0 (true/false) - If true, the player can place blocks. true when in Creative or Survival mode, and false when in Spectator or Adventure mode.
    • [Byte] mayfly: 1 or 0 (true/false) - If true, the player can fly and doesn't take fall damage. true when in Creative and Spectator modes, and false when in Survival and Adventure modes.
    • [Float] walkSpeed: The walking speed, set to 0.1.
  • [NBT List / JSON Array] current_explosion_impact_pos: Position where the player was when the last explosion happened. Used for wind charge fall damage reduction.
  • [Int] DataVersion: Version of the player NBT structure. Is increased with every new snapshot and release. See Data version.
  • [String] Dimension: The ID of the dimension the player is in. Used to store the players last known location along with Pos.
  • [NBT List / JSON Array] EnderItems: Each compound tag in this list is an item in the player's 27-slot ender chest inventory. When empty, list type may have unexpected value.
    • [NBT Compound / JSON Object] An item in the inventory.
      • Includes the [Byte] Slot tag - slots are numbered 0–26, inclusive.
      • See Item_format § NBT_structure.
  • [NBT List / JSON Array] entered_nether_pos: May not exist. A list of 3 doubles, describing the Overworld position from which the player entered the Nether. Used by the nether_travel advancement trigger. Set every time the player passes through a portal from the Overworld to the Nether. When entering a dimension other than the nether (not by respawning) this tag is removed. Entering the Nether without using a portal does not update this tag.
    • [Double] x: The X coordinate in the Overworld.
    • [Double] y: The Y coordinate in the Overworld.
    • [Double] z: The Z coordinate in the Overworld.
  • [Float] foodExhaustionLevel: See Hunger § Mechanics.
  • [Int] foodLevel: The value of the hunger bar. Referred to as hunger. See Hunger.
  • [Float] foodSaturationLevel: Referred to as saturation. See Hunger § Mechanics.
  • [Int] foodTickTimer: See Hunger.
  • [Boolean] ignore_fall_damage_from_current_explosion: 1 or 0 (true/false) - true if the current explosion should apply a fall damage reduction. Only used by explosions from wind charges.
  • [NBT List / JSON Array] Inventory: Each compound tag in this list is an item in the player's inventory. (Note: when empty, list type may have unexpected value.)
    • [NBT Compound / JSON Object] An item in the inventory.
      • See Item_format § NBT_structure.
  • [NBT Compound / JSON Object] LastDeathLocation: May not exist. Location of the player's last death.
    • [String] dimension: Dimension of last death.
    • [Int Array] pos: Coordinates of last death.
  • [Int] playerGameType: The current game mode of the player. 0 means Survival, 1 means Creative, 2 means Adventure, and 3 means Spectator.
  • [Int] previousPlayerGameType: The previous game mode of the player.
  • [NBT Compound / JSON Object] recipeBook: Contains a JSON object detailing recipes the player has unlocked.
    • Tags related to the recipe book see Template:Nbt inherit/Recipe Book/template[show]
  • [NBT Compound / JSON Object] RootVehicle: May not exist. The root entity that the player is riding.
    • [Int Array] Attach: The UUID of the entity the player is riding, stored as four ints.
    • [NBT Compound / JSON Object] Entity: The NBT data of the root vehicle.
      • See Entity format.
  • [Int] Score: The score displayed upon death.
  • [Byte] seenCredits: 1 or 0 (true/false) - true if the player has entered the exit portal in the End at least once.
  • [NBT Compound / JSON Object] SelectedItem: Data of the item currently being held by the player, excluding the Slot tag. Only exists when using the /data command, this value is not saved in the player.dat format.
    • See item format.
  • [Int] SelectedItemSlot: The selected hotbar slot of the player.
  • [NBT Compound / JSON Object] ShoulderEntityLeft: The entity that is on the player's left shoulder. Always displays as a parrot.
    • See Entity format.
  • [NBT Compound / JSON Object] ShoulderEntityRight: The entity that is on the player's right shoulder. Always displays as a parrot.
    • See Entity format.
  • [Short] SleepTimer: The number of game ticks the player had been in bed. 0 when the player is not sleeping. When in bed, increases up to 100 ticks, then stops. Skips the night after enough players in beds have reached 100 (see Bed § Passing the night). When getting out of bed, instantly changes to 100 ticks and then increases for another 9 ticks (up to 109 ticks) before returning to 0 ticks.
  • [NBT Compound / JSON Object] respawn: May not exist. The respawn information of the player. Removed when 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.
    • [Int Array] pos: block position to spawn at
    • [Float] angle: angle to spawn with (default: 0.0)
    • [String] dimension: dimension id to spawn in (default minecraft:overworld)
    • [Boolean] forced: true if this spawn was set through commands (default: false)
  • [NBT Compound / JSON Object] warden_spawn_tracker: Contains data about the warden spawning process for this player.
    • [Int] warning_level: A warning level between 0, and 3 (inclusive). The warden spawns at level 3.
    • [Int] cooldown_ticks: The number of game ticks before the warning_level can be increased again. Decreases by 1 every tick. It is set to 200 game ticks (10 seconds) every time the warning level is increased.
    • [Int] ticks_since_last_warning: The number of game ticks since the player was warned for warden spawning. Increases by 1 every tick. After 12000 game ticks (10 minutes) it resets to level 3, and the warning_level decreases by 1 level.
  • [Int] XpLevel: The level shown on the experience bar.
  • [Float] XpP: The progress across the experience bar to the next level, stored as a percentage.
  • [Int] XpSeed: The seed used for the next enchantment in enchanting tables.
  • [Int] XpTotal: The total amount of experience the player has collected over time; used for the score upon death.

Item structure

Items are used both in the player's inventory and ender chest.

Inventory slot numbers

The image below shows the slot numbers of the player's inventory slots as of Java Edition 1.21.5.

In versions prior to 25w03a (including 1.21.4), the head, chest, legs, feet, and offhand slots were stored in the Inventory tag. In 1.21.4 and most prior versions these slots are numbered 103, 102, 101, 100 and -106 respectively; in 1.20.1 these values were 39, 38, 37, 36 and 40 instead.

History

[hide]Java Edition
1.7.10							Player data files are now named by UUID instead of by Username.
1.8			14w33a				Added SelectedItem for all items.
1.12			17w13a				Added ShoulderEntityLeft, and ShoulderEntityRight, which contain entity data about the entity on the player's shoulders.
							Added seenCredits to indicate whether the player has entered the exit portal at least once.
							Added recipeBook, which contain various information about the recipes the player has unlocked.
			pre1				Added enteredNetherPosition to players, for use with the minecraft:nether_travel advancement trigger.
1.16			Pre-release 6				Added previousPlayerGameType to store the previous game mode of the player.
1.19			22w14a				Added LastDeathLocation, together with the recovery compass.
1.21			Pre-release 4				Added current_explosion_impact_pos and ignore_fall_damage_from_current_explosion to store the wind charge's fall damage reduction.

Trivia

• Pre-1.7.10 player data files were named as the player's username rather than their UUID, this meant if the server was running on Windows and the player had a reserved filename as a player name they would not have their player data saved. List of Reserved Windows Filenames:
  • AUX
  • COM<n> where n is a digit from 1-9 (inclusive)
  • CON
  • LPT<n> where n is a digit from 1-9 (inclusive)
  • NUL
  • PRN