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