world_format.txt 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596
  1. =============================
  2. Minetest World Format 22...29
  3. =============================
  4. This applies to a world format carrying the block serialization version
  5. 22...27, used at least in
  6. - 0.4.dev-20120322 ... 0.4.dev-20120606 (22...23)
  7. - 0.4.0 (23)
  8. - 24 was never released as stable and existed for ~2 days
  9. - 27 was added in 0.4.15-dev
  10. - 29 was added in 5.5.0-dev
  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.
  14. Files
  15. ======
  16. Everything is contained in a directory, the name of which is freeform, but
  17. often serves as the name of the world.
  18. Currently the authentication and ban data is stored on a per-world basis.
  19. It can be copied over from an old world to a newly created world.
  20. World
  21. |-- auth.txt ----- Authentication data
  22. |-- auth.sqlite -- Authentication data (SQLite alternative)
  23. |-- env_meta.txt - Environment metadata
  24. |-- ipban.txt ---- Banned ips/users
  25. |-- map_meta.txt - Map metadata
  26. |-- map.sqlite --- Map data
  27. |-- players ------ Player directory
  28. | |-- player1 -- Player file
  29. | '-- Foo ------ Player file
  30. `-- world.mt ----- World metadata
  31. auth.txt
  32. ---------
  33. Contains authentication data, player per line.
  34. <name>:<password hash>:<privilege1,...>
  35. Legacy format (until 0.4.12) of password hash is <name><password> SHA1'd,
  36. in the base64 encoding.
  37. Format (since 0.4.13) of password hash is #1#<salt>#<verifier>, with the
  38. parts inside <> encoded in the base64 encoding.
  39. <verifier> is an RFC 2945 compatible SRP verifier,
  40. of the given salt, password, and the player's name lowercased,
  41. using the 2048-bit group specified in RFC 5054 and the SHA-256 hash function.
  42. Example lines:
  43. - Player "celeron55", no password, privileges "interact" and "shout":
  44. celeron55::interact,shout
  45. - Player "Foo", password "bar", privilege "shout", with a legacy password hash:
  46. foo:iEPX+SQWIR3p67lj/0zigSWTKHg:shout
  47. - Player "Foo", password "bar", privilege "shout", with a 0.4.13 pw hash:
  48. foo:#1#hPpy4O3IAn1hsNK00A6wNw#Kpu6rj7McsrPCt4euTb5RA5ltF7wdcWGoYMcRngwDi11cZhPuuR9i5Bo7o6A877TgcEwoc//HNrj9EjR/CGjdyTFmNhiermZOADvd8eu32FYK1kf7RMC0rXWxCenYuOQCG4WF9mMGiyTPxC63VAjAMuc1nCZzmy6D9zt0SIKxOmteI75pAEAIee2hx4OkSXRIiU4Zrxo1Xf7QFxkMY4x77vgaPcvfmuzom0y/fU1EdSnZeopGPvzMpFx80ODFx1P34R52nmVl0W8h4GNo0k8ZiWtRCdrJxs8xIg7z5P1h3Th/BJ0lwexpdK8sQZWng8xaO5ElthNuhO8UQx1l6FgEA:shout
  49. - Player "bar", no password, no privileges:
  50. bar::
  51. auth.sqlite
  52. ------------
  53. Contains authentification data as an SQLite database. This replaces auth.txt
  54. above when auth_backend is set to "sqlite3" in world.mt .
  55. This database contains two tables "auth" and "user_privileges":
  56. CREATE TABLE `auth` (
  57. `id` INTEGER PRIMARY KEY AUTOINCREMENT,
  58. `name` VARCHAR(32) UNIQUE,
  59. `password` VARCHAR(512),
  60. `last_login` INTEGER
  61. );
  62. CREATE TABLE `user_privileges` (
  63. `id` INTEGER,
  64. `privilege` VARCHAR(32),
  65. PRIMARY KEY (id, privilege)
  66. CONSTRAINT fk_id FOREIGN KEY (id) REFERENCES auth (id) ON DELETE CASCADE
  67. );
  68. The "name" and "password" fields of the auth table are the same as the auth.txt
  69. fields (with modern password hash). The "last_login" field is the last login
  70. time as a unix time stamp.
  71. The "user_privileges" table contains one entry per privilege and player.
  72. A player with "interact" and "shout" privileges will have two entries, one
  73. with privilege="interact" and the second with privilege="shout".
  74. env_meta.txt
  75. -------------
  76. Simple global environment variables.
  77. Example content (added indentation):
  78. game_time = 73471
  79. time_of_day = 19118
  80. EnvArgsEnd
  81. ipban.txt
  82. ----------
  83. Banned IP addresses and usernames.
  84. Example content (added indentation):
  85. 123.456.78.9|foo
  86. 123.456.78.10|bar
  87. map_meta.txt
  88. -------------
  89. Simple global map variables.
  90. Example content (added indentation):
  91. seed = 7980462765762429666
  92. [end_of_params]
  93. map.sqlite
  94. -----------
  95. Map data.
  96. See Map File Format below.
  97. player1, Foo
  98. -------------
  99. Player data.
  100. Filename can be anything.
  101. See Player File Format below.
  102. world.mt
  103. ---------
  104. World metadata.
  105. Example content (added indentation and - explanations):
  106. gameid = mesetint - name of the game
  107. enable_damage = true - whether damage is enabled or not
  108. creative_mode = false - whether creative mode is enabled or not
  109. backend = sqlite3 - which DB backend to use for blocks (sqlite3, dummy, leveldb, redis, postgresql)
  110. player_backend = sqlite3 - which DB backend to use for player data
  111. readonly_backend = sqlite3 - optionally readonly seed DB (DB file _must_ be located in "readonly" subfolder)
  112. auth_backend = files - which DB backend to use for authentication data
  113. server_announce = false - whether the server is publicly announced or not
  114. load_mod_<mod> = false - whether <mod> is to be loaded in this world
  115. For load_mod_<mod>, the possible values are:
  116. * `false` - Do not load the mod.
  117. * `true` - Load the mod from wherever it is found (may cause conflicts if the same mod appears also in some other place).
  118. * `mods/modpack/moddir` - Relative path to the mod
  119. * Must be one of the following:
  120. * `mods/`: mods in the user path's mods folder (ex `/home/user/.minetest/mods`)
  121. * `share/`: mods in the share's mods folder (ex: `/usr/share/minetest/mods`)
  122. * `/path/to/env`: you can use absolute paths to mods inside folders specified with the `MINETEST_MOD_PATH` env variable.
  123. * Other locations and absolute paths are not supported
  124. * Note that `moddir` is the directory name, not the mod name specified in mod.conf.
  125. PostgreSQL backend specific settings:
  126. pgsql_connection = host=127.0.0.1 port=5432 user=mt_user password=mt_password dbname=minetest
  127. pgsql_player_connection = (same parameters as above)
  128. pgsql_readonly_connection = (same parameters as above)
  129. pgsql_auth_connection = (same parameters as above)
  130. Redis backend specific settings:
  131. redis_address = 127.0.0.1 - Redis server address
  132. redis_hash = foo - Database hash
  133. redis_port = 6379 - (optional) connection port
  134. redis_password = hunter2 - (optional) server password
  135. Player File Format
  136. ===================
  137. - Should be pretty self-explanatory.
  138. - Note: position is in nodes * 10
  139. Example content (added indentation):
  140. hp = 11
  141. name = celeron55
  142. pitch = 39.77
  143. position = (-5231.97,15,1961.41)
  144. version = 1
  145. yaw = 101.37
  146. PlayerArgsEnd
  147. List main 32
  148. Item default:torch 13
  149. Item default:pick_steel 1 50112
  150. Item experimental:tnt
  151. Item default:cobble 99
  152. Item default:pick_stone 1 13104
  153. Item default:shovel_steel 1 51838
  154. Item default:dirt 61
  155. Item default:rail 78
  156. Item default:coal_lump 3
  157. Item default:cobble 99
  158. Item default:leaves 22
  159. Item default:gravel 52
  160. Item default:axe_steel 1 2045
  161. Item default:cobble 98
  162. Item default:sand 61
  163. Item default:water_source 94
  164. Item default:glass 2
  165. Item default:mossycobble
  166. Item default:pick_steel 1 64428
  167. Item animalmaterials:bone
  168. Item default:sword_steel
  169. Item default:sapling
  170. Item default:sword_stone 1 10647
  171. Item default:dirt 99
  172. Empty
  173. Empty
  174. Empty
  175. Empty
  176. Empty
  177. Empty
  178. Empty
  179. Empty
  180. EndInventoryList
  181. List craft 9
  182. Empty
  183. Empty
  184. Empty
  185. Empty
  186. Empty
  187. Empty
  188. Empty
  189. Empty
  190. Empty
  191. EndInventoryList
  192. List craftpreview 1
  193. Empty
  194. EndInventoryList
  195. List craftresult 1
  196. Empty
  197. EndInventoryList
  198. EndInventory
  199. Map File Format
  200. ================
  201. Minetest maps consist of MapBlocks, chunks of 16x16x16 nodes.
  202. In addition to the bulk node data, MapBlocks stored on disk also contain
  203. other things.
  204. History
  205. --------
  206. We need a bit of history in here. Initially Minetest stored maps in a
  207. format called the "sectors" format. It was a directory/file structure like
  208. this:
  209. sectors2/XXX/ZZZ/YYYY
  210. For example, the MapBlock at (0,1,-2) was this file:
  211. sectors2/000/ffd/0001
  212. Eventually Minetest outgrow this directory structure, as filesystems were
  213. struggling under the amount of files and directories.
  214. Large servers seriously needed a new format, and thus the base of the
  215. current format was invented, suggested by celeron55 and implemented by
  216. JacobF.
  217. SQLite3 was slammed in, and blocks files were directly inserted as blobs
  218. in a single table, indexed by integer primary keys, oddly mangled from
  219. coordinates.
  220. Today we know that SQLite3 allows multiple primary keys (which would allow
  221. storing coordinates separately), but the format has been kept unchanged for
  222. that part. So, this is where it has come.
  223. </history>
  224. So here goes
  225. -------------
  226. map.sqlite is an sqlite3 database, containing a single table, called
  227. "blocks". It looks like this:
  228. CREATE TABLE `blocks` (`pos` INT NOT NULL PRIMARY KEY,`data` BLOB);
  229. The key
  230. --------
  231. "pos" is created from the three coordinates of a MapBlock using this
  232. algorithm, defined here in Python:
  233. def getBlockAsInteger(p):
  234. return int64(p[2]*16777216 + p[1]*4096 + p[0])
  235. def int64(u):
  236. while u >= 2**63:
  237. u -= 2**64
  238. while u <= -2**63:
  239. u += 2**64
  240. return u
  241. It can be converted the other way by using this code:
  242. def getIntegerAsBlock(i):
  243. x = unsignedToSigned(i % 4096, 2048)
  244. i = int((i - x) / 4096)
  245. y = unsignedToSigned(i % 4096, 2048)
  246. i = int((i - y) / 4096)
  247. z = unsignedToSigned(i % 4096, 2048)
  248. return x,y,z
  249. def unsignedToSigned(i, max_positive):
  250. if i < max_positive:
  251. return i
  252. else:
  253. return i - 2*max_positive
  254. The blob
  255. ---------
  256. The blob is the data that would have otherwise gone into the file.
  257. See below for description.
  258. MapBlock serialization format
  259. ==============================
  260. NOTE: Byte order is MSB first (big-endian).
  261. NOTE: Zlib data is in such a format that Python's zlib at least can
  262. directly decompress.
  263. NOTE: Since version 29 zstd is used instead of zlib. In addition the entire
  264. block is first serialized and then compressed (except the version byte).
  265. u8 version
  266. - map format version number, see serialisation.h for the latest number
  267. u8 flags
  268. - Flag bitmasks:
  269. - 0x01: is_underground: Should be set to 0 if there will be no light
  270. obstructions above the block. If/when sunlight of a block is updated
  271. and there is no block above it, this value is checked for determining
  272. whether sunlight comes from the top.
  273. - 0x02: day_night_differs: Whether the lighting of the block is different
  274. on day and night. Only blocks that have this bit set are updated when
  275. day transforms to night.
  276. - 0x04: lighting_expired: Not used in version 27 and above. If true,
  277. lighting is invalid and should be updated. If you can't calculate
  278. lighting in your generator properly, you could try setting this 1 to
  279. everything and setting the uppermost block in every sector as
  280. is_underground=0. I am quite sure it doesn't work properly, though.
  281. - 0x08: generated: True if the block has been generated. If false, block
  282. is mostly filled with CONTENT_IGNORE and is likely to contain eg. parts
  283. of trees of neighboring blocks.
  284. u16 lighting_complete
  285. - Added in version 27.
  286. - This contains 12 flags, each of them corresponds to a direction.
  287. - Indicates if the light is correct at the sides of a map block.
  288. Lighting may not be correct if the light changed, but a neighbor
  289. block was not loaded at that time.
  290. If these flags are false, Minetest will automatically recompute light
  291. when both this block and its required neighbor are loaded.
  292. - The bit order is:
  293. nothing, nothing, nothing, nothing,
  294. night X-, night Y-, night Z-, night Z+, night Y+, night X+,
  295. day X-, day Y-, day Z-, day Z+, day Y+, day X+.
  296. Where 'day' is for the day light bank, 'night' is for the night
  297. light bank.
  298. The 'nothing' bits should be always set, as they will be used
  299. to indicate if direct sunlight spreading is finished.
  300. - Example: if the block at (0, 0, 0) has
  301. lighting_complete = 0b1111111111111110,
  302. then Minetest will correct lighting in the day light bank when
  303. the block at (1, 0, 0) is also loaded.
  304. if map format version >= 29:
  305. u32 timestamp
  306. - Timestamp when last saved, as seconds from starting the game.
  307. - 0xffffffff = invalid/unknown timestamp, nothing should be done with the time
  308. difference when loaded
  309. u8 name_id_mapping_version
  310. - Should be zero for map format version 29.
  311. u16 num_name_id_mappings
  312. foreach num_name_id_mappings
  313. u16 id
  314. u16 name_len
  315. u8[name_len] name
  316. if map format version < 29:
  317. -- Nothing right here, timpstamp and node id mappings are serialized later
  318. u8 content_width
  319. - Number of bytes in the content (param0) fields of nodes
  320. if map format version <= 23:
  321. - Always 1
  322. if map format version >= 24:
  323. - Always 2
  324. u8 params_width
  325. - Number of bytes used for parameters per node
  326. - Always 2
  327. node data (zlib-compressed if version < 29):
  328. if content_width == 1:
  329. - content:
  330. u8[4096]: param0 fields
  331. u8[4096]: param1 fields
  332. u8[4096]: param2 fields
  333. if content_width == 2:
  334. - content:
  335. u16[4096]: param0 fields
  336. u8[4096]: param1 fields
  337. u8[4096]: param2 fields
  338. - The location of a node in each of those arrays is (z*16*16 + y*16 + x).
  339. node metadata list (zlib-compressed if version < 29):
  340. - content:
  341. if map format version <= 22:
  342. u16 version (=1)
  343. u16 count of metadata
  344. foreach count:
  345. u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
  346. u16 type_id
  347. u16 content_size
  348. u8[content_size] content of metadata. Format depends on type_id, see below.
  349. if map format version >= 23:
  350. u8 version -- Note: type was u16 for map format version <= 22
  351. -- = 1 for map format version < 28
  352. -- = 2 since map format version 28
  353. u16 count of metadata
  354. foreach count:
  355. u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X)
  356. u32 num_vars
  357. foreach num_vars:
  358. u16 key_len
  359. u8[key_len] key
  360. u32 val_len
  361. u8[val_len] value
  362. u8 is_private -- only for version >= 2. 0 = not private, 1 = private
  363. serialized inventory
  364. - Node timers
  365. if map format version == 23:
  366. u8 unused version (always 0)
  367. if map format version == 24: (NOTE: Not released as stable)
  368. u8 nodetimer_version
  369. if nodetimer_version == 0:
  370. (nothing else)
  371. if nodetimer_version == 1:
  372. u16 num_of_timers
  373. foreach num_of_timers:
  374. u16 timer position (z*16*16 + y*16 + x)
  375. s32 timeout*1000
  376. s32 elapsed*1000
  377. if map format version >= 25:
  378. -- Nothing right here, node timers are serialized later
  379. u8 static object version:
  380. - Always 0
  381. u16 static_object_count
  382. foreach static_object_count:
  383. u8 type (object type-id)
  384. s32 pos_x_nodes * 10000
  385. s32 pos_y_nodes * 10000
  386. s32 pos_z_nodes * 10000
  387. u16 data_size
  388. u8[data_size] data
  389. if map format version < 29:
  390. u32 timestamp
  391. - Same meaning as the timestamp further up
  392. u8 name-id-mapping version
  393. - Always 0
  394. u16 num_name_id_mappings
  395. foreach num_name_id_mappings
  396. u16 id
  397. u16 name_len
  398. u8[name_len] name
  399. - Node timers
  400. if map format version >= 25:
  401. u8 length of the data of a single timer (always 2+4+4=10)
  402. u16 num_of_timers
  403. foreach num_of_timers:
  404. u16 timer position (z*16*16 + y*16 + x)
  405. s32 timeout*1000
  406. s32 elapsed*1000
  407. EOF.
  408. Format of nodes
  409. ----------------
  410. A node is composed of the u8 fields param0, param1 and param2.
  411. if map format version <= 23:
  412. The content id of a node is determined as so:
  413. - If param0 < 0x80,
  414. content_id = param0
  415. - Otherwise
  416. content_id = (param0<<4) + (param2>>4)
  417. if map format version >= 24:
  418. The content id of a node is param0.
  419. The purpose of param1 and param2 depend on the definition of the node.
  420. The name-id-mapping
  421. --------------------
  422. The mapping maps node content ids to node names.
  423. Node metadata format for map format versions <= 22
  424. ---------------------------------------------------
  425. The node metadata are serialized depending on the type_id field.
  426. 1: Generic metadata
  427. serialized inventory
  428. u32 len
  429. u8[len] text
  430. u16 len
  431. u8[len] owner
  432. u16 len
  433. u8[len] infotext
  434. u16 len
  435. u8[len] inventory drawspec
  436. u8 allow_text_input (bool)
  437. u8 removal_disabled (bool)
  438. u8 enforce_owner (bool)
  439. u32 num_vars
  440. foreach num_vars
  441. u16 len
  442. u8[len] name
  443. u32 len
  444. u8[len] value
  445. 14: Sign metadata
  446. u16 text_len
  447. u8[text_len] text
  448. 15: Chest metadata
  449. serialized inventory
  450. 16: Furnace metadata
  451. TBD
  452. 17: Locked Chest metadata
  453. u16 len
  454. u8[len] owner
  455. serialized inventory
  456. Static objects
  457. ---------------
  458. Static objects are persistent freely moving objects in the world.
  459. Object types:
  460. 1: Test object
  461. 7: LuaEntity
  462. 7: LuaEntity:
  463. u8 compatibility_byte (always 1)
  464. u16 len
  465. u8[len] entity name
  466. u32 len
  467. u8[len] static data
  468. s16 hp
  469. s32 velocity.x * 10000
  470. s32 velocity.y * 10000
  471. s32 velocity.z * 10000
  472. s32 yaw * 1000
  473. if PROTOCOL_VERSION >= 37:
  474. u8 version2 (=1)
  475. s32 pitch * 1000
  476. s32 roll * 1000
  477. Itemstring format
  478. ------------------
  479. eg. 'default:dirt 5'
  480. eg. 'default:pick_wood 21323'
  481. eg. '"default:apple" 2'
  482. eg. 'default:apple'
  483. - The wear value in tools is 0...65535
  484. - There are also a number of older formats that you might stumble upon:
  485. eg. 'node "default:dirt" 5'
  486. eg. 'NodeItem default:dirt 5'
  487. eg. 'ToolItem WPick 21323'
  488. Inventory serialization format
  489. -------------------------------
  490. - The inventory serialization format is line-based
  491. - The newline character used is "\n"
  492. - The end condition of a serialized inventory is always "EndInventory\n"
  493. - All the slots in a list must always be serialized.
  494. Example (format does not include "---"):
  495. ---
  496. List foo 4
  497. Item default:sapling
  498. Item default:sword_stone 1 10647
  499. Item default:dirt 99
  500. Empty
  501. EndInventoryList
  502. List bar 9
  503. Empty
  504. Empty
  505. Empty
  506. Empty
  507. Empty
  508. Empty
  509. Empty
  510. Empty
  511. Empty
  512. EndInventoryList
  513. EndInventory
  514. ---