Bedrock Edition level format

Minecraft Pocket Edition uses a completely different format for its saved games. Not much is understood about it yet. As of version 0.9.0 Pocket Edition uses a modified version Google's LevelDB, which uses the Zlib compression format for level storage. Pocket Edition versions 0.8.1 and below uses a modified NBT format which uses little-endian byte order for some files.

0.9.0 and above

LevelDB format

Note: this part is still being researched.

Minecraft PE 0.9.0 introduced a new world save format, based on LevelDB 1.17 with Zlib compression support added. Older worlds are automatically converted to the new format when loaded.

Mojang's modified LevelDB is available at https://github.com/Mojang/leveldb-mcpe , and the build parameters required to build it are documented by Tommaso at https://twitter.com/_tomcc/status/477950809427427328. The Official LevelDB page is at https://code.google.com/p/leveldb/

The database is stored in the db/ subdirectory of a Pocket Edition world. It seems this is also where terrain generation is stored. This is because you can turn an old world infinite by replacing its db folder with one from an infinite world.

There are three types of data stored in the database: terrain data, entity data, and tile entity data.

Key format: 9 byte key, which seems to consist of:

• x coordinate of chunk as little endian integer
• z coordinate of chunk as little endian integer
• one more byte indicating the type of the data:
  • 0x30 (48 in decimal, '0' ascii) for what appears to be terrain data
  • 0x31 (49 in decimal, '1' ascii) for tile entity data
  • 0x32 (50 in decimal, '2' ascii) for entity data
  • 0x76 (118 in decimal, 'v' ascii) for 1-byte data: always zero (placeholder chunks?)

There's also the special key ~local_player for an entity data entry that holds the local player entity. If entity data exists here, it takes precedence over the player data stored in level.dat.

Entity and tile entity data entries consist of individual entity CompoundTags concatenated together.

level.dat

The level.dat structure is the similar to the one from 0.8.1 and below.

Structure

• World data.
  •  Dimension: The dimension the player is in. 0 is the Overworld.
  •  GameType: Whether in survival (0) or in creative (1) mode.
  •  Generator: World Type: Old, Infinite, or Flat
  •  LastPlayed: Stores the Unix time stamp (in seconds) when the player saved the game.
  •  LevelName: Specifies the name of the level.
  • LimitedWorldOrigin. (Only applies to old type worlds)
    •  LimitedWorldOriginX: X coordinate where limited world generation started.
    •  LimitedWorldOriginY: Y coordinate where limited world generation started.
    •  LimitedWorldOriginZ: Z coordinate where limited world generation started.
  •  Platform: Seems to store the platform that the level is created on. Currently observed value is 2.
  •  RandomSeed: Level Seed
  •  SizeOnDisk: Estimated size of level in bytes
  • Spawn Coordinates of world
    •  SpawnX: X coordinate of the player's spawn position. Default is 0.
    •  SpawnY: Y coordinate of the player's spawn position. Default is 64.
    •  SpawnZ: Z coordinate of the player's spawn position. Default is 0.
  •  StorageVersion:Version of Pocket Edition Storage Tool, currently is 4
  •  Time: Stores the current "time of day" in ticks. There are 20 ticks per real-life second, and 14400 ticks per Minecraft day/night cycle, making the full cycle length 12 minutes—8 minutes shorter than the standard 20 minute day/night cycle. 0 is the start of daytime, 7200 is the start of sunset, 8280 is the start of nighttime, 13320 is the start of sunrise, and 14400 is daytime again. The value stored in level.dat is always increasing and can be larger than 14400, but the "time of day" is always modulo 14400 of the "Time" field value.
  •  dayCycleStopTime: Added in 8.0. Default is 18446744073709552000.
  •  spawnMobs: Disable (0) or enable (1) mob spawning.

0.8.1 and below

level.dat

The format of level.dat has been changed in 0.2.0; it is now a NBT formatted file, based on the format of level.dat in a Desktop world.

In a post-0.2.0 Pocket Edition world, level.dat is an uncompressed little-endian NBT file that stores environmental data (time of day, for example) and player health, inventory, velocity, and position within the map.

The file begins with an 8-byte header, consisting of a little-endian 4-byte integer indicating the type of the file, which is 3 (was 2 before latest update) for level.dat. It is followed by another integer container the length of the file, minus the header.

NBT Structure

