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,...>
44 Format of password hash is <name><password> SHA1'd, in the base64 encoding.
47 - Player "celeron55", no password, privileges "interact" and "shout":
48 celeron55::interact,shout
49 - Player "Foo", password "bar", privilege "shout":
50 foo:iEPX+SQWIR3p67lj/0zigSWTKHg:shout
51 - Player "bar", no password, no privileges:
56 Simple global environment variables.
57 Example content (added indentation):
64 Banned IP addresses and usernames.
65 Example content (added indentation):
71 Simple global map variables.
72 Example content (added indentation):
73 seed = 7980462765762429666
79 See Map File Format below.
84 Filename can be anything.
85 See Player File Format below.
90 Example content (added indentation):
96 - Should be pretty self-explanatory.
97 - Note: position is in nodes * 10
99 Example content (added indentation):
103 position = (-5231.97,15,1961.41)
108 Item default:torch 13
109 Item default:pick_steel 1 50112
110 Item experimental:tnt
111 Item default:cobble 99
112 Item default:pick_stone 1 13104
113 Item default:shovel_steel 1 51838
116 Item default:coal_lump 3
117 Item default:cobble 99
118 Item default:leaves 22
119 Item default:gravel 52
120 Item default:axe_steel 1 2045
121 Item default:cobble 98
123 Item default:water_source 94
125 Item default:mossycobble
126 Item default:pick_steel 1 64428
127 Item animalmaterials:bone
128 Item default:sword_steel
130 Item default:sword_stone 1 10647
163 Minetest maps consist of MapBlocks, chunks of 16x16x16 nodes.
165 In addition to the bulk node data, MapBlocks stored on disk also contain
170 We need a bit of history in here. Initially Minetest stored maps in a
171 format called the "sectors" format. It was a directory/file structure like
173 sectors2/XXX/ZZZ/YYYY
174 For example, the MapBlock at (0,1,-2) was this file:
175 sectors2/000/ffd/0001
177 Eventually Minetest outgrow this directory structure, as filesystems were
178 struggling under the amount of files and directories.
180 Large servers seriously needed a new format, and thus the base of the
181 current format was invented, suggested by celeron55 and implemented by
184 SQLite3 was slammed in, and blocks files were directly inserted as blobs
185 in a single table, indexed by integer primary keys, oddly mangled from
188 Today we know that SQLite3 allows multiple primary keys (which would allow
189 storing coordinates separately), but the format has been kept unchanged for
190 that part. So, this is where it has come.
195 map.sqlite is an sqlite3 database, containg a single table, called
196 "blocks". It looks like this:
198 CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY,`data` BLOB);
202 "pos" is created from the three coordinates of a MapBlock using this
203 algorithm, defined here in Python:
205 def getBlockAsInteger(p):
206 return int64(p[2]*16777216 + p[1]*4096 + p[0])
215 It can be converted the other way by using this code:
217 def getIntegerAsBlock(i):
218 x = unsignedToSigned(i % 4096, 2048)
219 i = int((i - x) / 4096)
220 y = unsignedToSigned(i % 4096, 2048)
221 i = int((i - y) / 4096)
222 z = unsignedToSigned(i % 4096, 2048)
225 def unsignedToSigned(i, max_positive):
229 return i - 2*max_positive
233 The blob is the data that would have otherwise gone into the file.
235 See below for description.
237 MapBlock serialization format
238 ==============================
239 NOTE: Byte order is MSB first (big-endian).
240 NOTE: Zlib data is in such a format that Python's zlib at least can
244 - map format version number, this one is version 22
248 - 0x01: is_underground: Should be set to 0 if there will be no light
249 obstructions above the block. If/when sunlight of a block is updated
250 and there is no block above it, this value is checked for determining
251 whether sunlight comes from the top.
252 - 0x02: day_night_differs: Whether the lighting of the block is different
253 on day and night. Only blocks that have this bit set are updated when
254 day transforms to night.
255 - 0x04: lighting_expired: If true, lighting is invalid and should be
256 updated. If you can't calculate lighting in your generator properly,
257 you could try setting this 1 to everything and setting the uppermost
258 block in every sector as is_underground=0. I am quite sure it doesn't
259 work properly, though.
260 - 0x08: generated: True if the block has been generated. If false, block
261 is mostly filled with CONTENT_IGNORE and is likely to contain eg. parts
262 of trees of neighboring blocks.
265 - Number of bytes in the content (param0) fields of nodes
266 if map format version <= 23:
268 if map format version >= 24:
272 - Number of bytes used for parameters per node
275 zlib-compressed node data:
276 if content_width == 1:
278 u8[4096]: param0 fields
279 u8[4096]: param1 fields
280 u8[4096]: param2 fields
281 if content_width == 2:
283 u16[4096]: param0 fields
284 u8[4096]: param1 fields
285 u8[4096]: param2 fields
286 - The location of a node in each of those arrays is (z*16*16 + y*16 + x).
288 zlib-compressed node metadata list
291 u16 count of metadata
293 u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
296 u8[content_size] (content of metadata)
299 if map format version == 23:
300 u8 unused version (always 0)
301 if map format version == 24: (NOTE: Not released as stable)
303 if nodetimer_version == 0:
305 if nodetimer_version == 1:
307 foreach num_of_timers:
308 u16 timer position (z*16*16 + y*16 + x)
312 u8 static object version:
315 u16 static_object_count
317 foreach static_object_count:
318 u8 type (object type-id)
319 s32 pos_x_nodes * 10000
320 s32 pos_y_nodes * 10000
321 s32 pos_z_nodes * 10000
326 - Timestamp when last saved, as seconds from starting the game.
327 - 0xffffffff = invalid/unknown timestamp, nothing should be done with the time
328 difference when loaded
330 u8 name-id-mapping version
333 u16 num_name_id_mappings
335 foreach num_name_id_mappings
341 if map format version == 25:
342 u8 length of the data of a single timer (always 2+4+4=10)
344 foreach num_of_timers:
345 u16 timer position (z*16*16 + y*16 + x)
353 A node is composed of the u8 fields param0, param1 and param2.
355 if map format version <= 23:
356 The content id of a node is determined as so:
360 content_id = (param0<<4) + (param2>>4)
361 if map format version >= 24:
362 The content id of a node is param0.
364 The purpose of param1 and param2 depend on the definition of the node.
368 The mapping maps node content ids to node names.
371 ---------------------
382 u8[len] inventory drawspec
383 u8 allow_text_input (bool)
384 u8 removal_disabled (bool)
385 u8 enforce_owner (bool)
403 17: Locked Chest metadata
410 Static objects are persistent freely moving objects in the world.
416 4: Oerkki (deprecated)
417 5: Firefly (deprecated)
418 6: MobV2 (deprecated)
435 s32 velocity.x * 10000
436 s32 velocity.y * 10000
437 s32 velocity.z * 10000
443 eg. 'default:pick_wood 21323'
444 eg. '"default:apple" 2'
446 - The wear value in tools is 0...65535
447 - There are also a number of older formats that you might stumble upon:
448 eg. 'node "default:dirt" 5'
449 eg. 'NodeItem default:dirt 5'
450 eg. 'ToolItem WPick 21323'
452 Inventory serialization format
453 -------------------------------
454 - The inventory serialization format is line-based
455 - The newline character used is "\n"
456 - The end condition of a serialized inventory is always "EndInventory\n"
457 - All the slots in a list must always be serialized.
459 Example (format does not include "---"):
463 Item default:sword_stone 1 10647
481 ==============================================
482 Minetest World Format used as of 2011-05 or so
483 ==============================================
485 Map data serialization format version 17.
487 0.3.1 does not use this format, but a more recent one. This exists here for
491 sectors/XXXXZZZZ or sectors2/XXX/ZZZ
492 XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates.
493 Under these, the block files are stored, called YYYY.
495 There also exists files map_meta.txt and chunk_meta, that are used by the
496 generator. If they are not found or invalid, the generator will currently
497 behave quite strangely.
499 The MapBlock file format (sectors2/XXX/ZZZ/YYYY):
500 -------------------------------------------------
502 NOTE: Byte order is MSB first.
505 - map format version number, this one is version 17
509 - 0x01: is_underground: Should be set to 0 if there will be no light
510 obstructions above the block. If/when sunlight of a block is updated and
511 there is no block above it, this value is checked for determining whether
512 sunlight comes from the top.
513 - 0x02: day_night_differs: Whether the lighting of the block is different on
514 day and night. Only blocks that have this bit set are updated when day
516 - 0x04: lighting_expired: If true, lighting is invalid and should be updated.
517 If you can't calculate lighting in your generator properly, you could try
518 setting this 1 to everything and setting the uppermost block in every
519 sector as is_underground=0. I am quite sure it doesn't work properly,
522 zlib-compressed map data:
524 u8[4096]: content types
525 u8[4096]: param1 values
526 u8[4096]: param2 values
528 zlib-compressed node metadata
531 u16 count of metadata
533 u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
536 u8[content_size] misc. stuff contained in the metadata
538 u16 mapblockobject_count
540 - if read != 0, just fail.
542 foreach mapblockobject_count:
543 - deprecated, should not be used. Length of this data can only be known by
544 properly parsing it. Just hope not to run into any of this.
546 u8 static object version:
549 u16 static_object_count
551 foreach static_object_count:
552 u8 type (object type-id)
560 - Timestamp when last saved, as seconds from starting the game.
561 - 0xffffffff = invalid/unknown timestamp, nothing will be done with the time
562 difference when loaded (recommended)
564 Node metadata format:
565 ---------------------
569 u8[string_len] string
577 Locking Chest metadata:
579 u8[string_len] string