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.

client_lua_api.txt 47KB

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