doc/world_format.txt

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