2
0

mapformat.txt 14 KB

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