doc/mapformat.txt

   1 =========================================
   2          Minetest World Format
   3 =========================================
   4
   5 Format used as of 0.4.dev-120322
   6 ==================================
   7
   8 This applies to a world format carrying the serialization version 22 which
   9 is used at least in version 0.4.dev-120322.
  10
  11 The serialization version used is 22. It does not fully specify every aspect
  12 of this format; if compliance with this format is to be checked, it needs to
  13 be done by detecting if the files and data indeed follows it.
  14
  15 Legacy stuff:
  16 -------------
  17 Data can, in theory, be contained in the flat file directory structure
  18 described below in Version 17, but it is not officially supported.
  19
  20 Files:
  21 ------
  22 Everything is contained in a directory, the name of which is freeform, but
  23 often serves as the name of the world.
  24
  25 Currently the authentication and ban data is stored on a per-world basis. It
  26 can be copied over from an old world to a newly created world.
  27
  28 World
  29 |-- auth.txt ----- Authentication data
  30 |-- env_meta.txt - Environment metadata
  31 |-- ipban.txt ---- Banned ips/users
  32 |-- map_meta.txt - Map metadata
  33 |-- map.sqlite --- Map data
  34 |-- players ------ Player directory
  35 |   |-- player1 -- Player file
  36 |   '-- player2 -- Player file
  37 `-- world.mt ----- World metadata
  38
  39 auth.txt
  40 ---------
  41 Contains authentication data, player per line.
  42 <name>:<password hash as <name><password> SHA1 base64>:<privilege1,...>
  43 Example lines:
  44 Player "celeron55", no password, privileges "interact" and "shout":
  45 celeron55::interact,shout
  46 Player "Foo", password "bar", privileges "interact" and "shout":
  47 foo:iEPX+SQWIR3p67lj/0zigSWTKHg:interact,shout
  48
  49 env_meta.txt
  50 -------------
  51 --- Example content ---
  52 game_time = 73471
  53 time_of_day = 19118
  54 EnvArgsEnd
  55 -----------------------
  56
  57 ipban.txt
  58 ----------
  59
  60
  61 Format used as of 2011-05 or so
  62 ================================
  63
  64 Map data serialization format version 17.
  65
  66 Directory structure:
  67 sectors/XXXXZZZZ or sectors2/XXX/ZZZ
  68 XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates.
  69 Under these, the block files are stored, called YYYY.
  70
  71 There also exists files map_meta.txt and chunk_meta, that are used by the
  72 generator. If they are not found or invalid, the generator will currently
  73 behave quite strangely.
  74
  75 The MapBlock file format (sectors2/XXX/ZZZ/YYYY):
  76 -------------------------------------------------
  77
  78 NOTE: Byte order is MSB first.
  79
  80 u8 version
  81 - map format version number, this one is version 17
  82
  83 u8 flags
  84 - Flag bitmasks:
  85   - 0x01: is_underground: Should be set to 0 if there will be no light
  86     obstructions above the block. If/when sunlight of a block is updated and
  87         there is no block above it, this value is checked for determining whether
  88         sunlight comes from the top.
  89   - 0x02: day_night_differs: Whether the lighting of the block is different on
  90     day and night. Only blocks that have this bit set are updated when day
  91         transforms to night.
  92   - 0x04: lighting_expired: If true, lighting is invalid and should be updated.
  93     If you can't calculate lighting in your generator properly, you could try
  94         setting this 1 to everything and setting the uppermost block in every
  95         sector as is_underground=0. I am quite sure it doesn't work properly,
  96         though.
  97
  98 zlib-compressed map data:
  99 - content:
 100   u8[4096]: content types
 101   u8[4096]: param1 values
 102   u8[4096]: param2 values
 103
 104 zlib-compressed node metadata
 105 - content:
 106   u16 version (=1)
 107   u16 count of metadata
 108   foreach count:
 109     u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
 110         u16 type_id
 111         u16 content_size
 112         u8[content_size] misc. stuff contained in the metadata
 113
 114 u16 mapblockobject_count
 115 - always write as 0.
 116 - if read != 0, just fail.
 117
 118 foreach mapblockobject_count:
 119   - deprecated, should not be used. Length of this data can only be known by
 120     properly parsing it. Just hope not to run into any of this.
 121
 122 u8 static object version:
 123 - currently 0
 124
 125 u16 static_object_count
 126
 127 foreach static_object_count:
 128   u8 type (object type-id)
 129   s32 pos_x * 1000
 130   s32 pos_y * 1000
 131   s32 pos_z * 1000
 132   u16 data_size
 133   u8[data_size] data
 134
 135 u32 timestamp
 136 - Timestamp when last saved, as seconds from starting the game.
 137 - 0xffffffff = invalid/unknown timestamp, nothing will be done with the time
 138                difference when loaded (recommended)
 139
 140 Node metadata format:
 141 ---------------------
 142
 143 Sign metadata:
 144   u16 string_len
 145   u8[string_len] string
 146
 147 Furnace metadata:
 148   TBD
 149
 150 Chest metadata:
 151   TBD
 152
 153 Locking Chest metadata:
 154   u16 string_len
 155   u8[string_len] string
 156   TBD
 157
 158 // END
 159