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   auth_backend = files          - which DB backend to use for authentication data
 133   server_announce = false       - whether the server is publicly announced or not
 134   load_mod_<mod> = false        - whether <mod> is to be loaded in this world
 135
 136 For load_mod_<mod>, the possible values are:
 137
 138 * `false` - Do not load the mod.
 139 * `true` - Load the mod from wherever it is found (may cause conflicts if the same mod appears also in some other place).
 140 * `mods/modpack/moddir` - Relative path to the mod
 141     * Must be one of the following:
 142         * `mods/`: mods in the user path's mods folder (ex `/home/user/.minetest/mods`)
 143         * `share/`: mods in the share's mods folder (ex: `/usr/share/minetest/mods`)
 144         * `/path/to/env`: you can use absolute paths to mods inside folders specified with the `MINETEST_MOD_PATH` env variable.
 145     * Other locations and absolute paths are not supported
 146     * Note that `moddir` is the directory name, not the mod name specified in mod.conf.
 147
 148 PostgreSQL backend specific settings:
 149   pgsql_connection = host=127.0.0.1 port=5432 user=mt_user password=mt_password dbname=minetest
 150   pgsql_player_connection = (same parameters as above)
 151   pgsql_readonly_connection = (same parameters as above)
 152   pgsql_auth_connection = (same parameters as above)
 153
 154 Redis backend specific settings:
 155   redis_address = 127.0.0.1  - Redis server address
 156   redis_hash = foo           - Database hash
 157   redis_port = 6379          - (optional) connection port
 158   redis_password = hunter2   - (optional) server password
 159
 160
 161 Player File Format
 162 ===================
 163
 164 - Should be pretty self-explanatory.
 165 - Note: position is in nodes * 10
 166
 167 Example content (added indentation):
 168   hp = 11
 169   name = celeron55
 170   pitch = 39.77
 171   position = (-5231.97,15,1961.41)
 172   version = 1
 173   yaw = 101.37
 174   PlayerArgsEnd
 175   List main 32
 176   Item default:torch 13
 177   Item default:pick_steel 1 50112
 178   Item experimental:tnt
 179   Item default:cobble 99
 180   Item default:pick_stone 1 13104
 181   Item default:shovel_steel 1 51838
 182   Item default:dirt 61
 183   Item default:rail 78
 184   Item default:coal_lump 3
 185   Item default:cobble 99
 186   Item default:leaves 22
 187   Item default:gravel 52
 188   Item default:axe_steel 1 2045
 189   Item default:cobble 98
 190   Item default:sand 61
 191   Item default:water_source 94
 192   Item default:glass 2
 193   Item default:mossycobble
 194   Item default:pick_steel 1 64428
 195   Item animalmaterials:bone
 196   Item default:sword_steel
 197   Item default:sapling
 198   Item default:sword_stone 1 10647
 199   Item default:dirt 99
 200   Empty
 201   Empty
 202   Empty
 203   Empty
 204   Empty
 205   Empty
 206   Empty
 207   Empty
 208   EndInventoryList
 209   List craft 9
 210   Empty
 211   Empty
 212   Empty
 213   Empty
 214   Empty
 215   Empty
 216   Empty
 217   Empty
 218   Empty
 219   EndInventoryList
 220   List craftpreview 1
 221   Empty
 222   EndInventoryList
 223   List craftresult 1
 224   Empty
 225   EndInventoryList
 226   EndInventory
 227
 228 Map File Format
 229 ================
 230
 231 Minetest maps consist of MapBlocks, chunks of 16x16x16 nodes.
 232
 233 In addition to the bulk node data, MapBlocks stored on disk also contain
 234 other things.
 235
 236 History
 237 --------
 238 We need a bit of history in here. Initially Minetest stored maps in a
 239 format called the "sectors" format. It was a directory/file structure like
 240 this:
 241   sectors2/XXX/ZZZ/YYYY
 242 For example, the MapBlock at (0,1,-2) was this file:
 243   sectors2/000/ffd/0001
 244
 245 Eventually Minetest outgrow this directory structure, as filesystems were
 246 struggling under the amount of files and directories.
 247
 248 Large servers seriously needed a new format, and thus the base of the
 249 current format was invented, suggested by celeron55 and implemented by
 250 JacobF.
 251
 252 SQLite3 was slammed in, and blocks files were directly inserted as blobs
 253 in a single table, indexed by integer primary keys, oddly mangled from
 254 coordinates.
 255
 256 Today we know that SQLite3 allows multiple primary keys (which would allow
 257 storing coordinates separately), but the format has been kept unchanged for
 258 that part. So, this is where it has come.
 259 </history>
 260
 261 So here goes
 262 -------------
 263 map.sqlite is an sqlite3 database, containing a single table, called
 264 "blocks". It looks like this:
 265
 266   CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY,`data` BLOB);
 267
 268 The key
 269 --------
 270 "pos" is created from the three coordinates of a MapBlock using this
 271 algorithm, defined here in Python:
 272
 273   def getBlockAsInteger(p):
 274       return int64(p[2]*16777216 + p[1]*4096 + p[0])
 275
 276   def int64(u):
 277       while u >= 2**63:
 278           u -= 2**64
 279       while u <= -2**63:
 280           u += 2**64
 281       return u
 282
 283 It can be converted the other way by using this code:
 284
 285   def getIntegerAsBlock(i):
 286       x = unsignedToSigned(i % 4096, 2048)
 287       i = int((i - x) / 4096)
 288       y = unsignedToSigned(i % 4096, 2048)
 289       i = int((i - y) / 4096)
 290       z = unsignedToSigned(i % 4096, 2048)
 291       return x,y,z
 292
 293   def unsignedToSigned(i, max_positive):
 294       if i < max_positive:
 295           return i
 296       else:
 297           return i - 2*max_positive
 298
 299 The blob
 300 ---------
 301 The blob is the data that would have otherwise gone into the file.
 302
 303 See below for description.
 304
 305 MapBlock serialization format
 306 ==============================
 307 NOTE: Byte order is MSB first (big-endian).
 308 NOTE: Zlib data is in such a format that Python's zlib at least can
 309       directly decompress.
 310 NOTE: Since version 29 zstd is used instead of zlib. In addition the entire
 311       block is first serialized and then compressed (except the version byte).
 312
 313 u8 version
 314 - map format version number, see serialization.h for the latest number
 315
 316 u8 flags
 317 - Flag bitmasks:
 318   - 0x01: is_underground: Should be set to 0 if there will be no light
 319     obstructions above the block. If/when sunlight of a block is updated
 320     and there is no block above it, this value is checked for determining
 321     whether sunlight comes from the top.
 322   - 0x02: day_night_differs: Whether the lighting of the block is different
 323     on day and night. Only blocks that have this bit set are updated when
 324     day transforms to night.
 325   - 0x04: lighting_expired: Not used in version 27 and above. If true,
 326     lighting is invalid and should be updated.  If you can't calculate
 327     lighting in your generator properly, you could try setting this 1 to
 328     everything and setting the uppermost block in every sector as
 329     is_underground=0. I am quite sure it doesn't work properly, though.
 330   - 0x08: generated: True if the block has been generated. If false, block
 331     is mostly filled with CONTENT_IGNORE and is likely to contain eg. parts
 332     of trees of neighboring blocks.
 333
 334 u16 lighting_complete
 335 - Added in version 27.
 336 - This contains 12 flags, each of them corresponds to a direction.
 337 - Indicates if the light is correct at the sides of a map block.
 338   Lighting may not be correct if the light changed, but a neighbor
 339   block was not loaded at that time.
 340   If these flags are false, Minetest will automatically recompute light
 341   when both this block and its required neighbor are loaded.
 342 - The bit order is:
 343   nothing,  nothing,  nothing,  nothing,
 344   night X-, night Y-, night Z-, night Z+, night Y+, night X+,
 345   day X-,   day Y-,   day Z-,   day Z+,   day Y+,   day X+.
 346   Where 'day' is for the day light bank, 'night' is for the night
 347   light bank.
 348   The 'nothing' bits should be always set, as they will be used
 349   to indicate if direct sunlight spreading is finished.
 350 - Example: if the block at (0, 0, 0) has
 351   lighting_complete = 0b1111111111111110,
 352   then Minetest will correct lighting in the day light bank when
 353   the block at (1, 0, 0) is also loaded.
 354
 355 if map format version >= 29:
 356   u32 timestamp
 357   - Timestamp when last saved, as seconds from starting the game.
 358   - 0xffffffff = invalid/unknown timestamp, nothing should be done with the time
 359                  difference when loaded
 360
 361   u8 name_id_mapping_version
 362   - Should be zero for map format version 29.
 363
 364   u16 num_name_id_mappings
 365   foreach num_name_id_mappings
 366     u16 id
 367     u16 name_len
 368     u8[name_len] name
 369 if map format version < 29:
 370   -- Nothing right here, timestamp and node id mappings are serialized later
 371
 372 u8 content_width
 373 - Number of bytes in the content (param0) fields of nodes
 374 if map format version <= 23:
 375     - Always 1
 376 if map format version >= 24:
 377     - Always 2
 378
 379 u8 params_width
 380 - Number of bytes used for parameters per node
 381 - Always 2
 382
 383 node data (zlib-compressed if version < 29):
 384 if content_width == 1:
 385     - content:
 386       u8[4096]: param0 fields
 387       u8[4096]: param1 fields
 388       u8[4096]: param2 fields
 389 if content_width == 2:
 390     - content:
 391       u16[4096]: param0 fields
 392       u8[4096]: param1 fields
 393       u8[4096]: param2 fields
 394 - The location of a node in each of those arrays is (z*16*16 + y*16 + x).
 395
 396 node metadata list (zlib-compressed if version < 29):
 397 - content:
 398   if map format version <= 22:
 399     u16 version (=1)
 400     u16 count of metadata
 401     foreach count:
 402       u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
 403       u16 type_id
 404       u16 content_size
 405       u8[content_size] content of metadata. Format depends on type_id, see below.
 406   if map format version >= 23:
 407     u8 version -- Note: type was u16 for map format version <= 22
 408       -- = 1 for map format version < 28
 409       -- = 2 since map format version 28
 410     u16 count of metadata
 411     foreach count:
 412       u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
 413       u32 num_vars
 414       foreach num_vars:
 415         u16 key_len
 416         u8[key_len] key
 417         u32 val_len
 418         u8[val_len] value
 419         u8 is_private -- only for version >= 2. 0 = not private, 1 = private
 420       serialized inventory
 421
 422 - Node timers
 423 if map format version == 23:
 424   u8 unused version (always 0)
 425 if map format version == 24: (NOTE: Not released as stable)
 426   u8 nodetimer_version
 427   if nodetimer_version == 0:
 428     (nothing else)
 429   if nodetimer_version == 1:
 430     u16 num_of_timers
 431     foreach num_of_timers:
 432       u16 timer position (z*16*16 + y*16 + x)
 433       s32 timeout*1000
 434       s32 elapsed*1000
 435 if map format version >= 25:
 436   -- Nothing right here, node timers are serialized later
 437
 438 u8 static object version:
 439 - Always 0
 440
 441 u16 static_object_count
 442
 443 foreach static_object_count:
 444   u8 type (object type-id)
 445   s32 pos_x_nodes * 10000
 446   s32 pos_y_nodes * 10000
 447   s32 pos_z_nodes * 10000
 448   u16 data_size
 449   u8[data_size] data
 450
 451 if map format version < 29:
 452   u32 timestamp
 453   - Same meaning as the timestamp further up
 454
 455   u8 name-id-mapping version
 456   - Always 0
 457
 458   u16 num_name_id_mappings
 459   foreach num_name_id_mappings
 460     u16 id
 461     u16 name_len
 462     u8[name_len] name
 463
 464 - Node timers
 465 if map format version >= 25:
 466   u8 length of the data of a single timer (always 2+4+4=10)
 467   u16 num_of_timers
 468   foreach num_of_timers:
 469     u16 timer position (z*16*16 + y*16 + x)
 470     s32 timeout*1000
 471     s32 elapsed*1000
 472
 473 EOF.
 474
 475 Format of nodes
 476 ----------------
 477 A node is composed of the u8 fields param0, param1 and param2.
 478
 479 if map format version <= 23:
 480     The content id of a node is determined as so:
 481     - If param0 < 0x80,
 482         content_id = param0
 483     - Otherwise
 484         content_id = (param0<<4) + (param2>>4)
 485 if map format version >= 24:
 486     The content id of a node is param0.
 487
 488 The purpose of param1 and param2 depend on the definition of the node.
 489
 490 The name-id-mapping
 491 --------------------
 492 The mapping maps node content ids to node names.
 493
 494 Node metadata format for map format versions <= 22
 495 ---------------------------------------------------
 496 The node metadata are serialized depending on the type_id field.
 497
 498 1: Generic metadata
 499   serialized inventory
 500   u32 len
 501   u8[len] text
 502   u16 len
 503   u8[len] owner
 504   u16 len
 505   u8[len] infotext
 506   u16 len
 507   u8[len] inventory drawspec
 508   u8 allow_text_input (bool)
 509   u8 removal_disabled (bool)
 510   u8 enforce_owner (bool)
 511   u32 num_vars
 512   foreach num_vars
 513     u16 len
 514     u8[len] name
 515     u32 len
 516     u8[len] value
 517
 518 14: Sign metadata
 519   u16 text_len
 520   u8[text_len] text
 521
 522 15: Chest metadata
 523   serialized inventory
 524
 525 16: Furnace metadata
 526   TBD
 527
 528 17: Locked Chest metadata
 529   u16 len
 530   u8[len] owner
 531   serialized inventory
 532
 533 Static objects
 534 ---------------
 535 Static objects are persistent freely moving objects in the world.
 536
 537 Object types:
 538 1: Test object
 539 7: LuaEntity
 540
 541 7: LuaEntity:
 542   u8 compatibility_byte (always 1)
 543   u16 len
 544   u8[len] entity name
 545   u32 len
 546   u8[len] static data
 547   s16 hp
 548   s32 velocity.x * 10000
 549   s32 velocity.y * 10000
 550   s32 velocity.z * 10000
 551   s32 yaw * 1000
 552   if PROTOCOL_VERSION >= 37:
 553     u8 version2 (=1)
 554     s32 pitch * 1000
 555     s32 roll * 1000
 556
 557 Itemstring format
 558 ------------------
 559 eg. 'default:dirt 5'
 560 eg. 'default:pick_wood 21323'
 561 eg. '"default:apple" 2'
 562 eg. 'default:apple'
 563 - The wear value in tools is 0...65535
 564 - There are also a number of older formats that you might stumble upon:
 565 eg. 'node "default:dirt" 5'
 566 eg. 'NodeItem default:dirt 5'
 567 eg. 'ToolItem WPick 21323'
 568
 569 Inventory serialization format
 570 -------------------------------
 571 - The inventory serialization format is line-based
 572 - The newline character used is "\n"
 573 - The end condition of a serialized inventory is always "EndInventory\n"
 574 - All the slots in a list must always be serialized.
 575
 576 Example (format does not include "---"):
 577 ---
 578 List foo 4
 579 Item default:sapling
 580 Item default:sword_stone 1 10647
 581 Item default:dirt 99
 582 Empty
 583 EndInventoryList
 584 List bar 9
 585 Empty
 586 Empty
 587 Empty
 588 Empty
 589 Empty
 590 Empty
 591 Empty
 592 Empty
 593 Empty
 594 EndInventoryList
 595 EndInventory
 596 ---