Update doc/mapformat.txt

1 files changed, 358 insertions, 29 deletions

diff --git a/doc/mapformat.txt b/doc/mapformat.txt
index 430be2d48..fd892c9db 100644
--- a/doc/mapformat.txt
+++ b/doc/mapformat.txt
@@ -1,24 +1,22 @@
-=========================================
-         Minetest World Format
-=========================================
+===============================================
+Minetest World Format used as of 0.4.dev-120322
+===============================================
 
-Format used as of 0.4.dev-120322
-==================================
+This applies to a world format carrying the block serialization version 22
+which is used at least in version 0.4.dev-120322.
 
-This applies to a world format carrying the serialization version 22 which
-is used at least in version 0.4.dev-120322.
+The map data serialization version used is 22. It 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.
 
-The serialization version used is 22. It 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.
-
-Legacy stuff:
--------------
+Legacy stuff
+=============
 Data can, in theory, be contained in the flat file directory structure
-described below in Version 17, but it is not officially supported.
+described below in Version 17, but it is not officially supported. Also you
+may stumble upon all kinds of oddities in not-so-recent formats.
 
-Files:
-------
+Files
+======
 Everything is contained in a directory, the name of which is freeform, but
 often serves as the name of the world.
 
@@ -33,36 +31,367 @@ World
 |-- map.sqlite --- Map data
 |-- players ------ Player directory
 |   |-- player1 -- Player file
-|   '-- player2 -- Player file
+|   '-- Foo ------ Player file
 `-- world.mt ----- World metadata
 
 auth.txt
 ---------
 Contains authentication data, player per line.
-<name>:<password hash as <name><password> SHA1 base64>:<privilege1,...>
+  <name>:<password hash>:<privilege1,...>
+Format of password hash is <name><password> SHA1'd, in the base64 encoding.
+
 Example lines:
-Player "celeron55", no password, privileges "interact" and "shout":
-celeron55::interact,shout
-Player "Foo", password "bar", privileges "interact" and "shout":
-foo:iEPX+SQWIR3p67lj/0zigSWTKHg:interact,shout
+- Player "celeron55", no password, privileges "interact" and "shout":
+    celeron55::interact,shout
+- Player "Foo", password "bar", privilege "shout":
+    foo:iEPX+SQWIR3p67lj/0zigSWTKHg:shout
+- Player "bar", no password, no privileges:
+    bar::
 
 env_meta.txt
 -------------
---- Example content ---
-game_time = 73471
-time_of_day = 19118
-EnvArgsEnd
------------------------
+Simple global environment variables.
+Example content (added indentation):
+  game_time = 73471
+  time_of_day = 19118
+  EnvArgsEnd
 
 ipban.txt
 ----------
+Banned IP addresses and usernames.
+Example content (added indentation):
+  123.456.78.9|foo
+  123.456.78.10|bar
+
+map_meta.txt
+-------------
+Simple global map variables.
+Example content (added indentation):
+  seed = 7980462765762429666
+  [end_of_params]
+
+map.sqlite
+-----------
+Map data.
+See Map File Format below.
+
+player1, Foo
+-------------
+Player data.
+Filename can be anything.
+See Player File Format below.
+
+world.mt
+---------
+World metadata.
+Example content (added indentation):
+  gameid = mesetint
+
+Player File Format
+===================
+
+- Should be pretty self-explanatory.
+- Note: position is in nodes * 10
+
+Example content (added indentation):
+  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
+
+Map File Format
+================
+
+Minetest maps consist of MapBlocks, chunks of 16x16x16 nodes.
+
+In addition to the bulk node data, MapBlocks stored on disk also contain
+other things.
+
+History
+--------
+We need a bit of history in here. Initially Minetest 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 Minetest outgrow this directory structure, as filesystems were
+struggling under the amount 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 slammed in, and blocks files were directly inserted as blobs
+in a single table, indexed by integer primary keys, oddly mangled from
+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. So, this is where it has come.
+</history>
+
+So here goes
+-------------
+map.sqlite is an sqlite3 database, containg a single table, called
+"blocks". It looks like this:
+
+  CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY,`data` BLOB);
+
+The key
+--------
+"pos" 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
+---------
+The blob is the data that would have otherwise gone into the file.
+
+See below for description.
+
+MapBlock serialization format
+==============================
+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.
+
+u8 version
+- map format version number, this one is version 22
+
+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: 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. I am quite sure it doesn't
+    work properly, though.
+  - 0x08: generated: True if the block has been generated. If false, block
+    is mostly filled with CONTENT_IGNORE and is likely to contain eg. parts
+    of trees of neighboring blocks.
+
+u8 content_width
+- Number of bytes in the content (param0) fields of nodes
+- Always 1
+
+u8 params_width
+- Number of bytes used for parameters per node
+- Always 2
+
+zlib-compressed node data:
+- content:
+  u8[4096]: param0 fields
+  u8[4096]: param1 fields
+  u8[4096]: param2 fields
+
+zlib-compressed node metadata list
+- content:
+  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_id
+    u16 content_size
+    u8[content_size] (content of metadata)
+
+u16 mapblockobject_count
+- Always 0
+- Should be removed in version 23 (TODO)
+
+u8 static object version:
+- Always 0
+
+u16 static_object_count
+
+foreach static_object_count:
+  u8 type (object type-id)
+  s32 pos_x_nodes * 10000
+  s32 pos_y_nodes * 10000
+  s32 pos_z_nodes * 10000
+  u16 data_size
+  u8[data_size] data
+
+u32 timestamp
+- Timestamp when last saved, as seconds from starting the game.
+- 0xffffffff = invalid/unknown timestamp, nothing should be done with the time
+               difference when loaded
+
+u8 name-id-mapping version
+- Always 0
+
+u16 num_name_id_mappings
 
+foreach num_name_id_mappings
+  u16 id
+  u16 name_len
+  u8[name_len] name
 
-Format used as of 2011-05 or so
-================================
+EOF.
+
+Node metadata format
+---------------------
+
+1: Generic metadata
+  serialized inventory
+  u32 len
+  u8[len] text
+  u16 len
+  u8[len] owner
+  u16 len
+  u8[len] infotext
+  u16 len
+  u8[len] inventory drawspec
+  u8 allow_text_input (bool)
+  u8 removal_disabled (bool)
+  u8 enforce_owner (bool)
+  u32 num_vars
+  foreach 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
+  serialized inventory
+
+16: Furnace metadata
+  TBD
+
+17: Locked Chest metadata
+  u16 len
+  u8[len] owner
+  serialized inventory
+
+Inventory serialization format
+-------------------------------
+- The inventory serialization format is line-based
+- The newline character used is "\n"
+- The end condition of a serialized inventory is always "EndInventory\n"
+- All the slots in a list must always be serialized.
+
+Example (format does not include "---"):
+---
+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
+---
+
+==============================================
+Minetest World Format used as of 2011-05 or so
+==============================================
 
 Map data serialization format version 17.
 
+0.3.1 does not use this format, but a more recent one. This exists here for
+historical reasons.
+
 Directory structure:
 sectors/XXXXZZZZ or sectors2/XXX/ZZZ
 XXXX, ZZZZ, XXX and ZZZ being the hexadecimal X and Z coordinates.