1 =================================================
2 Minetest World Format used as of 0.4.dev-20120322
3 =================================================
5 This applies to a world format carrying the block serialization version 22
6 which is used at least in version 0.4.dev-20120322.
8 The block serialization version used is 22. It does not fully specify every
9 aspect of this format; if compliance with this format is to be checked, it
10 needs to be done by detecting if the files and data indeed follows it.
14 Data can, in theory, be contained in the flat file directory structure
15 described below in Version 17, but it is not officially supported. Also you
16 may stumble upon all kinds of oddities in not-so-recent formats.
20 Everything is contained in a directory, the name of which is freeform, but
21 often serves as the name of the world.
23 Currently the authentication and ban data is stored on a per-world basis. It
24 can be copied over from an old world to a newly created world.
27 |-- auth.txt ----- Authentication data
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
39 Contains authentication data, player per line.
40 <name>:<password hash>:<privilege1,...>
41 Format of password hash is <name><password> SHA1'd, in the base64 encoding.
44 - Player "celeron55", no password, privileges "interact" and "shout":
45 celeron55::interact,shout
46 - Player "Foo", password "bar", privilege "shout":
47 foo:iEPX+SQWIR3p67lj/0zigSWTKHg:shout
48 - Player "bar", no password, no privileges:
53 Simple global environment variables.
54 Example content (added indentation):
61 Banned IP addresses and usernames.
62 Example content (added indentation):
68 Simple global map variables.
69 Example content (added indentation):
70 seed = 7980462765762429666
76 See Map File Format below.
81 Filename can be anything.
82 See Player File Format below.
87 Example content (added indentation):
93 - Should be pretty self-explanatory.
94 - Note: position is in nodes * 10
96 Example content (added indentation):
100 position = (-5231.97,15,1961.41)
105 Item default:torch 13
106 Item default:pick_steel 1 50112
107 Item experimental:tnt
108 Item default:cobble 99
109 Item default:pick_stone 1 13104
110 Item default:shovel_steel 1 51838
113 Item default:coal_lump 3
114 Item default:cobble 99
115 Item default:leaves 22
116 Item default:gravel 52
117 Item default:axe_steel 1 2045
118 Item default:cobble 98
120 Item default:water_source 94
122 Item default:mossycobble
123 Item default:pick_steel 1 64428
124 Item animalmaterials:bone
125 Item default:sword_steel
127 Item default:sword_stone 1 10647
160 Minetest maps consist of MapBlocks, chunks of 16x16x16 nodes.
162 In addition to the bulk node data, MapBlocks stored on disk also contain
167 We need a bit of history in here. Initially Minetest stored maps in a
168 format called the "sectors" format. It was a directory/file structure like
170 sectors2/XXX/ZZZ/YYYY
171 For example, the MapBlock at (0,1,-2) was this file:
172 sectors2/000/ffd/0001
174 Eventually Minetest outgrow this directory structure, as filesystems were
175 struggling under the amount of files and directories.
177 Large servers seriously needed a new format, and thus the base of the
178 current format was invented, suggested by celeron55 and implemented by
181 SQLite3 was slammed in, and blocks files were directly inserted as blobs
182 in a single table, indexed by integer primary keys, oddly mangled from
185 Today we know that SQLite3 allows multiple primary keys (which would allow
186 storing coordinates separately), but the format has been kept unchanged for
187 that part. So, this is where it has come.
192 map.sqlite is an sqlite3 database, containg a single table, called
193 "blocks". It looks like this:
195 CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY,`data` BLOB);
199 "pos" is created from the three coordinates of a MapBlock using this
200 algorithm, defined here in Python:
202 def getBlockAsInteger(p):
203 return int64(p[2]*16777216 + p[1]*4096 + p[0])
212 It can be converted the other way by using this code:
214 def getIntegerAsBlock(i):
215 x = unsignedToSigned(i % 4096, 2048)
216 i = int((i - x) / 4096)
217 y = unsignedToSigned(i % 4096, 2048)
218 i = int((i - y) / 4096)
219 z = unsignedToSigned(i % 4096, 2048)
222 def unsignedToSigned(i, max_positive):
226 return i - 2*max_positive
230 The blob is the data that would have otherwise gone into the file.
232 See below for description.
234 MapBlock serialization format
235 ==============================
236 NOTE: Byte order is MSB first (big-endian).
237 NOTE: Zlib data is in such a format that Python's zlib at least can
241 - map format version number, this one is version 22
245 - 0x01: is_underground: Should be set to 0 if there will be no light
246 obstructions above the block. If/when sunlight of a block is updated
247 and there is no block above it, this value is checked for determining
248 whether sunlight comes from the top.
249 - 0x02: day_night_differs: Whether the lighting of the block is different
250 on day and night. Only blocks that have this bit set are updated when
251 day transforms to night.
252 - 0x04: lighting_expired: If true, lighting is invalid and should be
253 updated. If you can't calculate lighting in your generator properly,
254 you could try setting this 1 to everything and setting the uppermost
255 block in every sector as is_underground=0. I am quite sure it doesn't
256 work properly, though.
257 - 0x08: generated: True if the block has been generated. If false, block
258 is mostly filled with CONTENT_IGNORE and is likely to contain eg. parts
259 of trees of neighboring blocks.
262 - Number of bytes in the content (param0) fields of nodes
266 - Number of bytes used for parameters per node
269 zlib-compressed node data:
271 u8[4096]: param0 fields
272 u8[4096]: param1 fields
273 u8[4096]: param2 fields
274 - The location of a node in each of those arrays is (z*16*16 + y*16 + x).
276 zlib-compressed node metadata list
279 u16 count of metadata
281 u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
284 u8[content_size] (content of metadata)
286 u16 mapblockobject_count
288 - Should be removed in version 23 (TODO)
290 u8 static object version:
293 u16 static_object_count
295 foreach static_object_count:
296 u8 type (object type-id)
297 s32 pos_x_nodes * 10000
298 s32 pos_y_nodes * 10000
299 s32 pos_z_nodes * 10000
304 - Timestamp when last saved, as seconds from starting the game.
305 - 0xffffffff = invalid/unknown timestamp, nothing should be done with the time
306 difference when loaded
308 u8 name-id-mapping version
311 u16 num_name_id_mappings
313 foreach num_name_id_mappings
322 A node is composed of the u8 fields param0, param1 and param2.
324 The content id of a node is determined as so:
328 content_id = (param0<<4) + (param2>>4)
330 The purpose of param1 and param2 depend on the definition of the node.
334 The mapping maps node content ids to node names.
337 ---------------------
348 u8[len] inventory drawspec
349 u8 allow_text_input (bool)
350 u8 removal_disabled (bool)
351 u8 enforce_owner (bool)
369 17: Locked Chest metadata
376 Static objects are persistent freely moving objects in the world.
382 4: Oerkki (deprecated)
383 5: Firefly (deprecated)
384 6: MobV2 (deprecated)
401 s32 velocity.x * 10000
402 s32 velocity.y * 10000
403 s32 velocity.z * 10000
409 eg. 'default:pick_wood 21323'
410 eg. '"default:apple" 2'
412 - The wear value in tools is 0...65535
413 - There are also a number of older formats that you might stumble upon:
414 eg. 'node "default:dirt" 5'
415 eg. 'NodeItem default:dirt 5'
416 eg. 'ToolItem WPick 21323'
418 Inventory serialization format
419 -------------------------------
420 - The inventory serialization format is line-based
421 - The newline character used is "\n"
422 - The end condition of a serialized inventory is always "EndInventory\n"
423 - All the slots in a list must always be serialized.
425 Example (format does not include "---"):
429 Item default:sword_stone 1 10647
447 ==============================================
448 Minetest World Format used as of 2011-05 or so
449 ==============================================
451 Map data serialization format version 17.
453 0.3.1 does not use this format, but a more recent one. This exists here for
457 sectors/XXXXZZZZ or sectors2/XXX/ZZZ
458 XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates.
459 Under these, the block files are stored, called YYYY.
461 There also exists files map_meta.txt and chunk_meta, that are used by the
462 generator. If they are not found or invalid, the generator will currently
463 behave quite strangely.
465 The MapBlock file format (sectors2/XXX/ZZZ/YYYY):
466 -------------------------------------------------
468 NOTE: Byte order is MSB first.
471 - map format version number, this one is version 17
475 - 0x01: is_underground: Should be set to 0 if there will be no light
476 obstructions above the block. If/when sunlight of a block is updated and
477 there is no block above it, this value is checked for determining whether
478 sunlight comes from the top.
479 - 0x02: day_night_differs: Whether the lighting of the block is different on
480 day and night. Only blocks that have this bit set are updated when day
482 - 0x04: lighting_expired: If true, lighting is invalid and should be updated.
483 If you can't calculate lighting in your generator properly, you could try
484 setting this 1 to everything and setting the uppermost block in every
485 sector as is_underground=0. I am quite sure it doesn't work properly,
488 zlib-compressed map data:
490 u8[4096]: content types
491 u8[4096]: param1 values
492 u8[4096]: param2 values
494 zlib-compressed node metadata
497 u16 count of metadata
499 u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
502 u8[content_size] misc. stuff contained in the metadata
504 u16 mapblockobject_count
506 - if read != 0, just fail.
508 foreach mapblockobject_count:
509 - deprecated, should not be used. Length of this data can only be known by
510 properly parsing it. Just hope not to run into any of this.
512 u8 static object version:
515 u16 static_object_count
517 foreach static_object_count:
518 u8 type (object type-id)
526 - Timestamp when last saved, as seconds from starting the game.
527 - 0xffffffff = invalid/unknown timestamp, nothing will be done with the time
528 difference when loaded (recommended)
530 Node metadata format:
531 ---------------------
535 u8[string_len] string
543 Locking Chest metadata:
545 u8[string_len] string