This applies to a world format carrying the block serialization version 22...27, used at least in
0.4.dev-20120322
... 0.4.dev-20120606
(22...23)0.4.0
(23)0.4.15-dev
5.5.0-dev
The block serialization version does not fully specify every aspect of this format; if compliance with this format is to be checked, it needs to be done by detecting if the files and data indeed follows it.
Everything is contained in a directory, the name of which is freeform, but often serves as the name of the world.
Currently, the authentication and ban data is stored on a per-world basis. It can be copied over from an old world to a newly created world.
World
├── auth.txt ───── Authentication data
├── auth.sqlite ── Authentication data (SQLite alternative)
├── env_meta.txt ─ Environment metadata
├── ipban.txt ──── Banned IPs/users
├── map_meta.txt ─ Map metadata
├── map.sqlite ─── Map data
├── players ────── Player directory
│ │── player1 ── Player file
│ └── Foo ────── Player file
└── world.mt ───── World metadata
Contains authentication data, one player per line.
<name>:<password hash>:<privilege1,...>
Legacy format (until 0.4.12) of password hash is <name><password>
SHA1'd,
in base64.
Format (since 0.4.13) of password hash is #1#<salt>#<verifier>
, with the
parts inside <>
encoded in base64.
<verifier>
is an RFC 2945 compatible SRP verifier,
of the given salt, password, and the player's name lowercased,
using the 2048-bit group specified in RFC 5054 and the SHA-256 hash function.
Example lines:
Player "celeron55", no password, privileges "interact" and "shout":
celeron55::interact,shout
Player "Foo", password "bar", privilege "shout", with a legacy password hash:
foo:iEPX+SQWIR3p67lj/0zigSWTKHg:shout
Player "Foo", password "bar", privilege "shout", with a 0.4.13 password hash:
foo:#1#hPpy4O3IAn1hsNK00A6wNw#Kpu6rj7McsrPCt4euTb5RA5ltF7wdcWGoYMcRngwDi11cZhPuuR9i5Bo7o6A877TgcEwoc//HNrj9EjR/CGjdyTFmNhiermZOADvd8eu32FYK1kf7RMC0rXWxCenYuOQCG4WF9mMGiyTPxC63VAjAMuc1nCZzmy6D9zt0SIKxOmteI75pAEAIee2hx4OkSXRIiU4Zrxo1Xf7QFxkMY4x77vgaPcvfmuzom0y/fU1EdSnZeopGPvzMpFx80ODFx1P34R52nmVl0W8h4GNo0k8ZiWtRCdrJxs8xIg7z5P1h3Th/BJ0lwexpdK8sQZWng8xaO5ElthNuhO8UQx1l6FgEA:shout
Player "bar", no password, no privileges:
bar::
Contains authentication data as an SQLite database. This replaces auth.txt
above when auth_backend
is set to sqlite3
in world.mt.
This database contains two tables: auth
and user_privileges
:
CREATE TABLE `auth` (
`id` INTEGER PRIMARY KEY AUTOINCREMENT,
`name` VARCHAR(32) UNIQUE,
`password` VARCHAR(512),
`last_login` INTEGER
);
CREATE TABLE `user_privileges` (
`id` INTEGER,
`privilege` VARCHAR(32),
PRIMARY KEY (id, privilege),
CONSTRAINT fk_id FOREIGN KEY (id) REFERENCES auth (id) ON DELETE CASCADE
);
The name
and password
fields of the auth table are the same as the auth.txt
fields (with modern password hash). The last_login
field is the last login
time as a Unix time stamp.
The user_privileges
table contains one entry per privilege and player.
A player with "interact" and "shout" privileges will have two entries, one
with privilege="interact"
and the second with privilege="shout"
.
Simple global environment variables.
Example content:
game_time = 73471
time_of_day = 19118
EnvArgsEnd
Banned IP addresses and usernames.
Example content:
123.456.78.9|foo
123.456.78.10|bar
Simple global map variables.
Example content:
seed = 7980462765762429666
[end_of_params]
Map data.
See Map File Format below.
Player data.
Filename can be anything.
See Player File Format below.
World metadata.
gameid = mesetint - name of the game
enable_damage = true - whether damage is enabled or not
creative_mode = false - whether creative mode is enabled or not
backend = sqlite3 - which DB backend to use for blocks (sqlite3, dummy, leveldb, redis, postgresql)
player_backend = sqlite3 - which DB backend to use for player data
readonly_backend = sqlite3 - optionally read-only seed DB (DB file _must_ be located in "readonly" subfolder)
auth_backend = files - which DB backend to use for authentication data
mod_storage_backend = sqlite3 - which DB backend to use for mod storage
server_announce = false - whether the server is publicly announced or not
load_mod_<mod> = false - whether <mod> is to be loaded in this world
For load_mod_<mod>
, the possible values are:
false
- Do not load the mod.true
- Load the mod from wherever it is found (may cause conflicts if the same mod appears also in some other place).mods/modpack/moddir
- Relative path to the mod
mods/
: mods in the user path's mods folder (ex. /home/user/.minetest/mods
)share/
: mods in the share's mods folder (ex. /usr/share/minetest/mods
)/path/to/env
: you can use absolute paths to mods inside folders specified with the MINETEST_MOD_PATH
env
variable.moddir
is the directory name, not the mod name specified in mod.conf.PostgreSQL
backend specific settings:
pgsql_connection = host=127.0.0.1 port=5432 user=mt_user password=mt_password dbname=minetest
pgsql_player_connection = (same parameters as above)
pgsql_readonly_connection = (same parameters as above)
pgsql_auth_connection = (same parameters as above)
pgsql_mod_storage_connection = (same parameters as above)
Redis
backend specific settings:
redis_address = 127.0.0.1 - Redis server address
redis_hash = foo - Database hash
redis_port = 6379 - (optional) Connection port
redis_password = hunter2 - (optional) Server password
Should be pretty self-explanatory.
Note: Position is in
nodes * 10
Example content:
hp = 11
name = celeron55
pitch = 39.77
position = (-5231.97,15,1961.41)
version = 1
yaw = 101.37
PlayerArgsEnd
List main 32
Item default:torch 13
Item default:pick_steel 1 50112
Item experimental:tnt
Item default:cobble 99
Item default:pick_stone 1 13104
Item default:shovel_steel 1 51838
Item default:dirt 61
Item default:rail 78
Item default:coal_lump 3
Item default:cobble 99
Item default:leaves 22
Item default:gravel 52
Item default:axe_steel 1 2045
Item default:cobble 98
Item default:sand 61
Item default:water_source 94
Item default:glass 2
Item default:mossycobble
Item default:pick_steel 1 64428
Item animalmaterials:bone
Item default:sword_steel
Item default:sapling
Item default:sword_stone 1 10647
Item default:dirt 99
Empty
Empty
Empty
Empty
Empty
Empty
Empty
Empty
EndInventoryList
List craft 9
Empty
Empty
Empty
Empty
Empty
Empty
Empty
Empty
Empty
EndInventoryList
List craftpreview 1
Empty
EndInventoryList
List craftresult 1
Empty
EndInventoryList
EndInventory
Luanti maps consist of MapBlock
s, chunks of 16x16x16 nodes.
In addition to the bulk node data, MapBlock
s stored on disk also contain
other things.
Initially, Luanti stored maps in a format called the "sectors" format. It was a directory/file structure like this:
sectors2/XXX/ZZZ/YYYY
For example, the MapBlock
at (0, 1, -2)
was this file:
sectors2/000/ffd/0001
Eventually Luanti outgrew this directory structure, as filesystems were struggling under the number of files and directories.
Large servers seriously needed a new format, and thus the base of the current format was invented, suggested by celeron55 and implemented by JacobF.
SQLite3
was implemented. Blocks files were directly inserted as blobs
in a single table, indexed by integer primary keys, which were hashed
coordinates.
Today, we know that SQLite3
allows multiple primary keys (which would allow
storing coordinates separately), but the format has been kept unchanged for
that part.
map.sqlite
is a SQLite3
database, containing a single table, called
blocks
. It looks like this:
CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY, `data` BLOB);
pos
(a node position hash) is created from the three coordinates of a
MapBlock
using this algorithm, defined here in Python:
def getBlockAsInteger(p):
return int64(p[2]*16777216 + p[1]*4096 + p[0])
def int64(u):
while u >= 2**63:
u -= 2**64
while u <= -2**63:
u += 2**64
return u
It can be converted the other way by using this code:
def getIntegerAsBlock(i):
x = unsignedToSigned(i % 4096, 2048)
i = int((i - x) / 4096)
y = unsignedToSigned(i % 4096, 2048)
i = int((i - y) / 4096)
z = unsignedToSigned(i % 4096, 2048)
return x,y,z
def unsignedToSigned(i, max_positive):
if i < max_positive:
return i
else:
return i - 2*max_positive
The blob is the data that would have otherwise gone into the file.
See below for description.
Notes:
- NOTE: Byte order is MSB first (big-endian).
- NOTE: Zlib data is in such a format that Python's
zlib
at least can directly decompress.- NOTE: Since version 29 zstd is used instead of zlib. In addition, the entire block is first serialized and then compressed (except the version byte).
u8
version
u8
flags
Flag bitmasks:
0x01
: is_underground
: Should be set to 0 if there will be no light
obstructions above the block. If/when sunlight of a block is updated
and there is no block above it, this value is checked for determining
whether sunlight comes from the top.
0x02
: day_night_differs
: Whether the lighting of the block is different
on day and night. Only blocks that have this bit set are updated when
day transforms to night.
0x04
: lighting_expired
: Not used in version 27 and above. If true,
lighting is invalid and should be updated. If you can't calculate
lighting in your generator properly, you could try setting this 1 to
everything and setting the uppermost block in every sector as
is_underground=0
. It most likely won't work properly.
0x08
: generated
: True if the block has been generated. If false, block
is mostly filled with CONTENT_IGNORE
and is likely to contain e.g. parts
of trees of neighboring blocks.
u16
lighting_complete
Added in version 27.
This contains 12 flags, each of them corresponds to a direction.
Indicates if the light is correct at the sides of a map block. Lighting may not be correct if the light changed, but a neighbor block was not loaded at that time. If these flags are false, Luanti will automatically recompute light when both this block and its required neighbor are loaded.
The bit order is: nothing, nothing, nothing, nothing, night X-, night Y-, night Z-, night Z+, night Y+, night X+, day X-, day Y-, day Z-, day Z+, day Y+, day X+. Where 'day' is for the day light bank, 'night' is for the night light bank. The 'nothing' bits should be always set, as they will be used to indicate if direct sunlight spreading is finished.
Example: if the block at (0, 0, 0)
has lighting_complete = 0b1111111111111110
,
Luanti will correct lighting in the day light bank when the block at
(1, 0, 0)
is also loaded.
Timestamp and node ID mappings were introduced in map format version 29.
u32
timestamp
0xffffffff
= invalid/unknown timestamp, nothing should be done with the time
difference when loadedu8
name_id_mapping_version
u16
num_name_id_mappings
num_name_id_mappings
:
u16
id
u16
name_len
u8[name_len]
name
u8
content_width
param0
) fields of nodesu8
params_width
Note: Zlib-compressed before map format version 29
If content_width
is 1:
u8[4096]
: param0
fieldsu8[4096]
: param1
fieldsu8[4096]
: param2
fieldsIf content_width
is 2:
u16[4096]
: param0
fieldsu8[4096]
: param1
fieldsu8[4096]
: param2
fieldsThe location of a node in each of those arrays is (z*16*16 + y*16 + x)
.
Note: Zlib-compressed before map version format 29
- Before map format version 23:
u16
version (=1)u16
count of metadata- foreach count:
u16
position ((p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
)u16
type_idu16
content_sizeu8[content_size]
content of metadata. Format depends ontype_id
, see below.
u8
version
> Note: Type was u16
before map format version 23
u16
count of metadatau16
position
((p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
)u32
num_vars
num_vars
:
u16
key_len
u8[key_len]
key
u32 val_len
u8[val_len]
value
u8
is_private
Map format version 23:
u8
unused version (always 0)Map format version 24:
Note: Not released as stable
u8
nodetimer_version
nodetimer_version
== 1:
u16
num_of_timers
num_of_timers
:
u16
timer position ((z*16*16 + y*16 + x)
)s32
timeout * 1000s32
elapsed * 1000Since map format version 25:
u8
length of the data of a single timer (always 2+4+4=10)u16
num_of_timers
num_of_timers
:
u16
timer position ((z*16*16 + y*16 + x)
)s32
timeout * 1000s32
elapsed * 1000u8
static object version:
u16
static_object_count
foreach static_object_count
:
u8
type (object type-id)s32
pos_x_nodes
* 10000s32
pos_y_nodes
* 10000s32
pos_z_nodes
* 10000u16
data_size
u8[data_size]
data
Before map format version 29:
u32
timestamp
u8
name-id-mapping
version
u16
num_name_id_mappings
num_name_id_mappings
:
u16
id
u16
name_len
u8[name_len]
name
End of File (EOF).
A node is composed of the u8
fields param0
, param1
and param2
.
Before map format version 24:
param0
< 0x80
, content_id = param0
content_id = (param0<<4) + (param2>>4)
Since map format version 24:
param0
.The purpose of param1
and param2
depend on the definition of the node.
The mapping maps node content IDs to node names.
The node metadata is serialized depending on the type_id
field.
1
: Generic metadata
u32
len
u8[len]
text
u16
len
u8[len]
owner
u16
len
u8[len]
infotext
u16
len
u8[len]
inventory drawspecu8
allow_text_input
(bool)u8
removal_disabled
(bool)u8
enforce_owner
(bool)u32
num_vars
num_vars
:
u16
len
u8[len]
name
u32
len
u8[len]
value
14
: Sign metadata
u16
text_len
u8[text_len]
text
15
: Chest metadata
16
: Furnace metadata
17
: Locked Chest metadata
u16
len
u8[len]
owner
Static objects are persistent freely moving objects in the world.
Object types:
1
: Test object
7
: LuaEntity:
u8
compatibility_byte
(always 1)u16
len
u8[len]
entity nameu32
len
u8[len]
static datas16
hp
s32
velocity.x * 10000s32
velocity.y * 10000s32
velocity.z * 10000s32
yaw * 1000Since protocol version 37:
u8
version2
(=1)s32
pitch * 1000s32
roll * 1000Examples:
'default:dirt 5'
'default:pick_wood 21323'
'"default:apple" 2'
'default:apple'
Older formats:
'node "default:dirt" 5'
'NodeItem default:dirt 5'
'ToolItem WPick 21323'
The wear value in tools is 0...65535.
\n
EndInventory\n
List foo 4
Item default:sapling
Item default:sword_stone 1 10647
Item default:dirt 99
Empty
EndInventoryList
List bar 9
Empty
Empty
Empty
Empty
Empty
Empty
Empty
Empty
Empty
EndInventoryList
EndInventory