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