• World data.
  •  GameType: Whether in survival (0) or in creative (1) mode.
  •  LastPlayed: Stores the Unix time stamp (in seconds) when the player saved the game.
  •  LevelName: Specifies the name of the level.
  •  Platform: Seems to store the platform that the level is created on. Currently observed value is 2.
  •  Player: Player entity information. See Entity Format and Mob Entity Format for details. It is missing the id tag and has additional elements:
    •  Armor: Each TAG_Compound in this list defines a piece of armor that the player is wearing. This is a list with length 4 - for helmet, chestplate, leggings, and boots.
      • Inventory item data
        •  id: Item or Block ID.
        •  Count: Number of items stacked in this inventory slot. Any item can be stacked, including tools. Range is 1-255. Values above 255 are not displayed in-game.
        •  Damage: For armour, the amount of wear they have suffered. The maximum durability of the armour means undamaged. When the Damage reaches 0, it breaks and disappears.
    •  Dimension: The dimension the player is in. 0 is the Overworld.
    •  Inventory: Each TAG_Compound in this list defines an item the player is carrying or holding.
      • Inventory item data
        •  Slot: Indicates which inventory slot this item is in.
        •  id: Item or Block ID.
        •  Count: Number of items stacked in this inventory slot. Any item can be stacked, including tools. Range is 1-255. Values above 255 are not displayed in-game.
        •  Damage: For tools, the amount of wear they have suffered. The maximum durability of the tool (for example, 33 for golden tools) means undamaged. When the Damage reaches 0, it breaks and disappears.
    •  Score: The score of the player.
    •  Sleeping: 1 or 0 (true/false) - true if the player was in a bed when this tag was saved; 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 when this tag was saved. No effect.
    •  SpawnX: X coordinate of the player's spawn position. Default is 0.
    •  SpawnY: Y coordinate of the player's spawn position. Default is 64.
    •  SpawnZ: Z coordinate of the player's spawn position. Default is 0.
    •  abilities: The abilities this player has.
      •  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.
      •  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.
  •  RandomSeed: Random number providing the Random Seed for the terrain.
  •  SizeOnDisk: Estimated size of the entire world in bytes.
  •  SpawnX: X coordinate of the world's spawn position. Default is 0.
  •  SpawnY: Y coordinate of the world's spawn position. Default is 64.
  •  SpawnZ: Z coordinate of the world's spawn position. Default is 0.
  •  StorageVersion: Version of Pocket Edition NBT, is 3.
  •  Time: Stores the current "time of day" in ticks. There are 20 ticks per real-life second, and 14400 ticks per Minecraft day/night cycle, making the full cycle length 12 minutes—8 minutes shorter than the standard 20 minute day/night cycle. 0 is the start of daytime, 7200 is the start of sunset, 8280 is the start of nighttime, 13320 is the start of sunrise, and 14400 is daytime again. The value stored in level.dat is always increasing and can be larger than 14400, but the "time of day" is always modulo 14400 of the "Time" field value.
  •  dayCycleStopTime: Added in 8.0. Default is 18446744073709552000.
  •  spawnMobs: Disable (0) or enable (1) mob spawning.

chunks.dat

This file stores the 16x16 (256) chunk arrays holding all 256x256x128 (8,388,608) blocks in each default map. Every 4,096 bytes or 4kb's is one sector length, where in total for a default map there are 5,377 sectors. The file has a maximum of 32x32 (1024) chunks and 512x512x128 (33,554,432) blocks, but in a default map generated by the game, the map will be its standard size. The type of the bytes in this file are mostly 32-bit little-endian, except for a few sections of data

The first sector of the file is a data location table, which points to what chunks are available and where in the map and the file. Every 128 bytes of the location table describes a row of chunks in the map, but usually there is only 64 bytes of data because there are only 16 chunks per row.

The format for each chunk in the location table is 15 XX ZZ 00, where the 15 (21_dec) describes how many sectors are in the section, the second number describes the X coordinate in hex to the top left corner of the chunk, the third number is the Z coordinate in hex describing which row the chunk is in, and the final number goes unused until an update where map sizes are increased. You can also think of the "X" coordinate as the chunk's starting point on the map.

To find the offset of a chunk based on the table, all one must do is use the algorithm 4096+(x*21*4096)+(z*21*16*4096), the reason being is the first sector is a location table, so we start at 4096. Every 86,016 bytes or 21*4096 bytes is a new chunk, so then times by x. It's the same for the z coordinate, just every 16 chunk sections is a new row, so multiply by 16.

Example of finding an offset is say we have these three numbers in the table, 15 4d 02 00, the first number tells how many sectors are in the chunk, in this case 21, the second number (4d_hex) is the "x coordinate", the third (02_hex) is the "z coordinate" and the fourth number is to be used when dealing with larger maps. So now we take 77*21*4096 and add it to 4096 (make up for the location table) to get 6,627,328, now add 2*21*4096*16 to get 9,379,840, which is the decimal offset of the chunk.

The first 8 sectors of the first chunk at offset 1000_hex or 4096_dec is the first array of blocks in the file. The first 4 bytes starting at offset 1000_hex or 4096_dec is a chunk header, identifying the start of a new chunk. The chunk header will always be 04 41 01 00 in hex. After the chunk header, every 128 blocks is a column. Every 16 columns is a new row. Columns can be stored as short[]'s (short arrays).

