1 =============================
2 Minetest World Format 22...25
3 =============================
5 This applies to a world format carrying the block serialization version
6 22...25, used at least in
7 - 0.4.dev-20120322 ... 0.4.dev-20120606 (22...23)
9 - 24 was never released as stable and existed for ~2 days
11 The block serialization version does not fully specify every aspect of this
12 format; if compliance with this format is to be checked, it needs to be
13 done by detecting if the files and data indeed follows it.
17 Data can, in theory, be contained in the flat file directory structure
18 described below in Version 17, but it is not officially supported. Also you
19 may stumble upon all kinds of oddities in not-so-recent formats.
23 Everything is contained in a directory, the name of which is freeform, but
24 often serves as the name of the world.
26 Currently the authentication and ban data is stored on a per-world basis.
27 It can be copied over from an old world to a newly created world.
30 |-- auth.txt ----- Authentication data
31 |-- env_meta.txt - Environment metadata
32 |-- ipban.txt ---- Banned ips/users
33 |-- map_meta.txt - Map metadata
34 |-- map.sqlite --- Map data
35 |-- players ------ Player directory
36 | |-- player1 -- Player file
37 | '-- Foo ------ Player file
38 `-- world.mt ----- World metadata
42 Contains authentication data, player per line.
43 <name>:<password hash>:<privilege1,...>
45 Legacy format (until 0.4.12) of password hash is <name><password> SHA1'd,
46 in the base64 encoding.
48 Format (since 0.4.13) of password hash is #1#<salt>#<verifier>, with the
49 parts inside <> encoded in the base64 encoding.
50 <verifier> is an RFC 2945 compatible SRP verifier,
51 of the given salt, password, and the player's name lowercased,
52 using the 2048-bit group specified in RFC 5054 and the SHA-256 hash function.
55 - Player "celeron55", no password, privileges "interact" and "shout":
56 celeron55::interact,shout
57 - Player "Foo", password "bar", privilege "shout", with a legacy password hash:
58 foo:iEPX+SQWIR3p67lj/0zigSWTKHg:shout
59 - Player "Foo", password "bar", privilege "shout", with a 0.4.13 pw hash:
60 foo:#1#hPpy4O3IAn1hsNK00A6wNw#Kpu6rj7McsrPCt4euTb5RA5ltF7wdcWGoYMcRngwDi11cZhPuuR9i5Bo7o6A877TgcEwoc//HNrj9EjR/CGjdyTFmNhiermZOADvd8eu32FYK1kf7RMC0rXWxCenYuOQCG4WF9mMGiyTPxC63VAjAMuc1nCZzmy6D9zt0SIKxOmteI75pAEAIee2hx4OkSXRIiU4Zrxo1Xf7QFxkMY4x77vgaPcvfmuzom0y/fU1EdSnZeopGPvzMpFx80ODFx1P34R52nmVl0W8h4GNo0k8ZiWtRCdrJxs8xIg7z5P1h3Th/BJ0lwexpdK8sQZWng8xaO5ElthNuhO8UQx1l6FgEA:shout
61 - Player "bar", no password, no privileges:
66 Simple global environment variables.
67 Example content (added indentation):
74 Banned IP addresses and usernames.
75 Example content (added indentation):
81 Simple global map variables.
82 Example content (added indentation):
83 seed = 7980462765762429666
89 See Map File Format below.
94 Filename can be anything.
95 See Player File Format below.
100 Example content (added indentation):
106 - Should be pretty self-explanatory.
107 - Note: position is in nodes * 10
109 Example content (added indentation):
113 position = (-5231.97,15,1961.41)
118 Item default:torch 13
119 Item default:pick_steel 1 50112
120 Item experimental:tnt
121 Item default:cobble 99
122 Item default:pick_stone 1 13104
123 Item default:shovel_steel 1 51838
126 Item default:coal_lump 3
127 Item default:cobble 99
128 Item default:leaves 22
129 Item default:gravel 52
130 Item default:axe_steel 1 2045
131 Item default:cobble 98
133 Item default:water_source 94
135 Item default:mossycobble
136 Item default:pick_steel 1 64428
137 Item animalmaterials:bone
138 Item default:sword_steel
140 Item default:sword_stone 1 10647
173 Minetest maps consist of MapBlocks, chunks of 16x16x16 nodes.
175 In addition to the bulk node data, MapBlocks stored on disk also contain
180 We need a bit of history in here. Initially Minetest stored maps in a
181 format called the "sectors" format. It was a directory/file structure like
183 sectors2/XXX/ZZZ/YYYY
184 For example, the MapBlock at (0,1,-2) was this file:
185 sectors2/000/ffd/0001
187 Eventually Minetest outgrow this directory structure, as filesystems were
188 struggling under the amount of files and directories.
190 Large servers seriously needed a new format, and thus the base of the
191 current format was invented, suggested by celeron55 and implemented by
194 SQLite3 was slammed in, and blocks files were directly inserted as blobs
195 in a single table, indexed by integer primary keys, oddly mangled from
198 Today we know that SQLite3 allows multiple primary keys (which would allow
199 storing coordinates separately), but the format has been kept unchanged for
200 that part. So, this is where it has come.
205 map.sqlite is an sqlite3 database, containing a single table, called
206 "blocks". It looks like this:
208 CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY,`data` BLOB);
212 "pos" is created from the three coordinates of a MapBlock using this
213 algorithm, defined here in Python:
215 def getBlockAsInteger(p):
216 return int64(p[2]*16777216 + p[1]*4096 + p[0])
225 It can be converted the other way by using this code:
227 def getIntegerAsBlock(i):
228 x = unsignedToSigned(i % 4096, 2048)
229 i = int((i - x) / 4096)
230 y = unsignedToSigned(i % 4096, 2048)
231 i = int((i - y) / 4096)
232 z = unsignedToSigned(i % 4096, 2048)
235 def unsignedToSigned(i, max_positive):
239 return i - 2*max_positive
243 The blob is the data that would have otherwise gone into the file.
245 See below for description.
247 MapBlock serialization format
248 ==============================
249 NOTE: Byte order is MSB first (big-endian).
250 NOTE: Zlib data is in such a format that Python's zlib at least can
254 - map format version number, see serialisation.h for the latest number
258 - 0x01: is_underground: Should be set to 0 if there will be no light
259 obstructions above the block. If/when sunlight of a block is updated
260 and there is no block above it, this value is checked for determining
261 whether sunlight comes from the top.
262 - 0x02: day_night_differs: Whether the lighting of the block is different
263 on day and night. Only blocks that have this bit set are updated when
264 day transforms to night.
265 - 0x04: lighting_expired: If true, lighting is invalid and should be
266 updated. If you can't calculate lighting in your generator properly,
267 you could try setting this 1 to everything and setting the uppermost
268 block in every sector as is_underground=0. I am quite sure it doesn't
269 work properly, though.
270 - 0x08: generated: True if the block has been generated. If false, block
271 is mostly filled with CONTENT_IGNORE and is likely to contain eg. parts
272 of trees of neighboring blocks.
275 - Number of bytes in the content (param0) fields of nodes
276 if map format version <= 23:
278 if map format version >= 24:
282 - Number of bytes used for parameters per node
285 zlib-compressed node data:
286 if content_width == 1:
288 u8[4096]: param0 fields
289 u8[4096]: param1 fields
290 u8[4096]: param2 fields
291 if content_width == 2:
293 u16[4096]: param0 fields
294 u8[4096]: param1 fields
295 u8[4096]: param2 fields
296 - The location of a node in each of those arrays is (z*16*16 + y*16 + x).
298 zlib-compressed node metadata list
300 if map format version <= 22:
302 u16 count of metadata
304 u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
307 u8[content_size] content of metadata. Format depends on type_id, see below.
308 if map format version >= 23:
309 u8 version (=1) -- Note the type is u8, while for map format version <= 22 it's u16
310 u16 count of metadata
312 u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
322 if map format version == 23:
323 u8 unused version (always 0)
324 if map format version == 24: (NOTE: Not released as stable)
326 if nodetimer_version == 0:
328 if nodetimer_version == 1:
330 foreach num_of_timers:
331 u16 timer position (z*16*16 + y*16 + x)
334 if map format version >= 25:
335 -- Nothing right here, node timers are serialized later
337 u8 static object version:
340 u16 static_object_count
342 foreach static_object_count:
343 u8 type (object type-id)
344 s32 pos_x_nodes * 10000
345 s32 pos_y_nodes * 10000
346 s32 pos_z_nodes * 10000
351 - Timestamp when last saved, as seconds from starting the game.
352 - 0xffffffff = invalid/unknown timestamp, nothing should be done with the time
353 difference when loaded
355 u8 name-id-mapping version
358 u16 num_name_id_mappings
360 foreach num_name_id_mappings
366 if map format version == 25:
367 u8 length of the data of a single timer (always 2+4+4=10)
369 foreach num_of_timers:
370 u16 timer position (z*16*16 + y*16 + x)
378 A node is composed of the u8 fields param0, param1 and param2.
380 if map format version <= 23:
381 The content id of a node is determined as so:
385 content_id = (param0<<4) + (param2>>4)
386 if map format version >= 24:
387 The content id of a node is param0.
389 The purpose of param1 and param2 depend on the definition of the node.
393 The mapping maps node content ids to node names.
395 Node metadata format for map format versions <= 22
396 ---------------------------------------------------
397 The node metadata are serialized depending on the type_id field.
408 u8[len] inventory drawspec
409 u8 allow_text_input (bool)
410 u8 removal_disabled (bool)
411 u8 enforce_owner (bool)
429 17: Locked Chest metadata
436 Static objects are persistent freely moving objects in the world.
442 4: Oerkki (deprecated)
443 5: Firefly (deprecated)
444 6: MobV2 (deprecated)
461 s32 velocity.x * 10000
462 s32 velocity.y * 10000
463 s32 velocity.z * 10000
469 eg. 'default:pick_wood 21323'
470 eg. '"default:apple" 2'
472 - The wear value in tools is 0...65535
473 - There are also a number of older formats that you might stumble upon:
474 eg. 'node "default:dirt" 5'
475 eg. 'NodeItem default:dirt 5'
476 eg. 'ToolItem WPick 21323'
478 Inventory serialization format
479 -------------------------------
480 - The inventory serialization format is line-based
481 - The newline character used is "\n"
482 - The end condition of a serialized inventory is always "EndInventory\n"
483 - All the slots in a list must always be serialized.
485 Example (format does not include "---"):
489 Item default:sword_stone 1 10647
507 ==============================================
508 Minetest World Format used as of 2011-05 or so
509 ==============================================
511 Map data serialization format version 17.
513 0.3.1 does not use this format, but a more recent one. This exists here for
517 sectors/XXXXZZZZ or sectors2/XXX/ZZZ
518 XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates.
519 Under these, the block files are stored, called YYYY.
521 There also exists files map_meta.txt and chunk_meta, that are used by the
522 generator. If they are not found or invalid, the generator will currently
523 behave quite strangely.
525 The MapBlock file format (sectors2/XXX/ZZZ/YYYY):
526 -------------------------------------------------
528 NOTE: Byte order is MSB first.
531 - map format version number, this one is version 17
535 - 0x01: is_underground: Should be set to 0 if there will be no light
536 obstructions above the block. If/when sunlight of a block is updated and
537 there is no block above it, this value is checked for determining whether
538 sunlight comes from the top.
539 - 0x02: day_night_differs: Whether the lighting of the block is different on
540 day and night. Only blocks that have this bit set are updated when day
542 - 0x04: lighting_expired: If true, lighting is invalid and should be updated.
543 If you can't calculate lighting in your generator properly, you could try
544 setting this 1 to everything and setting the uppermost block in every
545 sector as is_underground=0. I am quite sure it doesn't work properly,
548 zlib-compressed map data:
550 u8[4096]: content types
551 u8[4096]: param1 values
552 u8[4096]: param2 values
554 zlib-compressed node metadata
557 u16 count of metadata
559 u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
562 u8[content_size] misc. stuff contained in the metadata
564 u16 mapblockobject_count
566 - if read != 0, just fail.
568 foreach mapblockobject_count:
569 - deprecated, should not be used. Length of this data can only be known by
570 properly parsing it. Just hope not to run into any of this.
572 u8 static object version:
575 u16 static_object_count
577 foreach static_object_count:
578 u8 type (object type-id)
586 - Timestamp when last saved, as seconds from starting the game.
587 - 0xffffffff = invalid/unknown timestamp, nothing will be done with the time
588 difference when loaded (recommended)
590 Node metadata format:
591 ---------------------
595 u8[string_len] string
603 Locking Chest metadata:
605 u8[string_len] string