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