client_lua_api.txt 48 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208
  1. Minetest Lua Client Modding API Reference 0.5.0
  2. ================================================
  3. * More information at <http://www.minetest.net/>
  4. * Developer Wiki: <http://dev.minetest.net/>
  5. Introduction
  6. ------------
  7. ** WARNING: The client API is currently unstable, and may break/change without warning. **
  8. Content and functionality can be added to Minetest 0.4.15-dev+ by using Lua
  9. scripting in run-time loaded mods.
  10. A mod is a self-contained bunch of scripts, textures and other related
  11. things that is loaded by and interfaces with Minetest.
  12. Transferring client-sided mods from the server to the client is planned, but not implemented yet.
  13. If you see a deficiency in the API, feel free to attempt to add the
  14. functionality in the engine and API. You can send such improvements as
  15. source code patches on GitHub (https://github.com/minetest/minetest).
  16. Programming in Lua
  17. ------------------
  18. If you have any difficulty in understanding this, please read
  19. [Programming in Lua](http://www.lua.org/pil/).
  20. Startup
  21. -------
  22. Mods are loaded during client startup from the mod load paths by running
  23. the `init.lua` scripts in a shared environment.
  24. Paths
  25. -----
  26. * `RUN_IN_PLACE=1` (Windows release, local build)
  27. * `$path_user`:
  28. * Linux: `<build directory>`
  29. * Windows: `<build directory>`
  30. * `$path_share`
  31. * Linux: `<build directory>`
  32. * Windows: `<build directory>`
  33. * `RUN_IN_PLACE=0`: (Linux release)
  34. * `$path_share`
  35. * Linux: `/usr/share/minetest`
  36. * Windows: `<install directory>/minetest-0.4.x`
  37. * `$path_user`:
  38. * Linux: `$HOME/.minetest`
  39. * Windows: `C:/users/<user>/AppData/minetest` (maybe)
  40. Mod load path
  41. -------------
  42. Generic:
  43. * `$path_share/clientmods/`
  44. * `$path_user/clientmods/` (User-installed mods)
  45. In a run-in-place version (e.g. the distributed windows version):
  46. * `minetest-0.4.x/clientmods/` (User-installed mods)
  47. On an installed version on Linux:
  48. * `/usr/share/minetest/clientmods/`
  49. * `$HOME/.minetest/clientmods/` (User-installed mods)
  50. Modpack support
  51. ----------------
  52. **NOTE: Not implemented yet.**
  53. Mods can be put in a subdirectory, if the parent directory, which otherwise
  54. should be a mod, contains a file named `modpack.txt`. This file shall be
  55. empty, except for lines starting with `#`, which are comments.
  56. Mod directory structure
  57. ------------------------
  58. clientmods
  59. ├── modname
  60. | ├── depends.txt
  61. | ├── init.lua
  62. └── another
  63. ### modname
  64. The location of this directory.
  65. ### depends.txt
  66. List of mods that have to be loaded before loading this mod.
  67. A single line contains a single modname.
  68. Optional dependencies can be defined by appending a question mark
  69. to a single modname. Their meaning is that if the specified mod
  70. is missing, that does not prevent this mod from being loaded.
  71. ### init.lua
  72. The main Lua script. Running this script should register everything it
  73. wants to register. Subsequent execution depends on minetest calling the
  74. registered callbacks.
  75. `minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used
  76. to read custom or existing settings at load time, if necessary.
  77. ### `sounds`
  78. Media files (sounds) that will be transferred to the
  79. client and will be available for use by the mod.
  80. Naming convention for registered textual names
  81. ----------------------------------------------
  82. Registered names should generally be in this format:
  83. "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
  84. This is to prevent conflicting names from corrupting maps and is
  85. enforced by the mod loader.
  86. ### Example
  87. In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
  88. So the name should be `experimental:tnt`.
  89. Enforcement can be overridden by prefixing the name with `:`. This can
  90. be used for overriding the registrations of some other mod.
  91. Example: Any mod can redefine `experimental:tnt` by using the name
  92. :experimental:tnt
  93. when registering it.
  94. (also that mod is required to have `experimental` as a dependency)
  95. The `:` prefix can also be used for maintaining backwards compatibility.
  96. Sounds
  97. ------
  98. **NOTE: max_hear_distance and connecting to objects is not implemented.**
  99. Only Ogg Vorbis files are supported.
  100. For positional playing of sounds, only single-channel (mono) files are
  101. supported. Otherwise OpenAL will play them non-positionally.
  102. Mods should generally prefix their sounds with `modname_`, e.g. given
  103. the mod name "`foomod`", a sound could be called:
  104. foomod_foosound.ogg
  105. Sounds are referred to by their name with a dot, a single digit and the
  106. file extension stripped out. When a sound is played, the actual sound file
  107. is chosen randomly from the matching sounds.
  108. When playing the sound `foomod_foosound`, the sound is chosen randomly
  109. from the available ones of the following files:
  110. * `foomod_foosound.ogg`
  111. * `foomod_foosound.0.ogg`
  112. * `foomod_foosound.1.ogg`
  113. * (...)
  114. * `foomod_foosound.9.ogg`
  115. Examples of sound parameter tables:
  116. -- Play locationless
  117. {
  118. gain = 1.0, -- default
  119. }
  120. -- Play locationless, looped
  121. {
  122. gain = 1.0, -- default
  123. loop = true,
  124. }
  125. -- Play in a location
  126. {
  127. pos = {x = 1, y = 2, z = 3},
  128. gain = 1.0, -- default
  129. max_hear_distance = 32, -- default, uses an euclidean metric
  130. }
  131. -- Play connected to an object, looped
  132. {
  133. object = <an ObjectRef>,
  134. gain = 1.0, -- default
  135. max_hear_distance = 32, -- default, uses an euclidean metric
  136. loop = true,
  137. }
  138. Looped sounds must either be connected to an object or played locationless.
  139. ### SimpleSoundSpec
  140. * e.g. `""`
  141. * e.g. `"default_place_node"`
  142. * e.g. `{}`
  143. * e.g. `{name = "default_place_node"}`
  144. * e.g. `{name = "default_place_node", gain = 1.0}`
  145. Representations of simple things
  146. --------------------------------
  147. ### Position/vector
  148. {x=num, y=num, z=num}
  149. For helper functions see "Vector helpers".
  150. ### pointed_thing
  151. * `{type="nothing"}`
  152. * `{type="node", under=pos, above=pos}`
  153. * `{type="object", id=ObjectID}`
  154. Flag Specifier Format
  155. ---------------------
  156. Flags using the standardized flag specifier format can be specified in either of
  157. two ways, by string or table.
  158. The string format is a comma-delimited set of flag names; whitespace and
  159. unrecognized flag fields are ignored. Specifying a flag in the string sets the
  160. flag, and specifying a flag prefixed by the string `"no"` explicitly
  161. clears the flag from whatever the default may be.
  162. In addition to the standard string flag format, the schematic flags field can
  163. also be a table of flag names to boolean values representing whether or not the
  164. flag is set. Additionally, if a field with the flag name prefixed with `"no"`
  165. is present, mapped to a boolean of any value, the specified flag is unset.
  166. E.g. A flag field of value
  167. {place_center_x = true, place_center_y=false, place_center_z=true}
  168. is equivalent to
  169. {place_center_x = true, noplace_center_y=true, place_center_z=true}
  170. which is equivalent to
  171. "place_center_x, noplace_center_y, place_center_z"
  172. or even
  173. "place_center_x, place_center_z"
  174. since, by default, no schematic attributes are set.
  175. Formspec
  176. --------
  177. Formspec defines a menu. It is a string, with a somewhat strange format.
  178. Spaces and newlines can be inserted between the blocks, as is used in the
  179. examples.
  180. ### Examples
  181. #### Chest
  182. size[8,9]
  183. list[context;main;0,0;8,4;]
  184. list[current_player;main;0,5;8,4;]
  185. #### Furnace
  186. size[8,9]
  187. list[context;fuel;2,3;1,1;]
  188. list[context;src;2,1;1,1;]
  189. list[context;dst;5,1;2,2;]
  190. list[current_player;main;0,5;8,4;]
  191. #### Minecraft-like player inventory
  192. size[8,7.5]
  193. image[1,0.6;1,2;player.png]
  194. list[current_player;main;0,3.5;8,4;]
  195. list[current_player;craft;3,0;3,3;]
  196. list[current_player;craftpreview;7,1;1,1;]
  197. ### Elements
  198. #### `size[<W>,<H>,<fixed_size>]`
  199. * Define the size of the menu in inventory slots
  200. * `fixed_size`: `true`/`false` (optional)
  201. * deprecated: `invsize[<W>,<H>;]`
  202. #### `container[<X>,<Y>]`
  203. * Start of a container block, moves all physical elements in the container by (X, Y)
  204. * Must have matching container_end
  205. * Containers can be nested, in which case the offsets are added
  206. (child containers are relative to parent containers)
  207. #### `container_end[]`
  208. * End of a container, following elements are no longer relative to this container
  209. #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
  210. * Show an inventory list
  211. #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
  212. * Show an inventory list
  213. #### `listring[<inventory location>;<list name>]`
  214. * Allows to create a ring of inventory lists
  215. * Shift-clicking on items in one element of the ring
  216. will send them to the next inventory list inside the ring
  217. * The first occurrence of an element inside the ring will
  218. determine the inventory where items will be sent to
  219. #### `listring[]`
  220. * Shorthand for doing `listring[<inventory location>;<list name>]`
  221. for the last two inventory lists added by list[...]
  222. #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
  223. * Sets background color of slots as `ColorString`
  224. * Sets background color of slots on mouse hovering
  225. #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
  226. * Sets background color of slots as `ColorString`
  227. * Sets background color of slots on mouse hovering
  228. * Sets color of slots border
  229. #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
  230. * Sets background color of slots as `ColorString`
  231. * Sets background color of slots on mouse hovering
  232. * Sets color of slots border
  233. * Sets default background color of tooltips
  234. * Sets default font color of tooltips
  235. #### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
  236. * Adds tooltip for an element
  237. * `<bgcolor>` tooltip background color as `ColorString` (optional)
  238. * `<fontcolor>` tooltip font color as `ColorString` (optional)
  239. #### `image[<X>,<Y>;<W>,<H>;<texture name>]`
  240. * Show an image
  241. * Position and size units are inventory slots
  242. #### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
  243. * Show an inventory image of registered item/node
  244. * Position and size units are inventory slots
  245. #### `bgcolor[<color>;<fullscreen>]`
  246. * Sets background color of formspec as `ColorString`
  247. * If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
  248. #### `background[<X>,<Y>;<W>,<H>;<texture name>]`
  249. * Use a background. Inventory rectangles are not drawn then.
  250. * Position and size units are inventory slots
  251. * Example for formspec 8x4 in 16x resolution: image shall be sized
  252. 8 times 16px times 4 times 16px.
  253. #### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
  254. * Use a background. Inventory rectangles are not drawn then.
  255. * Position and size units are inventory slots
  256. * Example for formspec 8x4 in 16x resolution:
  257. image shall be sized 8 times 16px times 4 times 16px
  258. * If `true` the background is clipped to formspec size
  259. (`x` and `y` are used as offset values, `w` and `h` are ignored)
  260. #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
  261. * Textual password style field; will be sent to server when a button is clicked
  262. * When enter is pressed in field, fields.key_enter_field will be sent with the name
  263. of this field.
  264. * `x` and `y` position the field relative to the top left of the menu
  265. * `w` and `h` are the size of the field
  266. * Fields are a set height, but will be vertically centred on `h`
  267. * Position and size units are inventory slots
  268. * `name` is the name of the field as returned in fields to `on_receive_fields`
  269. * `label`, if not blank, will be text printed on the top left above the field
  270. * See field_close_on_enter to stop enter closing the formspec
  271. #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
  272. * Textual field; will be sent to server when a button is clicked
  273. * When enter is pressed in field, fields.key_enter_field will be sent with the name
  274. of this field.
  275. * `x` and `y` position the field relative to the top left of the menu
  276. * `w` and `h` are the size of the field
  277. * Fields are a set height, but will be vertically centred on `h`
  278. * Position and size units are inventory slots
  279. * `name` is the name of the field as returned in fields to `on_receive_fields`
  280. * `label`, if not blank, will be text printed on the top left above the field
  281. * `default` is the default value of the field
  282. * `default` may contain variable references such as `${text}'` which
  283. will fill the value from the metadata value `text`
  284. * **Note**: no extra text or more than a single variable is supported ATM.
  285. * See field_close_on_enter to stop enter closing the formspec
  286. #### `field[<name>;<label>;<default>]`
  287. * As above, but without position/size units
  288. * When enter is pressed in field, fields.key_enter_field will be sent with the name
  289. of this field.
  290. * Special field for creating simple forms, such as sign text input
  291. * Must be used without a `size[]` element
  292. * A "Proceed" button will be added automatically
  293. * See field_close_on_enter to stop enter closing the formspec
  294. #### `field_close_on_enter[<name>;<close_on_enter>]`
  295. * <name> is the name of the field
  296. * if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
  297. * defaults to true when not specified (ie: no tag for a field)
  298. #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
  299. * Same as fields above, but with multi-line input
  300. #### `label[<X>,<Y>;<label>]`
  301. * `x` and `y` work as per field
  302. * `label` is the text on the label
  303. * Position and size units are inventory slots
  304. #### `vertlabel[<X>,<Y>;<label>]`
  305. * Textual label drawn vertically
  306. * `x` and `y` work as per field
  307. * `label` is the text on the label
  308. * Position and size units are inventory slots
  309. #### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
  310. * Clickable button. When clicked, fields will be sent.
  311. * `x`, `y` and `name` work as per field
  312. * `w` and `h` are the size of the button
  313. * Fixed button height. It will be vertically centred on `h`
  314. * `label` is the text on the button
  315. * Position and size units are inventory slots
  316. #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
  317. * `x`, `y`, `w`, `h`, and `name` work as per button
  318. * `texture name` is the filename of an image
  319. * Position and size units are inventory slots
  320. #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
  321. * `x`, `y`, `w`, `h`, and `name` work as per button
  322. * `texture name` is the filename of an image
  323. * Position and size units are inventory slots
  324. * `noclip=true` means the image button doesn't need to be within specified formsize
  325. * `drawborder`: draw button border or not
  326. * `pressed texture name` is the filename of an image on pressed state
  327. #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
  328. * `x`, `y`, `w`, `h`, `name` and `label` work as per button
  329. * `item name` is the registered name of an item/node,
  330. tooltip will be made out of its description
  331. to override it use tooltip element
  332. * Position and size units are inventory slots
  333. #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
  334. * When clicked, fields will be sent and the form will quit.
  335. #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
  336. * When clicked, fields will be sent and the form will quit.
  337. #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
  338. * Scrollable item list showing arbitrary text elements
  339. * `x` and `y` position the itemlist relative to the top left of the menu
  340. * `w` and `h` are the size of the itemlist
  341. * `name` fieldname sent to server on doubleclick value is current selected element
  342. * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
  343. * if you want a listelement to start with "#" write "##".
  344. #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
  345. * Scrollable itemlist showing arbitrary text elements
  346. * `x` and `y` position the item list relative to the top left of the menu
  347. * `w` and `h` are the size of the item list
  348. * `name` fieldname sent to server on doubleclick value is current selected element
  349. * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
  350. * if you want a listelement to start with "#" write "##"
  351. * Index to be selected within textlist
  352. * `true`/`false`: draw transparent background
  353. * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
  354. #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
  355. * Show a tab**header** at specific position (ignores formsize)
  356. * `x` and `y` position the itemlist relative to the top left of the menu
  357. * `name` fieldname data is transferred to Lua
  358. * `caption 1`...: name shown on top of tab
  359. * `current_tab`: index of selected tab 1...
  360. * `transparent` (optional): show transparent
  361. * `draw_border` (optional): draw border
  362. #### `box[<X>,<Y>;<W>,<H>;<color>]`
  363. * Simple colored semitransparent box
  364. * `x` and `y` position the box relative to the top left of the menu
  365. * `w` and `h` are the size of box
  366. * `color` is color specified as a `ColorString`
  367. #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
  368. * Show a dropdown field
  369. * **Important note**: There are two different operation modes:
  370. 1. handle directly on change (only changed dropdown is submitted)
  371. 2. read the value on pressing a button (all dropdown values are available)
  372. * `x` and `y` position of dropdown
  373. * Width of dropdown
  374. * Fieldname data is transferred to Lua
  375. * Items to be shown in dropdown
  376. * Index of currently selected dropdown item
  377. #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
  378. * Show a checkbox
  379. * `x` and `y`: position of checkbox
  380. * `name` fieldname data is transferred to Lua
  381. * `label` to be shown left of checkbox
  382. * `selected` (optional): `true`/`false`
  383. #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
  384. * Show a scrollbar
  385. * There are two ways to use it:
  386. 1. handle the changed event (only changed scrollbar is available)
  387. 2. read the value on pressing a button (all scrollbars are available)
  388. * `x` and `y`: position of trackbar
  389. * `w` and `h`: width and height
  390. * `orientation`: `vertical`/`horizontal`
  391. * Fieldname data is transferred to Lua
  392. * Value this trackbar is set to (`0`-`1000`)
  393. * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
  394. #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
  395. * Show scrollable table using options defined by the previous `tableoptions[]`
  396. * Displays cells as defined by the previous `tablecolumns[]`
  397. * `x` and `y`: position the itemlist relative to the top left of the menu
  398. * `w` and `h` are the size of the itemlist
  399. * `name`: fieldname sent to server on row select or doubleclick
  400. * `cell 1`...`cell n`: cell contents given in row-major order
  401. * `selected idx`: index of row to be selected within table (first row = `1`)
  402. * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
  403. #### `tableoptions[<opt 1>;<opt 2>;...]`
  404. * Sets options for `table[]`
  405. * `color=#RRGGBB`
  406. * default text color (`ColorString`), defaults to `#FFFFFF`
  407. * `background=#RRGGBB`
  408. * table background color (`ColorString`), defaults to `#000000`
  409. * `border=<true/false>`
  410. * should the table be drawn with a border? (default: `true`)
  411. * `highlight=#RRGGBB`
  412. * highlight background color (`ColorString`), defaults to `#466432`
  413. * `highlight_text=#RRGGBB`
  414. * highlight text color (`ColorString`), defaults to `#FFFFFF`
  415. * `opendepth=<value>`
  416. * all subtrees up to `depth < value` are open (default value = `0`)
  417. * only useful when there is a column of type "tree"
  418. #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
  419. * Sets columns for `table[]`
  420. * Types: `text`, `image`, `color`, `indent`, `tree`
  421. * `text`: show cell contents as text
  422. * `image`: cell contents are an image index, use column options to define images
  423. * `color`: cell contents are a ColorString and define color of following cell
  424. * `indent`: cell contents are a number and define indentation of following cell
  425. * `tree`: same as indent, but user can open and close subtrees (treeview-like)
  426. * Column options:
  427. * `align=<value>`
  428. * for `text` and `image`: content alignment within cells.
  429. Available values: `left` (default), `center`, `right`, `inline`
  430. * `width=<value>`
  431. * for `text` and `image`: minimum width in em (default: `0`)
  432. * for `indent` and `tree`: indent width in em (default: `1.5`)
  433. * `padding=<value>`: padding left of the column, in em (default `0.5`).
  434. Exception: defaults to 0 for indent columns
  435. * `tooltip=<value>`: tooltip text (default: empty)
  436. * `image` column options:
  437. * `0=<value>` sets image for image index 0
  438. * `1=<value>` sets image for image index 1
  439. * `2=<value>` sets image for image index 2
  440. * and so on; defined indices need not be contiguous empty or
  441. non-numeric cells are treated as `0`.
  442. * `color` column options:
  443. * `span=<value>`: number of following columns to affect (default: infinite)
  444. **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
  445. pass key press events to formspec!
  446. Spatial Vectors
  447. ---------------
  448. * `vector.new(a[, b, c])`: returns a vector:
  449. * A copy of `a` if `a` is a vector.
  450. * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
  451. * `vector.direction(p1, p2)`: returns a vector
  452. * `vector.distance(p1, p2)`: returns a number
  453. * `vector.length(v)`: returns a number
  454. * `vector.normalize(v)`: returns a vector
  455. * `vector.floor(v)`: returns a vector, each dimension rounded down
  456. * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
  457. * `vector.apply(v, func)`: returns a vector
  458. * `vector.equals(v1, v2)`: returns a boolean
  459. For the following functions `x` can be either a vector or a number:
  460. * `vector.add(v, x)`: returns a vector
  461. * `vector.subtract(v, x)`: returns a vector
  462. * `vector.multiply(v, x)`: returns a scaled vector or Schur product
  463. * `vector.divide(v, x)`: returns a scaled vector or Schur quotient
  464. Helper functions
  465. ----------------
  466. * `dump2(obj, name="_", dumped={})`
  467. * Return object serialized as a string, handles reference loops
  468. * `dump(obj, dumped={})`
  469. * Return object serialized as a string
  470. * `math.hypot(x, y)`
  471. * Get the hypotenuse of a triangle with legs x and y.
  472. Useful for distance calculation.
  473. * `math.sign(x, tolerance)`
  474. * Get the sign of a number.
  475. Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
  476. * `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)`
  477. * If `max_splits` is negative, do not limit splits.
  478. * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
  479. * e.g. `string:split("a,b", ",") == {"a","b"}`
  480. * `string:trim()`
  481. * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
  482. * `minetest.wrap_text(str, limit)`: returns a string
  483. * Adds new lines to the string to keep it within the specified character limit
  484. * limit: Maximal amount of characters in one line
  485. * `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"`
  486. * Convert position to a printable string
  487. Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
  488. * `minetest.string_to_pos(string)`: returns a position
  489. * Same but in reverse. Returns `nil` if the string can't be parsed to a position.
  490. * `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
  491. * Converts a string representing an area box into two positions
  492. * `minetest.is_yes(arg)`
  493. * returns whether `arg` can be interpreted as yes
  494. * `table.copy(table)`: returns a table
  495. * returns a deep copy of `table`
  496. Minetest namespace reference
  497. ------------------------------
  498. ### Utilities
  499. * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
  500. * `minetest.get_language()`: returns the currently set gettext language.
  501. * `minetest.get_version()`: returns a table containing components of the
  502. engine version. Components:
  503. * `project`: Name of the project, eg, "Minetest"
  504. * `string`: Simple version, eg, "1.2.3-dev"
  505. * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
  506. Use this for informational purposes only. The information in the returned
  507. table does not represent the capabilities of the engine, nor is it
  508. reliable or verifiable. Compatible forks will have a different name and
  509. version entirely. To check for the presence of engine features, test
  510. whether the functions exported by the wanted features exist. For example:
  511. `if minetest.check_for_falling then ... end`.
  512. * `minetest.sha1(data, [raw])`: returns the sha1 hash of data
  513. * `data`: string of data to hash
  514. * `raw`: return raw bytes instead of hex digits, default: false
  515. ### Logging
  516. * `minetest.debug(...)`
  517. * Equivalent to `minetest.log(table.concat({...}, "\t"))`
  518. * `minetest.log([level,] text)`
  519. * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
  520. `"info"`, or `"verbose"`. Default is `"none"`.
  521. ### Global callback registration functions
  522. Call these functions only at load time!
  523. * `minetest.register_globalstep(func(dtime))`
  524. * Called every client environment step, usually interval of 0.1s
  525. * `minetest.register_on_shutdown(func())`
  526. * Called before client shutdown
  527. * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
  528. callbacks **will likely not be run**. Data should be saved at
  529. semi-frequent intervals as well as on server shutdown.
  530. * `minetest.register_on_connect(func())`
  531. * Called at the end of client connection (when player is loaded onto map)
  532. * `minetest.register_on_receiving_chat_message(func(message))`
  533. * Called always when a client receive a message
  534. * Return `true` to mark the message as handled, which means that it will not be shown to chat
  535. * `minetest.register_on_sending_chat_message(func(message))`
  536. * Called always when a client send a message from chat
  537. * Return `true` to mark the message as handled, which means that it will not be sent to server
  538. * `minetest.register_chatcommand(cmd, chatcommand definition)`
  539. * Adds definition to minetest.registered_chatcommands
  540. * `minetest.unregister_chatcommand(name)`
  541. * Unregisters a chatcommands registered with register_chatcommand.
  542. * `minetest.register_on_death(func())`
  543. * Called when the local player dies
  544. * `minetest.register_on_hp_modification(func(hp))`
  545. * Called when server modified player's HP
  546. * `minetest.register_on_damage_taken(func(hp))`
  547. * Called when the local player take damages
  548. * `minetest.register_on_formspec_input(func(formname, fields))`
  549. * Called when a button is pressed in the local player's inventory form
  550. * Newest functions are called first
  551. * If function returns `true`, remaining functions are not called
  552. * `minetest.register_on_dignode(func(pos, node))`
  553. * Called when the local player digs a node
  554. * Newest functions are called first
  555. * If any function returns true, the node isn't dug
  556. * `minetest.register_on_punchnode(func(pos, node))`
  557. * Called when the local player punches a node
  558. * Newest functions are called first
  559. * If any function returns true, the punch is ignored
  560. * `minetest.register_on_placenode(function(pointed_thing, node))`
  561. * Called when a node has been placed
  562. * `minetest.register_on_item_use(func(item, pointed_thing))`
  563. * Called when the local player uses an item.
  564. * Newest functions are called first.
  565. * If any function returns true, the item use is not sent to server.
  566. * `minetest.register_on_modchannel_message(func(channel_name, sender, message))`
  567. * Called when an incoming mod channel message is received
  568. * You must have joined some channels before, and server must acknowledge the
  569. join request.
  570. * If message comes from a server mod, `sender` field is an empty string.
  571. * `minetest.register_on_modchannel_signal(func(channel_name, signal))`
  572. * Called when a valid incoming mod channel signal is received
  573. * Signal id permit to react to server mod channel events
  574. * Possible values are:
  575. 0: join_ok
  576. 1: join_failed
  577. 2: leave_ok
  578. 3: leave_failed
  579. 4: event_on_not_joined_channel
  580. 5: state_changed
  581. * `minetest.register_on_inventory_open(func(inventory))`
  582. * Called when the local player open inventory
  583. * Newest functions are called first
  584. * If any function returns true, inventory doesn't open
  585. ### Sounds
  586. * `minetest.sound_play(spec, parameters)`: returns a handle
  587. * `spec` is a `SimpleSoundSpec`
  588. * `parameters` is a sound parameter table
  589. * `minetest.sound_stop(handle)`
  590. ### Timing
  591. * `minetest.after(time, func, ...)`
  592. * Call the function `func` after `time` seconds, may be fractional
  593. * Optional: Variable number of arguments that are passed to `func`
  594. * `minetest.get_us_time()`
  595. * Returns time with microsecond precision. May not return wall time.
  596. * `minetest.get_day_count()`
  597. * Returns number days elapsed since world was created, accounting for time changes.
  598. * `minetest.get_timeofday()`
  599. * Returns the time of day: `0` for midnight, `0.5` for midday
  600. ### Map
  601. * `minetest.get_node_or_nil(pos)`
  602. * Returns the node at the given position as table in the format
  603. `{name="node_name", param1=0, param2=0}`, returns `nil`
  604. for unloaded areas or flavor limited areas.
  605. * `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
  606. * `radius`: using a maximum metric
  607. * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
  608. * `search_center` is an optional boolean (default: `false`)
  609. If true `pos` is also checked for the nodes
  610. * `minetest.get_meta(pos)`
  611. * Get a `NodeMetaRef` at that position
  612. * `minetest.get_node_level(pos)`
  613. * get level of leveled node (water, snow)
  614. * `minetest.get_node_max_level(pos)`
  615. * get max available level for leveled node
  616. ### Player
  617. * `minetest.get_wielded_item()`
  618. * Returns the itemstack the local player is holding
  619. * `minetest.send_chat_message(message)`
  620. * Act as if `message` was typed by the player into the terminal.
  621. * `minetest.run_server_chatcommand(cmd, param)`
  622. * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)`
  623. * `minetest.clear_out_chat_queue()`
  624. * Clears the out chat queue
  625. * `minetest.localplayer`
  626. * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
  627. ### Privileges
  628. * `minetest.get_privilege_list()`
  629. * Returns a list of privileges the current player has in the format `{priv1=true,...}`
  630. * `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
  631. * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
  632. * Convert between two privilege representations
  633. ### Client Environment
  634. * `minetest.get_player_names()`
  635. * Returns list of player names on server
  636. * `minetest.disconnect()`
  637. * Disconnect from the server and exit to main menu.
  638. * Returns `false` if the client is already disconnecting otherwise returns `true`.
  639. * `minetest.take_screenshot()`
  640. * Take a screenshot.
  641. * `minetest.get_server_info()`
  642. * Returns [server info](#server-info).
  643. * `minetest.send_respawn()`
  644. * Sends a respawn request to the server.
  645. ### Storage API
  646. * `minetest.get_mod_storage()`:
  647. * returns reference to mod private `StorageRef`
  648. * must be called during mod load time
  649. ### Mod channels
  650. ![Mod channels communication scheme](docs/mod channels.png)
  651. * `minetest.mod_channel_join(channel_name)`
  652. * Client joins channel `channel_name`, and creates it, if necessary. You
  653. should listen from incoming messages with `minetest.register_on_modchannel_message`
  654. call to receive incoming messages. Warning, this function is asynchronous.
  655. * You should use a minetest.register_on_connect(function() ... end) to perform
  656. a successful channel join on client startup.
  657. ### Misc.
  658. * `minetest.parse_json(string[, nullvalue])`: returns something
  659. * Convert a string containing JSON data into the Lua equivalent
  660. * `nullvalue`: returned in place of the JSON null; defaults to `nil`
  661. * On success returns a table, a string, a number, a boolean or `nullvalue`
  662. * On failure outputs an error message and returns `nil`
  663. * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
  664. * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
  665. * Convert a Lua table into a JSON string
  666. * styled: Outputs in a human-readable format if this is set, defaults to false
  667. * Unserializable things like functions and userdata are saved as null.
  668. * **Warning**: JSON is more strict than the Lua table format.
  669. 1. You can only use strings and positive integers of at least one as keys.
  670. 2. You can not mix string and integer keys.
  671. This is due to the fact that JSON has two distinct array and object values.
  672. * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
  673. * `minetest.serialize(table)`: returns a string
  674. * Convert a table containing tables, strings, numbers, booleans and `nil`s
  675. into string form readable by `minetest.deserialize`
  676. * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
  677. * `minetest.deserialize(string)`: returns a table
  678. * Convert a string returned by `minetest.deserialize` into a table
  679. * `string` is loaded in an empty sandbox environment.
  680. * Will load functions, but they cannot access the global environment.
  681. * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
  682. * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
  683. * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
  684. * `minetest.compress(data, method, ...)`: returns `compressed_data`
  685. * Compress a string of data.
  686. * `method` is a string identifying the compression method to be used.
  687. * Supported compression methods:
  688. * Deflate (zlib): `"deflate"`
  689. * `...` indicates method-specific arguments. Currently defined arguments are:
  690. * Deflate: `level` - Compression level, `0`-`9` or `nil`.
  691. * `minetest.decompress(compressed_data, method, ...)`: returns data
  692. * Decompress a string of data (using ZLib).
  693. * See documentation on `minetest.compress()` for supported compression methods.
  694. * currently supported.
  695. * `...` indicates method-specific arguments. Currently, no methods use this.
  696. * `minetest.rgba(red, green, blue[, alpha])`: returns a string
  697. * Each argument is a 8 Bit unsigned integer
  698. * Returns the ColorString from rgb or rgba values
  699. * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
  700. * `minetest.encode_base64(string)`: returns string encoded in base64
  701. * Encodes a string in base64.
  702. * `minetest.decode_base64(string)`: returns string
  703. * Decodes a string encoded in base64.
  704. * `minetest.gettext(string)` : returns string
  705. * look up the translation of a string in the gettext message catalog
  706. * `fgettext_ne(string, ...)`
  707. * call minetest.gettext(string), replace "$1"..."$9" with the given
  708. extra arguments and return the result
  709. * `fgettext(string, ...)` : returns string
  710. * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
  711. * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
  712. * returns the exact position on the surface of a pointed node
  713. * `minetest.global_exists(name)`
  714. * Checks if a global variable has been set, without triggering a warning.
  715. ### UI
  716. * `minetest.ui.minimap`
  717. * Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods.
  718. * If client disabled minimap (using enable_minimap setting) this reference will be nil.
  719. * `minetest.camera`
  720. * Reference to the camera object. See [`Camera`](#camera) class reference for methods.
  721. * `minetest.show_formspec(formname, formspec)` : returns true on success
  722. * Shows a formspec to the player
  723. * `minetest.display_chat_message(message)` returns true on success
  724. * Shows a chat message to the current player.
  725. Class reference
  726. ---------------
  727. ### ModChannel
  728. An interface to use mod channels on client and server
  729. #### Methods
  730. * `leave()`: leave the mod channel.
  731. * Client leaves channel `channel_name`.
  732. * No more incoming or outgoing messages can be sent to this channel from client mods.
  733. * This invalidate all future object usage
  734. * Ensure your set mod_channel to nil after that to free Lua resources
  735. * `is_writeable()`: returns true if channel is writable and mod can send over it.
  736. * `send_all(message)`: Send `message` though the mod channel.
  737. * If mod channel is not writable or invalid, message will be dropped.
  738. * Message size is limited to 65535 characters by protocol.
  739. ### Minimap
  740. An interface to manipulate minimap on client UI
  741. #### Methods
  742. * `show()`: shows the minimap (if not disabled by server)
  743. * `hide()`: hides the minimap
  744. * `set_pos(pos)`: sets the minimap position on screen
  745. * `get_pos()`: returns the minimap current position
  746. * `set_angle(deg)`: sets the minimap angle in degrees
  747. * `get_angle()`: returns the current minimap angle in degrees
  748. * `set_mode(mode)`: sets the minimap mode (0 to 6)
  749. * `get_mode()`: returns the current minimap mode
  750. * `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round)
  751. * `get_shape()`: Gets the minimap shape. (0 = square, 1 = round)
  752. ### Camera
  753. An interface to get or set information about the camera and camera-node.
  754. Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.
  755. #### Methods
  756. * `set_camera_mode(mode)`
  757. * Pass `0` for first-person, `1` for third person, and `2` for third person front
  758. * `get_camera_mode()`
  759. * Returns 0, 1, or 2 as described above
  760. * `get_fov()`
  761. * Returns:
  762. ```lua
  763. {
  764. x = number,
  765. y = number,
  766. max = number,
  767. actual = number
  768. }
  769. ```
  770. * `get_pos()`
  771. * Returns position of camera with view bobbing
  772. * `get_offset()`
  773. * Returns eye offset vector
  774. * `get_look_dir()`
  775. * Returns eye direction unit vector
  776. * `get_look_vertical()`
  777. * Returns pitch in radians
  778. * `get_look_horizontal()`
  779. * Returns yaw in radians
  780. * `get_aspect_ratio()`
  781. * Returns aspect ratio of screen
  782. ### LocalPlayer
  783. An interface to retrieve information about the player. The player is
  784. not accessible until the client is fully done loading and therefore
  785. not at module init time.
  786. To get the localplayer handle correctly, use `on_connect()` as follows:
  787. ```lua
  788. local localplayer
  789. minetest.register_on_connect(function()
  790. localplayer = minetest.localplayer
  791. end)
  792. ```
  793. Methods:
  794. * `get_pos()`
  795. * returns current player current position
  796. * `get_velocity()`
  797. * returns player speed vector
  798. * `get_hp()`
  799. * returns player HP
  800. * `get_name()`
  801. * returns player name
  802. * `is_attached()`
  803. * returns true if player is attached
  804. * `is_touching_ground()`
  805. * returns true if player touching ground
  806. * `is_in_liquid()`
  807. * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)
  808. * `is_in_liquid_stable()`
  809. * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
  810. * `get_liquid_viscosity()`
  811. * returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
  812. * `is_climbing()`
  813. * returns true if player is climbing
  814. * `swimming_vertical()`
  815. * returns true if player is swimming in vertical
  816. * `get_physics_override()`
  817. * returns:
  818. ```lua
  819. {
  820. speed = float,
  821. jump = float,
  822. gravity = float,
  823. sneak = boolean,
  824. sneak_glitch = boolean
  825. }
  826. ```
  827. * `get_override_pos()`
  828. * returns override position
  829. * `get_last_pos()`
  830. * returns last player position before the current client step
  831. * `get_last_velocity()`
  832. * returns last player speed
  833. * `get_breath()`
  834. * returns the player's breath
  835. * `get_movement_acceleration()`
  836. * returns acceleration of the player in different environments:
  837. ```lua
  838. {
  839. fast = float,
  840. air = float,
  841. default = float,
  842. }
  843. ```
  844. * `get_movement_speed()`
  845. * returns player's speed in different environments:
  846. ```lua
  847. {
  848. walk = float,
  849. jump = float,
  850. crouch = float,
  851. fast = float,
  852. climb = float,
  853. }
  854. ```
  855. * `get_movement()`
  856. * returns player's movement in different environments:
  857. ```lua
  858. {
  859. liquid_fluidity = float,
  860. liquid_sink = float,
  861. liquid_fluidity_smooth = float,
  862. gravity = float,
  863. }
  864. ```
  865. * `get_last_look_horizontal()`:
  866. * returns last look horizontal angle
  867. * `get_last_look_vertical()`:
  868. * returns last look vertical angle
  869. * `get_key_pressed()`:
  870. * returns last key typed by the player
  871. ### Settings
  872. An interface to read config files in the format of `minetest.conf`.
  873. It can be created via `Settings(filename)`.
  874. #### Methods
  875. * `get(key)`: returns a value
  876. * `get_bool(key)`: returns a boolean
  877. * `set(key, value)`
  878. * `remove(key)`: returns a boolean (`true` for success)
  879. * `get_names()`: returns `{key1,...}`
  880. * `write()`: returns a boolean (`true` for success)
  881. * write changes to file
  882. * `to_table()`: returns `{[key1]=value1,...}`
  883. ### NodeMetaRef
  884. Node metadata: reference extra data and functionality stored in a node.
  885. Can be obtained via `minetest.get_meta(pos)`.
  886. #### Methods
  887. * `get_string(name)`
  888. * `get_int(name)`
  889. * `get_float(name)`
  890. * `to_table()`: returns `nil` or a table with keys:
  891. * `fields`: key-value storage
  892. * `inventory`: `{list1 = {}, ...}}`
  893. -----------------
  894. ### Definitions
  895. * `minetest.get_node_def(nodename)`
  896. * Returns [node definition](#node-definition) table of `nodename`
  897. * `minetest.get_item_def(itemstring)`
  898. * Returns item definition table of `itemstring`
  899. #### Node Definition
  900. ```lua
  901. {
  902. has_on_construct = bool, -- Whether the node has the on_construct callback defined
  903. has_on_destruct = bool, -- Whether the node has the on_destruct callback defined
  904. has_after_destruct = bool, -- Whether the node has the after_destruct callback defined
  905. name = string, -- The name of the node e.g. "air", "default:dirt"
  906. groups = table, -- The groups of the node
  907. paramtype = string, -- Paramtype of the node
  908. paramtype2 = string, -- ParamType2 of the node
  909. drawtype = string, -- Drawtype of the node
  910. mesh = <string>, -- Mesh name if existant
  911. minimap_color = <Color>, -- Color of node on minimap *May not exist*
  912. visual_scale = number, -- Visual scale of node
  913. alpha = number, -- Alpha of the node. Only used for liquids
  914. color = <Color>, -- Color of node *May not exist*
  915. palette_name = <string>, -- Filename of palette *May not exist*
  916. palette = <{ -- List of colors
  917. Color,
  918. Color
  919. }>,
  920. waving = number, -- 0 of not waving, 1 if waving
  921. connect_sides = number, -- Used for connected nodes
  922. connects_to = { -- List of nodes to connect to
  923. "node1",
  924. "node2"
  925. },
  926. post_effect_color = Color, -- Color overlayed on the screen when the player is in the node
  927. leveled = number, -- Max level for node
  928. sunlight_propogates = bool, -- Whether light passes through the block
  929. light_source = number, -- Light emitted by the block
  930. is_ground_content = bool, -- Whether caves should cut through the node
  931. walkable = bool, -- Whether the player collides with the node
  932. pointable = bool, -- Whether the player can select the node
  933. diggable = bool, -- Whether the player can dig the node
  934. climbable = bool, -- Whether the player can climb up the node
  935. buildable_to = bool, -- Whether the player can replace the node by placing a node on it
  936. rightclickable = bool, -- Whether the player can place nodes pointing at this node
  937. damage_per_second = number, -- HP of damage per second when the player is in the node
  938. liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist*
  939. liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
  940. liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
  941. liquid_viscosity = <number>, -- How fast the liquid flows *May not exist*
  942. liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist*
  943. liquid_range = <number>, -- How far the liquid flows *May not exist*
  944. drowning = bool, -- Whether the player will drown in the node
  945. floodable = bool, -- Whether nodes will be replaced by liquids (flooded)
  946. node_box = table, -- Nodebox to draw the node with
  947. collision_box = table, -- Nodebox to set the collision area
  948. selection_box = table, -- Nodebox to set the area selected by the player
  949. sounds = { -- Table of sounds that the block makes
  950. sound_footstep = SimpleSoundSpec,
  951. sound_dig = SimpleSoundSpec,
  952. sound_dug = SimpleSoundSpec
  953. },
  954. legacy_facedir_simple = bool, -- Whether to use old facedir
  955. legacy_wallmounted = bool -- Whether to use old wallmounted
  956. }
  957. ```
  958. #### Item Definition
  959. ```lua
  960. {
  961. name = string, -- Name of the item e.g. "default:stone"
  962. description = string, -- Description of the item e.g. "Stone"
  963. type = string, -- Item type: "none", "node", "craftitem", "tool"
  964. inventory_image = string, -- Image in the inventory
  965. wield_image = string, -- Image in wieldmesh
  966. palette_image = string, -- Image for palette
  967. color = Color, -- Color for item
  968. wield_scale = Vector, -- Wieldmesh scale
  969. stack_max = number, -- Number of items stackable together
  970. usable = bool, -- Has on_use callback defined
  971. liquids_pointable = bool, -- Whether you can point at liquids with the item
  972. tool_capabilities = <table>, -- If the item is a tool, tool capabilities of the item
  973. groups = table, -- Groups of the item
  974. sound_place = SimpleSoundSpec, -- Sound played when placed
  975. sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed
  976. node_placement_prediction = string -- Node placed in client until server catches up
  977. }
  978. ```
  979. -----------------
  980. ### Chat command definition (`register_chatcommand`)
  981. {
  982. params = "<name> <privilege>", -- Short parameter description
  983. description = "Remove privilege from player", -- Full description
  984. func = function(param), -- Called when command is run.
  985. -- Returns boolean success and text output.
  986. }
  987. ### Server info
  988. ```lua
  989. {
  990. address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
  991. ip = "203.0.113.156", -- The IP address of the server.
  992. port = 30000, -- The port the client is connected to.
  993. protocol_version = 30 -- Will not be accurate at start up as the client might not be connected to the server yet, in that case it will be 0.
  994. }
  995. ```
  996. Escape sequences
  997. ----------------
  998. Most text can contain escape sequences, that can for example color the text.
  999. There are a few exceptions: tab headers, dropdowns and vertical labels can't.
  1000. The following functions provide escape sequences:
  1001. * `minetest.get_color_escape_sequence(color)`:
  1002. * `color` is a [ColorString](#colorstring)
  1003. * The escape sequence sets the text color to `color`
  1004. * `minetest.colorize(color, message)`:
  1005. * Equivalent to:
  1006. `minetest.get_color_escape_sequence(color) ..
  1007. message ..
  1008. minetest.get_color_escape_sequence("#ffffff")`
  1009. * `minetest.get_background_escape_sequence(color)`
  1010. * `color` is a [ColorString](#colorstring)
  1011. * The escape sequence sets the background of the whole text element to
  1012. `color`. Only defined for item descriptions and tooltips.
  1013. * `minetest.strip_foreground_colors(str)`
  1014. * Removes foreground colors added by `get_color_escape_sequence`.
  1015. * `minetest.strip_background_colors(str)`
  1016. * Removes background colors added by `get_background_escape_sequence`.
  1017. * `minetest.strip_colors(str)`
  1018. * Removes all color escape sequences.
  1019. `ColorString`
  1020. -------------
  1021. `#RGB` defines a color in hexadecimal format.
  1022. `#RGBA` defines a color in hexadecimal format and alpha channel.
  1023. `#RRGGBB` defines a color in hexadecimal format.
  1024. `#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
  1025. Named colors are also supported and are equivalent to
  1026. [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
  1027. To specify the value of the alpha channel, append `#AA` to the end of the color name
  1028. (e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
  1029. value must (always) be two hexadecimal digits.
  1030. `Color`
  1031. -------------
  1032. `{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color.