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
 275 zlib-compressed node metadata list
 276 - content:
 277   u16 version (=1)
 278   u16 count of metadata
 279   foreach count:
 280     u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
 281     u16 type_id
 282     u16 content_size
 283     u8[content_size] (content of metadata)
 284
 285 u16 mapblockobject_count
 286 - Always 0
 287 - Should be removed in version 23 (TODO)
 288
 289 u8 static object version:
 290 - Always 0
 291
 292 u16 static_object_count
 293
 294 foreach static_object_count:
 295   u8 type (object type-id)
 296   s32 pos_x_nodes * 10000
 297   s32 pos_y_nodes * 10000
 298   s32 pos_z_nodes * 10000
 299   u16 data_size
 300   u8[data_size] data
 301
 302 u32 timestamp
 303 - Timestamp when last saved, as seconds from starting the game.
 304 - 0xffffffff = invalid/unknown timestamp, nothing should be done with the time
 305                difference when loaded
 306
 307 u8 name-id-mapping version
 308 - Always 0
 309
 310 u16 num_name_id_mappings
 311
 312 foreach num_name_id_mappings
 313   u16 id
 314   u16 name_len
 315   u8[name_len] name
 316
 317 EOF.
 318
 319 Node metadata format
 320 ---------------------
 321
 322 1: Generic metadata
 323   serialized inventory
 324   u32 len
 325   u8[len] text
 326   u16 len
 327   u8[len] owner
 328   u16 len
 329   u8[len] infotext
 330   u16 len
 331   u8[len] inventory drawspec
 332   u8 allow_text_input (bool)
 333   u8 removal_disabled (bool)
 334   u8 enforce_owner (bool)
 335   u32 num_vars
 336   foreach num_vars
 337     u16 len
 338     u8[len] name
 339     u32 len
 340     u8[len] value
 341
 342 14: Sign metadata
 343   u16 text_len
 344   u8[text_len] text
 345
 346 15: Chest metadata
 347   serialized inventory
 348
 349 16: Furnace metadata
 350   TBD
 351
 352 17: Locked Chest metadata
 353   u16 len
 354   u8[len] owner
 355   serialized inventory
 356
 357 Inventory serialization format
 358 -------------------------------
 359 - The inventory serialization format is line-based
 360 - The newline character used is "\n"
 361 - The end condition of a serialized inventory is always "EndInventory\n"
 362 - All the slots in a list must always be serialized.
 363
 364 Example (format does not include "---"):
 365 ---
 366 List foo 4
 367 Item default:sapling
 368 Item default:sword_stone 1 10647
 369 Item default:dirt 99
 370 Empty
 371 EndInventoryList
 372 List bar 9
 373 Empty
 374 Empty
 375 Empty
 376 Empty
 377 Empty
 378 Empty
 379 Empty
 380 Empty
 381 Empty
 382 EndInventoryList
 383 EndInventory
 384 ---
 385
 386 ==============================================
 387 Minetest World Format used as of 2011-05 or so
 388 ==============================================
 389
 390 Map data serialization format version 17.
 391
 392 0.3.1 does not use this format, but a more recent one. This exists here for
 393 historical reasons.
 394
 395 Directory structure:
 396 sectors/XXXXZZZZ or sectors2/XXX/ZZZ
 397 XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates.
 398 Under these, the block files are stored, called YYYY.
 399
 400 There also exists files map_meta.txt and chunk_meta, that are used by the
 401 generator. If they are not found or invalid, the generator will currently
 402 behave quite strangely.
 403
 404 The MapBlock file format (sectors2/XXX/ZZZ/YYYY):
 405 -------------------------------------------------
 406
 407 NOTE: Byte order is MSB first.
 408
 409 u8 version
 410 - map format version number, this one is version 17
 411
 412 u8 flags
 413 - Flag bitmasks:
 414   - 0x01: is_underground: Should be set to 0 if there will be no light
 415     obstructions above the block. If/when sunlight of a block is updated and
 416         there is no block above it, this value is checked for determining whether
 417         sunlight comes from the top.
 418   - 0x02: day_night_differs: Whether the lighting of the block is different on
 419     day and night. Only blocks that have this bit set are updated when day
 420         transforms to night.
 421   - 0x04: lighting_expired: If true, lighting is invalid and should be updated.
 422     If you can't calculate lighting in your generator properly, you could try
 423         setting this 1 to everything and setting the uppermost block in every
 424         sector as is_underground=0. I am quite sure it doesn't work properly,
 425         though.
 426
 427 zlib-compressed map data:
 428 - content:
 429   u8[4096]: content types
 430   u8[4096]: param1 values
 431   u8[4096]: param2 values
 432
 433 zlib-compressed node metadata
 434 - content:
 435   u16 version (=1)
 436   u16 count of metadata
 437   foreach count:
 438     u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
 439         u16 type_id
 440         u16 content_size
 441         u8[content_size] misc. stuff contained in the metadata
 442
 443 u16 mapblockobject_count
 444 - always write as 0.
 445 - if read != 0, just fail.
 446
 447 foreach mapblockobject_count:
 448   - deprecated, should not be used. Length of this data can only be known by
 449     properly parsing it. Just hope not to run into any of this.
 450
 451 u8 static object version:
 452 - currently 0
 453
 454 u16 static_object_count
 455
 456 foreach static_object_count:
 457   u8 type (object type-id)
 458   s32 pos_x * 1000
 459   s32 pos_y * 1000
 460   s32 pos_z * 1000
 461   u16 data_size
 462   u8[data_size] data
 463
 464 u32 timestamp
 465 - Timestamp when last saved, as seconds from starting the game.
 466 - 0xffffffff = invalid/unknown timestamp, nothing will be done with the time
 467                difference when loaded (recommended)
 468
 469 Node metadata format:
 470 ---------------------
 471
 472 Sign metadata:
 473   u16 string_len
 474   u8[string_len] string
 475
 476 Furnace metadata:
 477   TBD
 478
 479 Chest metadata:
 480   TBD
 481
 482 Locking Chest metadata:
 483   u16 string_len
 484   u8[string_len] string
 485   TBD
 486
 487 // END
 488