doc/world_format.txt

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