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 Everything is contained in a directory, the name of which is freeform, but
19 often serves as the name of the world.
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.
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
38 Contains authentication data, player per line.
39 <name>:<password hash>:<privilege1,...>
41 Legacy format (until 0.4.12) of password hash is <name><password> SHA1'd,
42 in the base64 encoding.
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.
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:
62 Contains authentification data as an SQLite database. This replaces auth.txt
63 above when auth_backend is set to "sqlite3" in world.mt .
65 This database contains two tables "auth" and "user_privileges":
68 `id` INTEGER PRIMARY KEY AUTOINCREMENT,
69 `name` VARCHAR(32) UNIQUE,
70 `password` VARCHAR(512),
73 CREATE TABLE `user_privileges` (
75 `privilege` VARCHAR(32),
76 PRIMARY KEY (id, privilege)
77 CONSTRAINT fk_id FOREIGN KEY (id) REFERENCES auth (id) ON DELETE CASCADE
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.
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".
90 Simple global environment variables.
91 Example content (added indentation):
98 Banned IP addresses and usernames.
99 Example content (added indentation):
105 Simple global map variables.
106 Example content (added indentation):
107 seed = 7980462765762429666
113 See Map File Format below.
118 Filename can be anything.
119 See Player File Format below.
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
138 - Should be pretty self-explanatory.
139 - Note: position is in nodes * 10
141 Example content (added indentation):
145 position = (-5231.97,15,1961.41)
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
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
165 Item default:water_source 94
167 Item default:mossycobble
168 Item default:pick_steel 1 64428
169 Item animalmaterials:bone
170 Item default:sword_steel
172 Item default:sword_stone 1 10647
205 Minetest maps consist of MapBlocks, chunks of 16x16x16 nodes.
207 In addition to the bulk node data, MapBlocks stored on disk also contain
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
215 sectors2/XXX/ZZZ/YYYY
216 For example, the MapBlock at (0,1,-2) was this file:
217 sectors2/000/ffd/0001
219 Eventually Minetest outgrow this directory structure, as filesystems were
220 struggling under the amount of files and directories.
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
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
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.
237 map.sqlite is an sqlite3 database, containing a single table, called
238 "blocks". It looks like this:
240 CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY,`data` BLOB);
244 "pos" is created from the three coordinates of a MapBlock using this
245 algorithm, defined here in Python:
247 def getBlockAsInteger(p):
248 return int64(p[2]*16777216 + p[1]*4096 + p[0])
257 It can be converted the other way by using this code:
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)
267 def unsignedToSigned(i, max_positive):
271 return i - 2*max_positive
275 The blob is the data that would have otherwise gone into the file.
277 See below for description.
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
286 - map format version number, see serialisation.h for the latest number
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.
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.
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
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.
328 - Number of bytes in the content (param0) fields of nodes
329 if map format version <= 23:
331 if map format version >= 24:
335 - Number of bytes used for parameters per node
338 zlib-compressed node data:
339 if content_width == 1:
341 u8[4096]: param0 fields
342 u8[4096]: param1 fields
343 u8[4096]: param2 fields
344 if content_width == 2:
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).
351 zlib-compressed node metadata list
353 if map format version <= 22:
355 u16 count of metadata
357 u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
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
367 u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
374 u8 is_private -- only for version >= 2. 0 = not private, 1 = private
378 if map format version == 23:
379 u8 unused version (always 0)
380 if map format version == 24: (NOTE: Not released as stable)
382 if nodetimer_version == 0:
384 if nodetimer_version == 1:
386 foreach num_of_timers:
387 u16 timer position (z*16*16 + y*16 + x)
390 if map format version >= 25:
391 -- Nothing right here, node timers are serialized later
393 u8 static object version:
396 u16 static_object_count
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
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
411 u8 name-id-mapping version
414 u16 num_name_id_mappings
416 foreach num_name_id_mappings
422 if map format version == 25:
423 u8 length of the data of a single timer (always 2+4+4=10)
425 foreach num_of_timers:
426 u16 timer position (z*16*16 + y*16 + x)
434 A node is composed of the u8 fields param0, param1 and param2.
436 if map format version <= 23:
437 The content id of a node is determined as so:
441 content_id = (param0<<4) + (param2>>4)
442 if map format version >= 24:
443 The content id of a node is param0.
445 The purpose of param1 and param2 depend on the definition of the node.
449 The mapping maps node content ids to node names.
451 Node metadata format for map format versions <= 22
452 ---------------------------------------------------
453 The node metadata are serialized depending on the type_id field.
464 u8[len] inventory drawspec
465 u8 allow_text_input (bool)
466 u8 removal_disabled (bool)
467 u8 enforce_owner (bool)
485 17: Locked Chest metadata
492 Static objects are persistent freely moving objects in the world.
499 5: Firefly (obsolete)
510 u8 compatibility_byte (always 1)
516 s32 velocity.x * 10000
517 s32 velocity.y * 10000
518 s32 velocity.z * 10000
520 if PROTOCOL_VERSION >= 37:
528 eg. 'default:pick_wood 21323'
529 eg. '"default:apple" 2'
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'
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.
544 Example (format does not include "---"):
548 Item default:sword_stone 1 10647