Final Minetest - Please use Linux & Windows build kits at: https://downloads.minetest.org/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

world_format.txt 19KB

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