doc/mapformat.txt

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