doc/mapformat.txt

   1 ===============================================
   2 Minetest World Format used as of 0.4.dev-120322
   3 ===============================================
   4
   5 This applies to a world format carrying the block serialization version 22
   6 which is used at least in version 0.4.dev-120322.
   7
   8 The map data serialization version used is 22. It does not fully specify every
   9 aspect of this format; if compliance with this format is to be checked, it
  10 needs to be done by detecting if the files and data indeed follows it.
  11
  12 Legacy stuff
  13 =============
  14 Data can, in theory, be contained in the flat file directory structure
  15 described below in Version 17, but it is not officially supported. Also you
  16 may stumble upon all kinds of oddities in not-so-recent formats.
  17
  18 Files
  19 ======
  20 Everything is contained in a directory, the name of which is freeform, but
  21 often serves as the name of the world.
  22
  23 Currently the authentication and ban data is stored on a per-world basis. It
  24 can be copied over from an old world to a newly created world.
  25
  26 World
  27 |-- auth.txt ----- Authentication data
  28 |-- env_meta.txt - Environment metadata
  29 |-- ipban.txt ---- Banned ips/users
  30 |-- map_meta.txt - Map metadata
  31 |-- map.sqlite --- Map data
  32 |-- players ------ Player directory
  33 |   |-- player1 -- Player file
  34 |   '-- Foo ------ Player file
  35 `-- world.mt ----- World metadata
  36
  37 auth.txt
  38 ---------
  39 Contains authentication data, player per line.
  40   <name>:<password hash>:<privilege1,...>
  41 Format of password hash is <name><password> SHA1'd, in the base64 encoding.
  42
  43 Example lines:
  44 - Player "celeron55", no password, privileges "interact" and "shout":
  45     celeron55::interact,shout
  46 - Player "Foo", password "bar", privilege "shout":
  47     foo:iEPX+SQWIR3p67lj/0zigSWTKHg:shout
  48 - Player "bar", no password, no privileges:
  49     bar::
  50
  51 env_meta.txt
  52 -------------
  53 Simple global environment variables.
  54 Example content (added indentation):
  55   game_time = 73471
  56   time_of_day = 19118
  57   EnvArgsEnd
  58
  59 ipban.txt
  60 ----------
  61 Banned IP addresses and usernames.
  62 Example content (added indentation):
  63   123.456.78.9|foo
  64   123.456.78.10|bar
  65
  66 map_meta.txt
  67 -------------
  68 Simple global map variables.
  69 Example content (added indentation):
  70   seed = 7980462765762429666
  71   [end_of_params]
  72
  73 map.sqlite
  74 -----------
  75 Map data.
  76 See Map File Format below.
  77
  78 player1, Foo
  79 -------------
  80 Player data.
  81 Filename can be anything.
  82 See Player File Format below.
  83
  84 world.mt
  85 ---------
  86 World metadata.
  87 Example content (added indentation):
  88   gameid = mesetint
  89
  90 Player File Format
  91 ===================
  92
  93 - Should be pretty self-explanatory.
  94 - Note: position is in nodes * 10
  95
  96 Example content (added indentation):
  97   hp = 11
  98   name = celeron55
  99   pitch = 39.77
 100   position = (-5231.97,15,1961.41)
 101   version = 1
 102   yaw = 101.37
 103   PlayerArgsEnd
 104   List main 32
 105   Item default:torch 13
 106   Item default:pick_steel 1 50112
 107   Item experimental:tnt
 108   Item default:cobble 99
 109   Item default:pick_stone 1 13104
 110   Item default:shovel_steel 1 51838
 111   Item default:dirt 61
 112   Item default:rail 78
 113   Item default:coal_lump 3
 114   Item default:cobble 99
 115   Item default:leaves 22
 116   Item default:gravel 52
 117   Item default:axe_steel 1 2045
 118   Item default:cobble 98
 119   Item default:sand 61
 120   Item default:water_source 94
 121   Item default:glass 2
 122   Item default:mossycobble
 123   Item default:pick_steel 1 64428
 124   Item animalmaterials:bone
 125   Item default:sword_steel
 126   Item default:sapling
 127   Item default:sword_stone 1 10647
 128   Item default:dirt 99
 129   Empty
 130   Empty
 131   Empty
 132   Empty
 133   Empty
 134   Empty
 135   Empty
 136   Empty
 137   EndInventoryList
 138   List craft 9
 139   Empty
 140   Empty
 141   Empty
 142   Empty
 143   Empty
 144   Empty
 145   Empty
 146   Empty
 147   Empty
 148   EndInventoryList
 149   List craftpreview 1
 150   Empty
 151   EndInventoryList
 152   List craftresult 1
 153   Empty
 154   EndInventoryList
 155   EndInventory
 156
 157 Map File Format
 158 ================
 159
 160 Minetest maps consist of MapBlocks, chunks of 16x16x16 nodes.
 161
 162 In addition to the bulk node data, MapBlocks stored on disk also contain
 163 other things.
 164
 165 History
 166 --------
 167 We need a bit of history in here. Initially Minetest stored maps in a
 168 format called the "sectors" format. It was a directory/file structure like
 169 this:
 170   sectors2/XXX/ZZZ/YYYY
 171 For example, the MapBlock at (0,1,-2) was this file:
 172   sectors2/000/ffd/0001
 173
 174 Eventually Minetest outgrow this directory structure, as filesystems were
 175 struggling under the amount of files and directories.
 176
 177 Large servers seriously needed a new format, and thus the base of the
 178 current format was invented, suggested by celeron55 and implemented by
 179 JacobF.
 180
 181 SQLite3 was slammed in, and blocks files were directly inserted as blobs
 182 in a single table, indexed by integer primary keys, oddly mangled from
 183 coordinates.
 184
 185 Today we know that SQLite3 allows multiple primary keys (which would allow
 186 storing coordinates separately), but the format has been kept unchanged for
 187 that part. So, this is where it has come.
 188 </history>
 189
 190 So here goes
 191 -------------
 192 map.sqlite is an sqlite3 database, containg a single table, called
 193 "blocks". It looks like this:
 194
 195   CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY,`data` BLOB);
 196
 197 The key
 198 --------
 199 "pos" is created from the three coordinates of a MapBlock using this
 200 algorithm, defined here in Python:
 201
 202   def getBlockAsInteger(p):
 203       return int64(p[2]*16777216 + p[1]*4096 + p[0])
 204
 205   def int64(u):
 206       while u >= 2**63:
 207           u -= 2**64
 208       while u <= -2**63:
 209           u += 2**64
 210       return u
 211
 212 It can be converted the other way by using this code:
 213
 214   def getIntegerAsBlock(i):
 215       x = unsignedToSigned(i % 4096, 2048)
 216       i = int((i - x) / 4096)
 217       y = unsignedToSigned(i % 4096, 2048)
 218       i = int((i - y) / 4096)
 219       z = unsignedToSigned(i % 4096, 2048)
 220       return x,y,z
 221
 222   def unsignedToSigned(i, max_positive):
 223       if i < max_positive:
 224           return i
 225       else:
 226           return i - 2*max_positive
 227
 228 The blob
 229 ---------
 230 The blob is the data that would have otherwise gone into the file.
 231
 232 See below for description.
 233
 234 MapBlock serialization format
 235 ==============================
 236 NOTE: Byte order is MSB first (big-endian).
 237 NOTE: Zlib data is in such a format that Python's zlib at least can
 238       directly decompress.
 239
 240 u8 version
 241 - map format version number, this one is version 22
 242
 243 u8 flags
 244 - Flag bitmasks:
 245   - 0x01: is_underground: Should be set to 0 if there will be no light
 246     obstructions above the block. If/when sunlight of a block is updated
 247     and there is no block above it, this value is checked for determining
 248     whether sunlight comes from the top.
 249   - 0x02: day_night_differs: Whether the lighting of the block is different
 250     on day and night. Only blocks that have this bit set are updated when
 251     day transforms to night.
 252   - 0x04: lighting_expired: If true, lighting is invalid and should be
 253     updated.  If you can't calculate lighting in your generator properly,
 254     you could try setting this 1 to everything and setting the uppermost
 255     block in every sector as is_underground=0. I am quite sure it doesn't
 256     work properly, though.
 257   - 0x08: generated: True if the block has been generated. If false, block
 258     is mostly filled with CONTENT_IGNORE and is likely to contain eg. parts
 259     of trees of neighboring blocks.
 260
 261 u8 content_width
 262 - Number of bytes in the content (param0) fields of nodes
 263 - Always 1
 264
 265 u8 params_width
 266 - Number of bytes used for parameters per node
 267 - Always 2
 268
 269 zlib-compressed node data:
 270 - content:
 271   u8[4096]: param0 fields
 272   u8[4096]: param1 fields
 273   u8[4096]: param2 fields
 274 - The location of a node in each of those arrays is (z*16*16 + y*16 + x).
 275
 276 zlib-compressed node metadata list
 277 - content:
 278   u16 version (=1)
 279   u16 count of metadata
 280   foreach count:
 281     u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
 282     u16 type_id
 283     u16 content_size
 284     u8[content_size] (content of metadata)
 285
 286 u16 mapblockobject_count
 287 - Always 0
 288 - Should be removed in version 23 (TODO)
 289
 290 u8 static object version:
 291 - Always 0
 292
 293 u16 static_object_count
 294
 295 foreach static_object_count:
 296   u8 type (object type-id)
 297   s32 pos_x_nodes * 10000
 298   s32 pos_y_nodes * 10000
 299   s32 pos_z_nodes * 10000
 300   u16 data_size
 301   u8[data_size] data
 302
 303 u32 timestamp
 304 - Timestamp when last saved, as seconds from starting the game.
 305 - 0xffffffff = invalid/unknown timestamp, nothing should be done with the time
 306                difference when loaded
 307
 308 u8 name-id-mapping version
 309 - Always 0
 310
 311 u16 num_name_id_mappings
 312
 313 foreach num_name_id_mappings
 314   u16 id
 315   u16 name_len
 316   u8[name_len] name
 317
 318 EOF.
 319
 320 Format of nodes
 321 ----------------
 322 A node is composed of the u8 fields param0, param1 and param2.
 323
 324 The content id of a node is determined as so:
 325 - If param0 < 0x80,
 326     content_id = param0
 327 - Otherwise
 328     content_id = (param0<<4) + (param2>>4)
 329
 330 The purpose of param1 and param2 depend on the definition of the node.
 331
 332 The name-id-mapping
 333 --------------------
 334 The mapping maps node content ids to node names.
 335
 336 Node metadata format
 337 ---------------------
 338
 339 1: Generic metadata
 340   serialized inventory
 341   u32 len
 342   u8[len] text
 343   u16 len
 344   u8[len] owner
 345   u16 len
 346   u8[len] infotext
 347   u16 len
 348   u8[len] inventory drawspec
 349   u8 allow_text_input (bool)
 350   u8 removal_disabled (bool)
 351   u8 enforce_owner (bool)
 352   u32 num_vars
 353   foreach num_vars
 354     u16 len
 355     u8[len] name
 356     u32 len
 357     u8[len] value
 358
 359 14: Sign metadata
 360   u16 text_len
 361   u8[text_len] text
 362
 363 15: Chest metadata
 364   serialized inventory
 365
 366 16: Furnace metadata
 367   TBD
 368
 369 17: Locked Chest metadata
 370   u16 len
 371   u8[len] owner
 372   serialized inventory
 373
 374 Inventory serialization format
 375 -------------------------------
 376 - The inventory serialization format is line-based
 377 - The newline character used is "\n"
 378 - The end condition of a serialized inventory is always "EndInventory\n"
 379 - All the slots in a list must always be serialized.
 380
 381 Example (format does not include "---"):
 382 ---
 383 List foo 4
 384 Item default:sapling
 385 Item default:sword_stone 1 10647
 386 Item default:dirt 99
 387 Empty
 388 EndInventoryList
 389 List bar 9
 390 Empty
 391 Empty
 392 Empty
 393 Empty
 394 Empty
 395 Empty
 396 Empty
 397 Empty
 398 Empty
 399 EndInventoryList
 400 EndInventory
 401 ---
 402
 403 ==============================================
 404 Minetest World Format used as of 2011-05 or so
 405 ==============================================
 406
 407 Map data serialization format version 17.
 408
 409 0.3.1 does not use this format, but a more recent one. This exists here for
 410 historical reasons.
 411
 412 Directory structure:
 413 sectors/XXXXZZZZ or sectors2/XXX/ZZZ
 414 XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates.
 415 Under these, the block files are stored, called YYYY.
 416
 417 There also exists files map_meta.txt and chunk_meta, that are used by the
 418 generator. If they are not found or invalid, the generator will currently
 419 behave quite strangely.
 420
 421 The MapBlock file format (sectors2/XXX/ZZZ/YYYY):
 422 -------------------------------------------------
 423
 424 NOTE: Byte order is MSB first.
 425
 426 u8 version
 427 - map format version number, this one is version 17
 428
 429 u8 flags
 430 - Flag bitmasks:
 431   - 0x01: is_underground: Should be set to 0 if there will be no light
 432     obstructions above the block. If/when sunlight of a block is updated and
 433         there is no block above it, this value is checked for determining whether
 434         sunlight comes from the top.
 435   - 0x02: day_night_differs: Whether the lighting of the block is different on
 436     day and night. Only blocks that have this bit set are updated when day
 437         transforms to night.
 438   - 0x04: lighting_expired: If true, lighting is invalid and should be updated.
 439     If you can't calculate lighting in your generator properly, you could try
 440         setting this 1 to everything and setting the uppermost block in every
 441         sector as is_underground=0. I am quite sure it doesn't work properly,
 442         though.
 443
 444 zlib-compressed map data:
 445 - content:
 446   u8[4096]: content types
 447   u8[4096]: param1 values
 448   u8[4096]: param2 values
 449
 450 zlib-compressed node metadata
 451 - content:
 452   u16 version (=1)
 453   u16 count of metadata
 454   foreach count:
 455     u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
 456         u16 type_id
 457         u16 content_size
 458         u8[content_size] misc. stuff contained in the metadata
 459
 460 u16 mapblockobject_count
 461 - always write as 0.
 462 - if read != 0, just fail.
 463
 464 foreach mapblockobject_count:
 465   - deprecated, should not be used. Length of this data can only be known by
 466     properly parsing it. Just hope not to run into any of this.
 467
 468 u8 static object version:
 469 - currently 0
 470
 471 u16 static_object_count
 472
 473 foreach static_object_count:
 474   u8 type (object type-id)
 475   s32 pos_x * 1000
 476   s32 pos_y * 1000
 477   s32 pos_z * 1000
 478   u16 data_size
 479   u8[data_size] data
 480
 481 u32 timestamp
 482 - Timestamp when last saved, as seconds from starting the game.
 483 - 0xffffffff = invalid/unknown timestamp, nothing will be done with the time
 484                difference when loaded (recommended)
 485
 486 Node metadata format:
 487 ---------------------
 488
 489 Sign metadata:
 490   u16 string_len
 491   u8[string_len] string
 492
 493 Furnace metadata:
 494   TBD
 495
 496 Chest metadata:
 497   TBD
 498
 499 Locking Chest metadata:
 500   u16 string_len
 501   u8[string_len] string
 502   TBD
 503
 504 // END
 505