1 =============================
2 Minetest World Format 22...27
3 =============================
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)
9 - 24 was never released as stable and existed for ~2 days
10 - 27 was added in 0.4.15-dev
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.
18 Data can, in theory, be contained in the flat file directory structure
19 described below in Version 17, but it is not officially supported. Also you
20 may stumble upon all kinds of oddities in not-so-recent formats.
24 Everything is contained in a directory, the name of which is freeform, but
25 often serves as the name of the world.
27 Currently the authentication and ban data is stored on a per-world basis.
28 It can be copied over from an old world to a newly created world.
31 |-- auth.txt ----- Authentication data
32 |-- env_meta.txt - Environment metadata
33 |-- ipban.txt ---- Banned ips/users
34 |-- map_meta.txt - Map metadata
35 |-- map.sqlite --- Map data
36 |-- players ------ Player directory
37 | |-- player1 -- Player file
38 | '-- Foo ------ Player file
39 `-- world.mt ----- World metadata
43 Contains authentication data, player per line.
44 <name>:<password hash>:<privilege1,...>
46 Legacy format (until 0.4.12) of password hash is <name><password> SHA1'd,
47 in the base64 encoding.
49 Format (since 0.4.13) of password hash is #1#<salt>#<verifier>, with the
50 parts inside <> encoded in the base64 encoding.
51 <verifier> is an RFC 2945 compatible SRP verifier,
52 of the given salt, password, and the player's name lowercased,
53 using the 2048-bit group specified in RFC 5054 and the SHA-256 hash function.
56 - Player "celeron55", no password, privileges "interact" and "shout":
57 celeron55::interact,shout
58 - Player "Foo", password "bar", privilege "shout", with a legacy password hash:
59 foo:iEPX+SQWIR3p67lj/0zigSWTKHg:shout
60 - Player "Foo", password "bar", privilege "shout", with a 0.4.13 pw hash:
61 foo:#1#hPpy4O3IAn1hsNK00A6wNw#Kpu6rj7McsrPCt4euTb5RA5ltF7wdcWGoYMcRngwDi11cZhPuuR9i5Bo7o6A877TgcEwoc//HNrj9EjR/CGjdyTFmNhiermZOADvd8eu32FYK1kf7RMC0rXWxCenYuOQCG4WF9mMGiyTPxC63VAjAMuc1nCZzmy6D9zt0SIKxOmteI75pAEAIee2hx4OkSXRIiU4Zrxo1Xf7QFxkMY4x77vgaPcvfmuzom0y/fU1EdSnZeopGPvzMpFx80ODFx1P34R52nmVl0W8h4GNo0k8ZiWtRCdrJxs8xIg7z5P1h3Th/BJ0lwexpdK8sQZWng8xaO5ElthNuhO8UQx1l6FgEA:shout
62 - Player "bar", no password, no privileges:
67 Simple global environment variables.
68 Example content (added indentation):
75 Banned IP addresses and usernames.
76 Example content (added indentation):
82 Simple global map variables.
83 Example content (added indentation):
84 seed = 7980462765762429666
90 See Map File Format below.
95 Filename can be anything.
96 See Player File Format below.
101 Example content (added indentation):
107 - Should be pretty self-explanatory.
108 - Note: position is in nodes * 10
110 Example content (added indentation):
114 position = (-5231.97,15,1961.41)
119 Item default:torch 13
120 Item default:pick_steel 1 50112
121 Item experimental:tnt
122 Item default:cobble 99
123 Item default:pick_stone 1 13104
124 Item default:shovel_steel 1 51838
127 Item default:coal_lump 3
128 Item default:cobble 99
129 Item default:leaves 22
130 Item default:gravel 52
131 Item default:axe_steel 1 2045
132 Item default:cobble 98
134 Item default:water_source 94
136 Item default:mossycobble
137 Item default:pick_steel 1 64428
138 Item animalmaterials:bone
139 Item default:sword_steel
141 Item default:sword_stone 1 10647
174 Minetest maps consist of MapBlocks, chunks of 16x16x16 nodes.
176 In addition to the bulk node data, MapBlocks stored on disk also contain
181 We need a bit of history in here. Initially Minetest stored maps in a
182 format called the "sectors" format. It was a directory/file structure like
184 sectors2/XXX/ZZZ/YYYY
185 For example, the MapBlock at (0,1,-2) was this file:
186 sectors2/000/ffd/0001
188 Eventually Minetest outgrow this directory structure, as filesystems were
189 struggling under the amount of files and directories.
191 Large servers seriously needed a new format, and thus the base of the
192 current format was invented, suggested by celeron55 and implemented by
195 SQLite3 was slammed in, and blocks files were directly inserted as blobs
196 in a single table, indexed by integer primary keys, oddly mangled from
199 Today we know that SQLite3 allows multiple primary keys (which would allow
200 storing coordinates separately), but the format has been kept unchanged for
201 that part. So, this is where it has come.
206 map.sqlite is an sqlite3 database, containing a single table, called
207 "blocks". It looks like this:
209 CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY,`data` BLOB);
213 "pos" is created from the three coordinates of a MapBlock using this
214 algorithm, defined here in Python:
216 def getBlockAsInteger(p):
217 return int64(p[2]*16777216 + p[1]*4096 + p[0])
226 It can be converted the other way by using this code:
228 def getIntegerAsBlock(i):
229 x = unsignedToSigned(i % 4096, 2048)
230 i = int((i - x) / 4096)
231 y = unsignedToSigned(i % 4096, 2048)
232 i = int((i - y) / 4096)
233 z = unsignedToSigned(i % 4096, 2048)
236 def unsignedToSigned(i, max_positive):
240 return i - 2*max_positive
244 The blob is the data that would have otherwise gone into the file.
246 See below for description.
248 MapBlock serialization format
249 ==============================
250 NOTE: Byte order is MSB first (big-endian).
251 NOTE: Zlib data is in such a format that Python's zlib at least can
255 - map format version number, see serialisation.h for the latest number
259 - 0x01: is_underground: Should be set to 0 if there will be no light
260 obstructions above the block. If/when sunlight of a block is updated
261 and there is no block above it, this value is checked for determining
262 whether sunlight comes from the top.
263 - 0x02: day_night_differs: Whether the lighting of the block is different
264 on day and night. Only blocks that have this bit set are updated when
265 day transforms to night.
266 - 0x04: lighting_expired: Not used in version 27 and above. If true,
267 lighting is invalid and should be updated. If you can't calculate
268 lighting in your generator properly, you could try setting this 1 to
269 everything and setting the uppermost block in every sector as
270 is_underground=0. I am quite sure it doesn't work properly, though.
271 - 0x08: generated: True if the block has been generated. If false, block
272 is mostly filled with CONTENT_IGNORE and is likely to contain eg. parts
273 of trees of neighboring blocks.
275 u16 lighting_complete
276 - Added in version 27.
277 - This contains 12 flags, each of them corresponds to a direction.
278 - Indicates if the light is correct at the sides of a map block.
279 Lighting may not be correct if the light changed, but a neighbor
280 block was not loaded at that time.
281 If these flags are false, Minetest will automatically recompute light
282 when both this block and its required neighbor are loaded.
284 nothing, nothing, nothing, nothing,
285 night X-, night Y-, night Z-, night Z+, night Y+, night X+,
286 day X-, day Y-, day Z-, day Z+, day Y+, day X+.
287 Where 'day' is for the day light bank, 'night' is for the night
289 The 'nothing' bits should be always set, as they will be used
290 to indicate if direct sunlight spreading is finished.
291 - Example: if the block at (0, 0, 0) has
292 lighting_complete = 0b1111111111111110,
293 then Minetest will correct lighting in the day light bank when
294 the block at (1, 0, 0) is also loaded.
297 - Number of bytes in the content (param0) fields of nodes
298 if map format version <= 23:
300 if map format version >= 24:
304 - Number of bytes used for parameters per node
307 zlib-compressed node data:
308 if content_width == 1:
310 u8[4096]: param0 fields
311 u8[4096]: param1 fields
312 u8[4096]: param2 fields
313 if content_width == 2:
315 u16[4096]: param0 fields
316 u8[4096]: param1 fields
317 u8[4096]: param2 fields
318 - The location of a node in each of those arrays is (z*16*16 + y*16 + x).
320 zlib-compressed node metadata list
322 if map format version <= 22:
324 u16 count of metadata
326 u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
329 u8[content_size] content of metadata. Format depends on type_id, see below.
330 if map format version >= 23:
331 u8 version (=1) -- Note the type is u8, while for map format version <= 22 it's u16
332 u16 count of metadata
334 u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
344 if map format version == 23:
345 u8 unused version (always 0)
346 if map format version == 24: (NOTE: Not released as stable)
348 if nodetimer_version == 0:
350 if nodetimer_version == 1:
352 foreach num_of_timers:
353 u16 timer position (z*16*16 + y*16 + x)
356 if map format version >= 25:
357 -- Nothing right here, node timers are serialized later
359 u8 static object version:
362 u16 static_object_count
364 foreach static_object_count:
365 u8 type (object type-id)
366 s32 pos_x_nodes * 10000
367 s32 pos_y_nodes * 10000
368 s32 pos_z_nodes * 10000
373 - Timestamp when last saved, as seconds from starting the game.
374 - 0xffffffff = invalid/unknown timestamp, nothing should be done with the time
375 difference when loaded
377 u8 name-id-mapping version
380 u16 num_name_id_mappings
382 foreach num_name_id_mappings
388 if map format version == 25:
389 u8 length of the data of a single timer (always 2+4+4=10)
391 foreach num_of_timers:
392 u16 timer position (z*16*16 + y*16 + x)
400 A node is composed of the u8 fields param0, param1 and param2.
402 if map format version <= 23:
403 The content id of a node is determined as so:
407 content_id = (param0<<4) + (param2>>4)
408 if map format version >= 24:
409 The content id of a node is param0.
411 The purpose of param1 and param2 depend on the definition of the node.
415 The mapping maps node content ids to node names.
417 Node metadata format for map format versions <= 22
418 ---------------------------------------------------
419 The node metadata are serialized depending on the type_id field.
430 u8[len] inventory drawspec
431 u8 allow_text_input (bool)
432 u8 removal_disabled (bool)
433 u8 enforce_owner (bool)
451 17: Locked Chest metadata
458 Static objects are persistent freely moving objects in the world.
464 4: Oerkki (deprecated)
465 5: Firefly (deprecated)
466 6: MobV2 (deprecated)
483 s32 velocity.x * 10000
484 s32 velocity.y * 10000
485 s32 velocity.z * 10000
491 eg. 'default:pick_wood 21323'
492 eg. '"default:apple" 2'
494 - The wear value in tools is 0...65535
495 - There are also a number of older formats that you might stumble upon:
496 eg. 'node "default:dirt" 5'
497 eg. 'NodeItem default:dirt 5'
498 eg. 'ToolItem WPick 21323'
500 Inventory serialization format
501 -------------------------------
502 - The inventory serialization format is line-based
503 - The newline character used is "\n"
504 - The end condition of a serialized inventory is always "EndInventory\n"
505 - All the slots in a list must always be serialized.
507 Example (format does not include "---"):
511 Item default:sword_stone 1 10647
529 ==============================================
530 Minetest World Format used as of 2011-05 or so
531 ==============================================
533 Map data serialization format version 17.
535 0.3.1 does not use this format, but a more recent one. This exists here for
539 sectors/XXXXZZZZ or sectors2/XXX/ZZZ
540 XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates.
541 Under these, the block files are stored, called YYYY.
543 There also exists files map_meta.txt and chunk_meta, that are used by the
544 generator. If they are not found or invalid, the generator will currently
545 behave quite strangely.
547 The MapBlock file format (sectors2/XXX/ZZZ/YYYY):
548 -------------------------------------------------
550 NOTE: Byte order is MSB first.
553 - map format version number, this one is version 17
557 - 0x01: is_underground: Should be set to 0 if there will be no light
558 obstructions above the block. If/when sunlight of a block is updated and
559 there is no block above it, this value is checked for determining whether
560 sunlight comes from the top.
561 - 0x02: day_night_differs: Whether the lighting of the block is different on
562 day and night. Only blocks that have this bit set are updated when day
564 - 0x04: lighting_expired: If true, lighting is invalid and should be updated.
565 If you can't calculate lighting in your generator properly, you could try
566 setting this 1 to everything and setting the uppermost block in every
567 sector as is_underground=0. I am quite sure it doesn't work properly,
570 zlib-compressed map data:
572 u8[4096]: content types
573 u8[4096]: param1 values
574 u8[4096]: param2 values
576 zlib-compressed node metadata
579 u16 count of metadata
581 u16 position (= p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
584 u8[content_size] misc. stuff contained in the metadata
586 u16 mapblockobject_count
588 - if read != 0, just fail.
590 foreach mapblockobject_count:
591 - deprecated, should not be used. Length of this data can only be known by
592 properly parsing it. Just hope not to run into any of this.
594 u8 static object version:
597 u16 static_object_count
599 foreach static_object_count:
600 u8 type (object type-id)
608 - Timestamp when last saved, as seconds from starting the game.
609 - 0xffffffff = invalid/unknown timestamp, nothing will be done with the time
610 difference when loaded (recommended)
612 Node metadata format:
613 ---------------------
617 u8[string_len] string
625 Locking Chest metadata:
627 u8[string_len] string