After the first 8 sectors of block data is 4 sectors of regular data in big-endian used to store information about certain blocks. Since this section is only 4 sectors long, each byte represents two blocks.

An example use of the data section is say you placed some blue wool and then some red wool in a column at [4,76,14] in the chunk. By dividing the X,Y,Z coordinates of the wool within the chunk in half you can find where the data for that block is [2,38,7]. Now that you have the new coordinates, you can find the byte by starting at the data sector's offset and then using the algorithm (x*64)+y+(z*64*16). The data at that offset would then be EB_hex, and since these sectors are big-endian you would read it as BE_hex. Since B is the data for blue wool and E is the data for red wool, you will have to split the byte and get B and E separate to get the individual data for those blocks.

After the 4 sectors of data is 4 sectors of skylight data. Once again every byte is two blocks and each byte should be read in big-endian like in the data sectors. If a light value is F, that means the lighting is dark, while if a light value is 0, then the lighting is light. Because the game automatically generates lighting, it is unimportant to modify this part of the file when generating a world via an outside program.

The last 4 sectors are like the skylight data, but instead are block light data. Once again every byte represents 2 blocks and should be read as big-endian. The light values are the same as skylight values, where F is dark and 0 is light. Once again, because the game automatically generates lighting, it is unimportant to modify this part of the file when generating a world via an outside program.

player.dat

In versions of Minecraft Pocket Edition before 0.2.0, this file stored the player inventory information, which is now stored in level.dat.

entities.dat

This file is added in version 0.2.0 Alpha, and uses the modified little endian uncompressed NBT format. It appears to store entity information using a format based on the Alpha Level Chunk Format.

In version 0.3.2, this file was extended to store Tile entity information as well.

The file has a 12 byte header. It begins with the ASCII Characters "ENT", then one zero byte, then a little-endian integer with the value 1, followed by another little endian integer stating the length of the file in bytes, not counting the header.

NBT Structure

• Root compound tag.
  •  Entities: Each TAG_Compound in this list defines an entity in the world. See Entity Format below.
  •  TileEntities: Each TAG_Compound in this list defines a Tile entity, such as a furnace, in the world.

Entity Format

Every entity is an unnamed TAG_Compound contained in the Entities list of a chunk file. The sole exception is the Player entity, stored in level.dat.

All entities share this base:

• Entity data
  •  id: Entity Type ID. Known values are 13 for Sheep, 32 for Zombie, and 64 for item drops.
  •  Pos: 3 TAG_Floats describing the current X,Y,Z position of the entity.
  •  Motion: 3 TAG_Floats describing the current dX,dY,dZ velocity of the entity. (Note: 0,0,0 is no motion.)
  •  Rotation: Two TAG_Floats representing rotation in degrees.
    • : The entity's rotation clockwise around the Y axis (called yaw). Due west is 0. Can have large values because it accumulates all of the entity's lateral rotation throughout the game.
    • : The entity's declination from the horizon (called pitch). Horizontal is 0. Positive values look downward. Does not exceed positive or negative 90 degrees.
  •  FallDistance: Distance the entity has fallen. Larger values cause more damage when the entity lands.
  •  Fire: Number of ticks until the fire is put out. Negative values reflect how long the entity can stand in fire before burning.
  •  Air: How much air the entity has, in ticks. Fills to a maximum of 300 in air. Decreases while underwater.
  •  OnGround: 1 if the entity is touching the ground.

Mobs

• Additional fields for mobs:

• •  AttackTime: Number of ticks the entity's "invincibility shield" is lasting after the entity was last struck.
  •  DeathTime: Number of ticks the entity has been dead for. Controls death animations.
  •  Health: Amount of health the entity has. Players and enemies normally have up to 20 health. Livestock has up to 10 health.
  •  HurtTime: Unknown, maybe time invincible after being hit

• Additional field for animals such as Sheep:

• •  Age: Age of the animal.

Sheep has two additional fields:

• •  Sheared: 1 or 0 (true/false) - true if the sheep has been shorn.
  •  Color: 0 to 15 - see wool data values for a mapping to colors. There is evidence that this value does not affect sheep rendering, but does affect wool drops.

• Additional fields for Item:

• •  Health: Starts at 5, and currently only decreases as the item takes fire damage. When health reaches 0, the item is destroyed.
  •  Age: The amount of time an item has been "untouched" on the ground. After 2400 'ticks', or 2 minutes, the item is destroyed.
  •  Item: Item data
    •  id: Item or Block ID.
    •  Damage: The amount of wear each item has suffered. 0 means undamaged. When the Damage exceeds the item's durability, it breaks and disappears. Only tools and armor accumulate damage normally.
    •  Count: Number of items contained in this item drop entity. Any item can be stacked, including tools, armor, and vehicles. Range is 1-255.

References