doc/mapformat.txt

   1 =============================
   2 Minetest World Format 22...23
   3 =============================
   4
   5 This applies to a world format carrying the block serialization version
   6 22...23, used at least in 0.4.dev-20120322 ... 0.4.dev-20120606.
   7
   8 The block serialization version does not fully specify every aspect of this
   9 format; if compliance with this format is to be checked, it needs to be
  10 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.
  24 It 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 - unused node timers (version will be 24 when they are actually used):
 287 if version == 23:
 288   u8 unused version (always 0)
 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 Static objects
 375 ---------------
 376 Static objects are persistent freely moving objects in the world.
 377
 378 Object types:
 379 1: Test object
 380 2: Item
 381 3: Rat (deprecated)
 382 4: Oerkki (deprecated)
 383 5: Firefly (deprecated)
 384 6: MobV2 (deprecated)
 385 7: LuaEntity
 386
 387 1: Item:
 388   u8 version
 389   version 0:
 390     u16 len
 391     u8[len] itemstring
 392
 393 7: LuaEntity:
 394   u8 version
 395   version 1:
 396     u16 len
 397     u8[len] entity name
 398     u32 len
 399     u8[len] static data
 400     s16 hp
 401     s32 velocity.x * 10000
 402     s32 velocity.y * 10000
 403     s32 velocity.z * 10000
 404     s32 yaw * 1000
 405
 406 Itemstring format
 407 ------------------
 408 eg. 'default:dirt 5'
 409 eg. 'default:pick_wood 21323'
 410 eg. '"default:apple" 2'
 411 eg. 'default:apple'
 412 - The wear value in tools is 0...65535
 413 - There are also a number of older formats that you might stumble upon:
 414 eg. 'node "default:dirt" 5'
 415 eg. 'NodeItem default:dirt 5'
 416 eg. 'ToolItem WPick 21323'
 417
 418 Inventory serialization format
 419 -------------------------------
 420 - The inventory serialization format is line-based
 421 - The newline character used is "\n"
 422 - The end condition of a serialized inventory is always "EndInventory\n"
 423 - All the slots in a list must always be serialized.
 424
 425 Example (format does not include "---"):
 426 ---
 427 List foo 4
 428 Item default:sapling
 429 Item default:sword_stone 1 10647
 430 Item default:dirt 99
 431 Empty
 432 EndInventoryList
 433 List bar 9
 434 Empty
 435 Empty
 436 Empty
 437 Empty
 438 Empty
 439 Empty
 440 Empty
 441 Empty
 442 Empty
 443 EndInventoryList
 444 EndInventory
 445 ---
 446
 447 ==============================================
 448 Minetest World Format used as of 2011-05 or so
 449 ==============================================
 450
 451 Map data serialization format version 17.
 452
 453 0.3.1 does not use this format, but a more recent one. This exists here for
 454 historical reasons.
 455
 456 Directory structure:
 457 sectors/XXXXZZZZ or sectors2/XXX/ZZZ
 458 XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates.
 459 Under these, the block files are stored, called YYYY.
 460
 461 There also exists files map_meta.txt and chunk_meta, that are used by the
 462 generator. If they are not found or invalid, the generator will currently
 463 behave quite strangely.
 464
 465 The MapBlock file format (sectors2/XXX/ZZZ/YYYY):
 466 -------------------------------------------------
 467
 468 NOTE: Byte order is MSB first.
 469
 470 u8 version
 471 - map format version number, this one is version 17
 472
 473 u8 flags
 474 - Flag bitmasks:
 475   - 0x01: is_underground: Should be set to 0 if there will be no light
 476     obstructions above the block. If/when sunlight of a block is updated and
 477         there is no block above it, this value is checked for determining whether
 478         sunlight comes from the top.
 479   - 0x02: day_night_differs: Whether the lighting of the block is different on
 480     day and night. Only blocks that have this bit set are updated when day
 481         transforms to night.
 482   - 0x04: lighting_expired: If true, lighting is invalid and should be updated.
 483     If you can't calculate lighting in your generator properly, you could try
 484         setting this 1 to everything and setting the uppermost block in every
 485         sector as is_underground=0. I am quite sure it doesn't work properly,
 486         though.
 487
 488 zlib-compressed map data:
 489 - content:
 490   u8[4096]: content types
 491   u8[4096]: param1 values
 492   u8[4096]: param2 values
 493
 494 zlib-compressed node metadata
 495 - content:
 496   u16 version (=1)
 497   u16 count of metadata
 498   foreach count:
 499     u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
 500         u16 type_id
 501         u16 content_size
 502         u8[content_size] misc. stuff contained in the metadata
 503
 504 u16 mapblockobject_count
 505 - always write as 0.
 506 - if read != 0, just fail.
 507
 508 foreach mapblockobject_count:
 509   - deprecated, should not be used. Length of this data can only be known by
 510     properly parsing it. Just hope not to run into any of this.
 511
 512 u8 static object version:
 513 - currently 0
 514
 515 u16 static_object_count
 516
 517 foreach static_object_count:
 518   u8 type (object type-id)
 519   s32 pos_x * 1000
 520   s32 pos_y * 1000
 521   s32 pos_z * 1000
 522   u16 data_size
 523   u8[data_size] data
 524
 525 u32 timestamp
 526 - Timestamp when last saved, as seconds from starting the game.
 527 - 0xffffffff = invalid/unknown timestamp, nothing will be done with the time
 528                difference when loaded (recommended)
 529
 530 Node metadata format:
 531 ---------------------
 532
 533 Sign metadata:
 534   u16 string_len
 535   u8[string_len] string
 536
 537 Furnace metadata:
 538   TBD
 539
 540 Chest metadata:
 541   TBD
 542
 543 Locking Chest metadata:
 544   u16 string_len
 545   u8[string_len] string
 546   TBD
 547
 548 // END
 549