doc/world_format.txt

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