path: root/doc/mapformat.txt

I'll try to quickly document the newest block format in here (might contain
errors). Refer to the mapgen or minetestmapper script for the directory
structure and file naming. There are two sector namings possible,
sector/XXXXZZZZ and sector/XXX/ZZZ.

There also exists files map_meta.txt and chunk_meta, that are used by the
generator. If they are not found or invalid, the generator will currently
behave quite strangely.

The MapBlock file format (sectors2/XXX/ZZZ/YYYY):
-------------------------------------------------

NOTE: Byte order is MSB first.

u8 version
- map format version number, this one is version 17

u8 flags
- Flag bitmasks:
  - 0x01: is_underground: Should be set to 0 if there will be no light
    obstructions above the block. If/when sunlight of a block is updated and
	there is no block above it, this value is checked for determining whether
	sunlight comes from the top.
  - 0x02: day_night_differs: Whether the lighting of the block is different on
    day and night. Only blocks that have this bit set are updated when day
	transforms to night.
  - 0x04: lighting_expired: If true, lighting is invalid and should be updated.
    If you can't calculate lighting in your generator properly, you could try
	setting this 1 to everything and setting the uppermost block in every
	sector as is_underground=0. I am quite sure it doesn't work properly,
	though.

zlib-compressed map data:
- content:
  u8[4096]: content types
  u8[4096]: param1 values
  u8[4096]: param2 values

zlib-compressed node metadata
- content:
  u16 version (=1)
  u16 count of metadata
  foreach count:
    u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
	u16 type_id
	u16 content_size
	u8[content_size] misc. stuff contained in the metadata

u16 mapblockobject_count
- always write as 0.
- if read != 0, just fail.

foreach mapblockobject_count:
  - deprecated, should not be used. Length of this data can only be known by
    properly parsing it. Just hope not to run into any of this.

u8 static object version:
- currently 0

u16 static_object_count

foreach static_object_count:
  u8 type (object type-id)
  s32 pos_x * 1000
  s32 pos_y * 1000
  s32 pos_z * 1000
  u16 data_size
  u8[data_size] data

u32 timestamp
- Timestamp when last saved, as seconds from starting the game.
- 0xffffffff = invalid/unknown timestamp, nothing will be done with the time
               difference when loaded (recommended)

Node metadata format:
---------------------

Sign metadata:
  u16 string_len
  u8[string_len] string

Furnace metadata:
  TBD

Chest metadata:
  TBD

// END