client_lua_api.txt 62 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519
  1. Minetest Lua Client Modding API Reference 5.6.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. In order to load client-side mods, the following conditions need to be satisfied:
  25. 1) `$path_user/minetest.conf` contains the setting `enable_client_modding = true`
  26. 2) The client-side mod located in `$path_user/clientmods/<modname>` is added to
  27. `$path_user/clientmods/mods.conf` as `load_mod_<modname> = true`.
  28. Note: Depending on the remote server's settings, client-side mods might not
  29. be loaded or have limited functionality. See setting `csm_restriction_flags` for reference.
  30. Paths
  31. -----
  32. * `RUN_IN_PLACE=1` (Windows release, local build)
  33. * `$path_user`: `<build directory>`
  34. * `$path_share`: `<build directory>`
  35. * `RUN_IN_PLACE=0`: (Linux release)
  36. * `$path_share`:
  37. * Linux: `/usr/share/minetest`
  38. * Windows: `<install directory>/minetest-0.4.x`
  39. * `$path_user`:
  40. * Linux: `$HOME/.minetest`
  41. * Windows: `C:/users/<user>/AppData/minetest` (maybe)
  42. Mod load path
  43. -------------
  44. Generic:
  45. * `$path_share/clientmods/`
  46. * `$path_user/clientmods/` (User-installed mods)
  47. In a run-in-place version (e.g. the distributed windows version):
  48. * `minetest-0.4.x/clientmods/` (User-installed mods)
  49. On an installed version on Linux:
  50. * `/usr/share/minetest/clientmods/`
  51. * `$HOME/.minetest/clientmods/` (User-installed mods)
  52. Modpack support
  53. ----------------
  54. Mods can be put in a subdirectory, if the parent directory, which otherwise
  55. should be a mod, contains a file named `modpack.conf`.
  56. The file is a key-value store of modpack details.
  57. * `name`: The modpack name.
  58. * `description`: Description of mod to be shown in the Mods tab of the main
  59. menu.
  60. Mod directory structure
  61. ------------------------
  62. clientmods
  63. ├── modname
  64. │   ├── mod.conf
  65. │   ├── init.lua
  66. └── another
  67. ### modname
  68. The location of this directory.
  69. ### mod.conf
  70. An (optional) settings file that provides meta information about the mod.
  71. * `name`: The mod name. Allows Minetest to determine the mod name even if the
  72. folder is wrongly named.
  73. * `description`: Description of mod to be shown in the Mods tab of the main
  74. menu.
  75. * `depends`: A comma separated list of dependencies. These are mods that must be
  76. loaded before this mod.
  77. * `optional_depends`: A comma separated list of optional dependencies.
  78. Like a dependency, but no error if the mod doesn't exist.
  79. ### `init.lua`
  80. The main Lua script. Running this script should register everything it
  81. wants to register. Subsequent execution depends on minetest calling the
  82. registered callbacks.
  83. **NOTE**: Client mods currently can't provide textures, sounds, or models by
  84. themselves. Any media referenced in function calls must already be loaded
  85. (provided by mods that exist on the server).
  86. Naming convention for registered textual names
  87. ----------------------------------------------
  88. Registered names should generally be in this format:
  89. "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
  90. This is to prevent conflicting names from corrupting maps and is
  91. enforced by the mod loader.
  92. ### Example
  93. In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
  94. So the name should be `experimental:tnt`.
  95. Enforcement can be overridden by prefixing the name with `:`. This can
  96. be used for overriding the registrations of some other mod.
  97. Example: Any mod can redefine `experimental:tnt` by using the name
  98. :experimental:tnt
  99. when registering it.
  100. (also that mod is required to have `experimental` as a dependency)
  101. The `:` prefix can also be used for maintaining backwards compatibility.
  102. Sounds
  103. ------
  104. **NOTE: Connecting sounds to objects is not implemented.**
  105. Only Ogg Vorbis files are supported.
  106. For positional playing of sounds, only single-channel (mono) files are
  107. supported. Otherwise OpenAL will play them non-positionally.
  108. Mods should generally prefix their sounds with `modname_`, e.g. given
  109. the mod name "`foomod`", a sound could be called:
  110. foomod_foosound.ogg
  111. Sounds are referred to by their name with a dot, a single digit and the
  112. file extension stripped out. When a sound is played, the actual sound file
  113. is chosen randomly from the matching sounds.
  114. When playing the sound `foomod_foosound`, the sound is chosen randomly
  115. from the available ones of the following files:
  116. * `foomod_foosound.ogg`
  117. * `foomod_foosound.0.ogg`
  118. * `foomod_foosound.1.ogg`
  119. * (...)
  120. * `foomod_foosound.9.ogg`
  121. Examples of sound parameter tables:
  122. -- Play locationless
  123. {
  124. gain = 1.0, -- default
  125. }
  126. -- Play locationless, looped
  127. {
  128. gain = 1.0, -- default
  129. loop = true,
  130. }
  131. -- Play in a location
  132. {
  133. pos = {x = 1, y = 2, z = 3},
  134. gain = 1.0, -- default
  135. }
  136. -- Play connected to an object, looped
  137. {
  138. object = <an ObjectRef>,
  139. gain = 1.0, -- default
  140. loop = true,
  141. }
  142. Looped sounds must either be connected to an object or played locationless.
  143. ### SimpleSoundSpec
  144. * e.g. `""`
  145. * e.g. `"default_place_node"`
  146. * e.g. `{}`
  147. * e.g. `{name = "default_place_node"}`
  148. * e.g. `{name = "default_place_node", gain = 1.0}`
  149. Representations of simple things
  150. --------------------------------
  151. ### Position/vector
  152. {x=num, y=num, z=num}
  153. For helper functions see "Vector helpers".
  154. ### pointed_thing
  155. * `{type="nothing"}`
  156. * `{type="node", under=pos, above=pos}`
  157. * `{type="object", id=ObjectID}`
  158. Flag Specifier Format
  159. ---------------------
  160. Flags using the standardized flag specifier format can be specified in either of
  161. two ways, by string or table.
  162. The string format is a comma-delimited set of flag names; whitespace and
  163. unrecognized flag fields are ignored. Specifying a flag in the string sets the
  164. flag, and specifying a flag prefixed by the string `"no"` explicitly
  165. clears the flag from whatever the default may be.
  166. In addition to the standard string flag format, the schematic flags field can
  167. also be a table of flag names to boolean values representing whether or not the
  168. flag is set. Additionally, if a field with the flag name prefixed with `"no"`
  169. is present, mapped to a boolean of any value, the specified flag is unset.
  170. E.g. A flag field of value
  171. {place_center_x = true, place_center_y=false, place_center_z=true}
  172. is equivalent to
  173. {place_center_x = true, noplace_center_y=true, place_center_z=true}
  174. which is equivalent to
  175. "place_center_x, noplace_center_y, place_center_z"
  176. or even
  177. "place_center_x, place_center_z"
  178. since, by default, no schematic attributes are set.
  179. Formspec
  180. --------
  181. Formspec defines a menu. It is a string, with a somewhat strange format.
  182. Spaces and newlines can be inserted between the blocks, as is used in the
  183. examples.
  184. ### Examples
  185. #### Chest
  186. size[8,9]
  187. list[context;main;0,0;8,4;]
  188. list[current_player;main;0,5;8,4;]
  189. #### Furnace
  190. size[8,9]
  191. list[context;fuel;2,3;1,1;]
  192. list[context;src;2,1;1,1;]
  193. list[context;dst;5,1;2,2;]
  194. list[current_player;main;0,5;8,4;]
  195. #### Minecraft-like player inventory
  196. size[8,7.5]
  197. image[1,0.6;1,2;player.png]
  198. list[current_player;main;0,3.5;8,4;]
  199. list[current_player;craft;3,0;3,3;]
  200. list[current_player;craftpreview;7,1;1,1;]
  201. ### Elements
  202. #### `size[<W>,<H>,<fixed_size>]`
  203. * Define the size of the menu in inventory slots
  204. * `fixed_size`: `true`/`false` (optional)
  205. * deprecated: `invsize[<W>,<H>;]`
  206. #### `container[<X>,<Y>]`
  207. * Start of a container block, moves all physical elements in the container by (X, Y)
  208. * Must have matching container_end
  209. * Containers can be nested, in which case the offsets are added
  210. (child containers are relative to parent containers)
  211. #### `container_end[]`
  212. * End of a container, following elements are no longer relative to this container
  213. #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]`
  214. * Show an inventory list
  215. #### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
  216. * Show an inventory list
  217. #### `listring[<inventory location>;<list name>]`
  218. * Allows to create a ring of inventory lists
  219. * Shift-clicking on items in one element of the ring
  220. will send them to the next inventory list inside the ring
  221. * The first occurrence of an element inside the ring will
  222. determine the inventory where items will be sent to
  223. #### `listring[]`
  224. * Shorthand for doing `listring[<inventory location>;<list name>]`
  225. for the last two inventory lists added by list[...]
  226. #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]`
  227. * Sets background color of slots as `ColorString`
  228. * Sets background color of slots on mouse hovering
  229. #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]`
  230. * Sets background color of slots as `ColorString`
  231. * Sets background color of slots on mouse hovering
  232. * Sets color of slots border
  233. #### `listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]`
  234. * Sets background color of slots as `ColorString`
  235. * Sets background color of slots on mouse hovering
  236. * Sets color of slots border
  237. * Sets default background color of tooltips
  238. * Sets default font color of tooltips
  239. #### `tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]`
  240. * Adds tooltip for an element
  241. * `<bgcolor>` tooltip background color as `ColorString` (optional)
  242. * `<fontcolor>` tooltip font color as `ColorString` (optional)
  243. #### `image[<X>,<Y>;<W>,<H>;<texture name>]`
  244. * Show an image
  245. * Position and size units are inventory slots
  246. #### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
  247. * Show an inventory image of registered item/node
  248. * Position and size units are inventory slots
  249. #### `bgcolor[<color>;<fullscreen>]`
  250. * Sets background color of formspec as `ColorString`
  251. * If `true`, the background color is drawn fullscreen (does not effect the size of the formspec)
  252. #### `background[<X>,<Y>;<W>,<H>;<texture name>]`
  253. * Use a background. Inventory rectangles are not drawn then.
  254. * Position and size units are inventory slots
  255. * Example for formspec 8x4 in 16x resolution: image shall be sized
  256. 8 times 16px times 4 times 16px.
  257. #### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]`
  258. * Use a background. Inventory rectangles are not drawn then.
  259. * Position and size units are inventory slots
  260. * Example for formspec 8x4 in 16x resolution:
  261. image shall be sized 8 times 16px times 4 times 16px
  262. * If `true` the background is clipped to formspec size
  263. (`x` and `y` are used as offset values, `w` and `h` are ignored)
  264. #### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
  265. * Textual password style field; will be sent to server when a button is clicked
  266. * When enter is pressed in field, fields.key_enter_field will be sent with the name
  267. of this field.
  268. * `x` and `y` position the field relative to the top left of the menu
  269. * `w` and `h` are the size of the field
  270. * Fields are a set height, but will be vertically centred on `h`
  271. * Position and size units are inventory slots
  272. * `name` is the name of the field as returned in fields to `on_receive_fields`
  273. * `label`, if not blank, will be text printed on the top left above the field
  274. * See field_close_on_enter to stop enter closing the formspec
  275. #### `field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
  276. * Textual field; will be sent to server when a button is clicked
  277. * When enter is pressed in field, fields.key_enter_field will be sent with the name
  278. of this field.
  279. * `x` and `y` position the field relative to the top left of the menu
  280. * `w` and `h` are the size of the field
  281. * Fields are a set height, but will be vertically centred on `h`
  282. * Position and size units are inventory slots
  283. * `name` is the name of the field as returned in fields to `on_receive_fields`
  284. * `label`, if not blank, will be text printed on the top left above the field
  285. * `default` is the default value of the field
  286. * `default` may contain variable references such as `${text}'` which
  287. will fill the value from the metadata value `text`
  288. * **Note**: no extra text or more than a single variable is supported ATM.
  289. * See field_close_on_enter to stop enter closing the formspec
  290. #### `field[<name>;<label>;<default>]`
  291. * As above, but without position/size units
  292. * When enter is pressed in field, fields.key_enter_field will be sent with the name
  293. of this field.
  294. * Special field for creating simple forms, such as sign text input
  295. * Must be used without a `size[]` element
  296. * A "Proceed" button will be added automatically
  297. * See field_close_on_enter to stop enter closing the formspec
  298. #### `field_close_on_enter[<name>;<close_on_enter>]`
  299. * <name> is the name of the field
  300. * if <close_on_enter> is false, pressing enter in the field will submit the form but not close it
  301. * defaults to true when not specified (ie: no tag for a field)
  302. #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
  303. * Same as fields above, but with multi-line input
  304. #### `label[<X>,<Y>;<label>]`
  305. * `x` and `y` work as per field
  306. * `label` is the text on the label
  307. * Position and size units are inventory slots
  308. #### `vertlabel[<X>,<Y>;<label>]`
  309. * Textual label drawn vertically
  310. * `x` and `y` work as per field
  311. * `label` is the text on the label
  312. * Position and size units are inventory slots
  313. #### `button[<X>,<Y>;<W>,<H>;<name>;<label>]`
  314. * Clickable button. When clicked, fields will be sent.
  315. * `x`, `y` and `name` work as per field
  316. * `w` and `h` are the size of the button
  317. * Fixed button height. It will be vertically centred on `h`
  318. * `label` is the text on the button
  319. * Position and size units are inventory slots
  320. #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
  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. #### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]`
  325. * `x`, `y`, `w`, `h`, and `name` work as per button
  326. * `texture name` is the filename of an image
  327. * Position and size units are inventory slots
  328. * `noclip=true` means the image button doesn't need to be within specified formsize
  329. * `drawborder`: draw button border or not
  330. * `pressed texture name` is the filename of an image on pressed state
  331. #### `item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]`
  332. * `x`, `y`, `w`, `h`, `name` and `label` work as per button
  333. * `item name` is the registered name of an item/node,
  334. tooltip will be made out of its description
  335. to override it use tooltip element
  336. * Position and size units are inventory slots
  337. #### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]`
  338. * When clicked, fields will be sent and the form will quit.
  339. #### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]`
  340. * When clicked, fields will be sent and the form will quit.
  341. #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]`
  342. * Scrollable item list showing arbitrary text elements
  343. * `x` and `y` position the itemlist relative to the top left of the menu
  344. * `w` and `h` are the size of the itemlist
  345. * `name` fieldname sent to server on doubleclick value is current selected element
  346. * `listelements` can be prepended by #color in hexadecimal format RRGGBB (only),
  347. * if you want a listelement to start with "#" write "##".
  348. #### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]`
  349. * Scrollable itemlist showing arbitrary text elements
  350. * `x` and `y` position the item list relative to the top left of the menu
  351. * `w` and `h` are the size of the item list
  352. * `name` fieldname sent to server on doubleclick value is current selected element
  353. * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format
  354. * if you want a listelement to start with "#" write "##"
  355. * Index to be selected within textlist
  356. * `true`/`false`: draw transparent background
  357. * See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`)
  358. #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]`
  359. * Show a tab**header** at specific position (ignores formsize)
  360. * `x` and `y` position the itemlist relative to the top left of the menu
  361. * `name` fieldname data is transferred to Lua
  362. * `caption 1`...: name shown on top of tab
  363. * `current_tab`: index of selected tab 1...
  364. * `transparent` (optional): show transparent
  365. * `draw_border` (optional): draw border
  366. #### `box[<X>,<Y>;<W>,<H>;<color>]`
  367. * Simple colored semitransparent box
  368. * `x` and `y` position the box relative to the top left of the menu
  369. * `w` and `h` are the size of box
  370. * `color` is color specified as a `ColorString`
  371. #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]`
  372. * Show a dropdown field
  373. * **Important note**: There are two different operation modes:
  374. 1. handle directly on change (only changed dropdown is submitted)
  375. 2. read the value on pressing a button (all dropdown values are available)
  376. * `x` and `y` position of dropdown
  377. * Width of dropdown
  378. * Fieldname data is transferred to Lua
  379. * Items to be shown in dropdown
  380. * Index of currently selected dropdown item
  381. #### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
  382. * Show a checkbox
  383. * `x` and `y`: position of checkbox
  384. * `name` fieldname data is transferred to Lua
  385. * `label` to be shown left of checkbox
  386. * `selected` (optional): `true`/`false`
  387. #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
  388. * Show a scrollbar
  389. * There are two ways to use it:
  390. 1. handle the changed event (only changed scrollbar is available)
  391. 2. read the value on pressing a button (all scrollbars are available)
  392. * `x` and `y`: position of trackbar
  393. * `w` and `h`: width and height
  394. * `orientation`: `vertical`/`horizontal`
  395. * Fieldname data is transferred to Lua
  396. * Value this trackbar is set to (`0`-`1000`)
  397. * See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`)
  398. #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
  399. * Show scrollable table using options defined by the previous `tableoptions[]`
  400. * Displays cells as defined by the previous `tablecolumns[]`
  401. * `x` and `y`: position the itemlist relative to the top left of the menu
  402. * `w` and `h` are the size of the itemlist
  403. * `name`: fieldname sent to server on row select or doubleclick
  404. * `cell 1`...`cell n`: cell contents given in row-major order
  405. * `selected idx`: index of row to be selected within table (first row = `1`)
  406. * See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`)
  407. #### `tableoptions[<opt 1>;<opt 2>;...]`
  408. * Sets options for `table[]`
  409. * `color=#RRGGBB`
  410. * default text color (`ColorString`), defaults to `#FFFFFF`
  411. * `background=#RRGGBB`
  412. * table background color (`ColorString`), defaults to `#000000`
  413. * `border=<true/false>`
  414. * should the table be drawn with a border? (default: `true`)
  415. * `highlight=#RRGGBB`
  416. * highlight background color (`ColorString`), defaults to `#466432`
  417. * `highlight_text=#RRGGBB`
  418. * highlight text color (`ColorString`), defaults to `#FFFFFF`
  419. * `opendepth=<value>`
  420. * all subtrees up to `depth < value` are open (default value = `0`)
  421. * only useful when there is a column of type "tree"
  422. #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]`
  423. * Sets columns for `table[]`
  424. * Types: `text`, `image`, `color`, `indent`, `tree`
  425. * `text`: show cell contents as text
  426. * `image`: cell contents are an image index, use column options to define images
  427. * `color`: cell contents are a ColorString and define color of following cell
  428. * `indent`: cell contents are a number and define indentation of following cell
  429. * `tree`: same as indent, but user can open and close subtrees (treeview-like)
  430. * Column options:
  431. * `align=<value>`
  432. * for `text` and `image`: content alignment within cells.
  433. Available values: `left` (default), `center`, `right`, `inline`
  434. * `width=<value>`
  435. * for `text` and `image`: minimum width in em (default: `0`)
  436. * for `indent` and `tree`: indent width in em (default: `1.5`)
  437. * `padding=<value>`: padding left of the column, in em (default `0.5`).
  438. Exception: defaults to 0 for indent columns
  439. * `tooltip=<value>`: tooltip text (default: empty)
  440. * `image` column options:
  441. * `0=<value>` sets image for image index 0
  442. * `1=<value>` sets image for image index 1
  443. * `2=<value>` sets image for image index 2
  444. * and so on; defined indices need not be contiguous empty or
  445. non-numeric cells are treated as `0`.
  446. * `color` column options:
  447. * `span=<value>`: number of following columns to affect (default: infinite)
  448. **Note**: do _not_ use a element name starting with `key_`; those names are reserved to
  449. pass key press events to formspec!
  450. Spatial Vectors
  451. ---------------
  452. * `vector.new(a[, b, c])`: returns a vector:
  453. * A copy of `a` if `a` is a vector.
  454. * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
  455. * `vector.direction(p1, p2)`: returns a vector
  456. * `vector.distance(p1, p2)`: returns a number
  457. * `vector.length(v)`: returns a number
  458. * `vector.normalize(v)`: returns a vector
  459. * `vector.floor(v)`: returns a vector, each dimension rounded down
  460. * `vector.round(v)`: returns a vector, each dimension rounded to nearest int
  461. * `vector.apply(v, func)`: returns a vector
  462. * `vector.combine(v, w, 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 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_modpath(modname)`: returns virtual path of given mod including
  508. the trailing separator. This is useful to load additional Lua files
  509. contained in your mod:
  510. e.g. `dofile(minetest.get_modpath(minetest.get_current_modname()) .. "stuff.lua")`
  511. * `minetest.get_language()`: returns two strings
  512. * the current gettext locale
  513. * the current language code (the same as used for client-side translations)
  514. * `minetest.get_version()`: returns a table containing components of the
  515. engine version. Components:
  516. * `project`: Name of the project, eg, "Minetest"
  517. * `string`: Simple version, eg, "1.2.3-dev"
  518. * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
  519. Use this for informational purposes only. The information in the returned
  520. table does not represent the capabilities of the engine, nor is it
  521. reliable or verifiable. Compatible forks will have a different name and
  522. version entirely. To check for the presence of engine features, test
  523. whether the functions exported by the wanted features exist. For example:
  524. `if minetest.check_for_falling then ... end`.
  525. * `minetest.sha1(data, [raw])`: returns the sha1 hash of data
  526. * `data`: string of data to hash
  527. * `raw`: return raw bytes instead of hex digits, default: false
  528. * `minetest.colorspec_to_colorstring(colorspec)`: Converts a ColorSpec to a
  529. ColorString. If the ColorSpec is invalid, returns `nil`.
  530. * `colorspec`: The ColorSpec to convert
  531. * `minetest.get_csm_restrictions()`: returns a table of `Flags` indicating the
  532. restrictions applied to the current mod.
  533. * If a flag in this table is set to true, the feature is RESTRICTED.
  534. * Possible flags: `load_client_mods`, `chat_messages`, `read_itemdefs`,
  535. `read_nodedefs`, `lookup_nodes`, `read_playerinfo`
  536. ### Logging
  537. * `minetest.debug(...)`
  538. * Equivalent to `minetest.log(table.concat({...}, "\t"))`
  539. * `minetest.log([level,] text)`
  540. * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
  541. `"info"`, or `"verbose"`. Default is `"none"`.
  542. ### Global callback registration functions
  543. Call these functions only at load time!
  544. * `minetest.register_globalstep(function(dtime))`
  545. * Called every client environment step, usually interval of 0.1s
  546. * `minetest.register_on_mods_loaded(function())`
  547. * Called just after mods have finished loading.
  548. * `minetest.register_on_shutdown(function())`
  549. * Called before client shutdown
  550. * **Warning**: If the client terminates abnormally (i.e. crashes), the registered
  551. callbacks **will likely not be run**. Data should be saved at
  552. semi-frequent intervals as well as on server shutdown.
  553. * `minetest.register_on_receiving_chat_message(function(message))`
  554. * Called always when a client receive a message
  555. * Return `true` to mark the message as handled, which means that it will not be shown to chat
  556. * `minetest.register_on_sending_chat_message(function(message))`
  557. * Called always when a client send a message from chat
  558. * Return `true` to mark the message as handled, which means that it will not be sent to server
  559. * `minetest.register_chatcommand(cmd, chatcommand definition)`
  560. * Adds definition to minetest.registered_chatcommands
  561. * `minetest.unregister_chatcommand(name)`
  562. * Unregisters a chatcommands registered with register_chatcommand.
  563. * `minetest.register_on_chatcommand(function(command, params))`
  564. * Called always when a chatcommand is triggered, before `minetest.registered_chatcommands`
  565. is checked to see if that the command exists, but after the input is parsed.
  566. * Return `true` to mark the command as handled, which means that the default
  567. handlers will be prevented.
  568. * `minetest.register_on_death(function())`
  569. * Called when the local player dies
  570. * `minetest.register_on_hp_modification(function(hp))`
  571. * Called when server modified player's HP
  572. * `minetest.register_on_damage_taken(function(hp))`
  573. * Called when the local player take damages
  574. * `minetest.register_on_formspec_input(function(formname, fields))`
  575. * Called when a button is pressed in the local player's inventory form
  576. * Newest functions are called first
  577. * If function returns `true`, remaining functions are not called
  578. * `minetest.register_on_dignode(function(pos, node))`
  579. * Called when the local player digs a node
  580. * Newest functions are called first
  581. * If any function returns true, the node isn't dug
  582. * `minetest.register_on_punchnode(function(pos, node))`
  583. * Called when the local player punches a node
  584. * Newest functions are called first
  585. * If any function returns true, the punch is ignored
  586. * `minetest.register_on_placenode(function(pointed_thing, node))`
  587. * Called when a node has been placed
  588. * `minetest.register_on_item_use(function(item, pointed_thing))`
  589. * Called when the local player uses an item.
  590. * Newest functions are called first.
  591. * If any function returns true, the item use is not sent to server.
  592. * `minetest.register_on_modchannel_message(function(channel_name, sender, message))`
  593. * Called when an incoming mod channel message is received
  594. * You must have joined some channels before, and server must acknowledge the
  595. join request.
  596. * If message comes from a server mod, `sender` field is an empty string.
  597. * `minetest.register_on_modchannel_signal(function(channel_name, signal))`
  598. * Called when a valid incoming mod channel signal is received
  599. * Signal id permit to react to server mod channel events
  600. * Possible values are:
  601. 0: join_ok
  602. 1: join_failed
  603. 2: leave_ok
  604. 3: leave_failed
  605. 4: event_on_not_joined_channel
  606. 5: state_changed
  607. * `minetest.register_on_inventory_open(function(inventory))`
  608. * Called when the local player open inventory
  609. * Newest functions are called first
  610. * If any function returns true, inventory doesn't open
  611. ### Sounds
  612. * `minetest.sound_play(spec, parameters)`: returns a handle
  613. * `spec` is a `SimpleSoundSpec`
  614. * `parameters` is a sound parameter table
  615. * `minetest.sound_stop(handle)`
  616. * `handle` is a handle returned by `minetest.sound_play`
  617. * `minetest.sound_fade(handle, step, gain)`
  618. * `handle` is a handle returned by `minetest.sound_play`
  619. * `step` determines how fast a sound will fade.
  620. Negative step will lower the sound volume, positive step will increase
  621. the sound volume.
  622. * `gain` the target gain for the fade.
  623. ### Timing
  624. * `minetest.after(time, func, ...)`
  625. * Call the function `func` after `time` seconds, may be fractional
  626. * Optional: Variable number of arguments that are passed to `func`
  627. * `minetest.get_us_time()`
  628. * Returns time with microsecond precision. May not return wall time.
  629. * `minetest.get_timeofday()`
  630. * Returns the time of day: `0` for midnight, `0.5` for midday
  631. ### Map
  632. * `minetest.get_node_or_nil(pos)`
  633. * Returns the node at the given position as table in the format
  634. `{name="node_name", param1=0, param2=0}`, returns `nil`
  635. for unloaded areas or flavor limited areas.
  636. * `minetest.get_node_light(pos, timeofday)`
  637. * Gets the light value at the given position. Note that the light value
  638. "inside" the node at the given position is returned, so you usually want
  639. to get the light value of a neighbor.
  640. * `pos`: The position where to measure the light.
  641. * `timeofday`: `nil` for current time, `0` for night, `0.5` for day
  642. * Returns a number between `0` and `15` or `nil`
  643. * `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
  644. * `radius`: using a maximum metric
  645. * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
  646. * `search_center` is an optional boolean (default: `false`)
  647. If true `pos` is also checked for the nodes
  648. * `minetest.find_nodes_in_area(pos1, pos2, nodenames, [grouped])`
  649. * `pos1` and `pos2` are the min and max positions of the area to search.
  650. * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
  651. * If `grouped` is true the return value is a table indexed by node name
  652. which contains lists of positions.
  653. * If `grouped` is false or absent the return values are as follows:
  654. first value: Table with all node positions
  655. second value: Table with the count of each node with the node name
  656. as index
  657. * Area volume is limited to 4,096,000 nodes
  658. * `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a
  659. list of positions.
  660. * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
  661. * Return value: Table with all node positions with a node air above
  662. * Area volume is limited to 4,096,000 nodes
  663. * `minetest.line_of_sight(pos1, pos2)`: returns `boolean, pos`
  664. * Checks if there is anything other than air between pos1 and pos2.
  665. * Returns false if something is blocking the sight.
  666. * Returns the position of the blocking node when `false`
  667. * `pos1`: First position
  668. * `pos2`: Second position
  669. * `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast`
  670. * Creates a `Raycast` object.
  671. * `pos1`: start of the ray
  672. * `pos2`: end of the ray
  673. * `objects`: if false, only nodes will be returned. Default is `true`.
  674. * `liquids`: if false, liquid nodes won't be returned. Default is `false`.
  675. * `minetest.find_nodes_with_meta(pos1, pos2)`
  676. * Get a table of positions of nodes that have metadata within a region
  677. {pos1, pos2}.
  678. * `minetest.get_meta(pos)`
  679. * Get a `NodeMetaRef` at that position
  680. * `minetest.get_node_level(pos)`
  681. * get level of leveled node (water, snow)
  682. * `minetest.get_node_max_level(pos)`
  683. * get max available level for leveled node
  684. ### Player
  685. * `minetest.send_chat_message(message)`
  686. * Act as if `message` was typed by the player into the terminal.
  687. * `minetest.run_server_chatcommand(cmd, param)`
  688. * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)`
  689. * `minetest.clear_out_chat_queue()`
  690. * Clears the out chat queue
  691. * `minetest.localplayer`
  692. * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
  693. ### Privileges
  694. * `minetest.get_privilege_list()`
  695. * Returns a list of privileges the current player has in the format `{priv1=true,...}`
  696. * `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
  697. * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
  698. * Convert between two privilege representations
  699. ### Client Environment
  700. * `minetest.get_player_names()`
  701. * Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server)
  702. * `minetest.disconnect()`
  703. * Disconnect from the server and exit to main menu.
  704. * Returns `false` if the client is already disconnecting otherwise returns `true`.
  705. * `minetest.get_server_info()`
  706. * Returns [server info](#server-info).
  707. * `minetest.send_respawn()`
  708. * Sends a respawn request to the server.
  709. ### Storage API
  710. * `minetest.get_mod_storage()`:
  711. * returns reference to mod private `StorageRef`
  712. * must be called during mod load time
  713. ### Mod channels
  714. ![Mod channels communication scheme](docs/mod channels.png)
  715. * `minetest.mod_channel_join(channel_name)`
  716. * Client joins channel `channel_name`, and creates it, if necessary. You
  717. should listen from incoming messages with `minetest.register_on_modchannel_message`
  718. call to receive incoming messages. Warning, this function is asynchronous.
  719. ### Particles
  720. * `minetest.add_particle(particle definition)`
  721. * `minetest.add_particlespawner(particlespawner definition)`
  722. * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds
  723. * Returns an `id`, and -1 if adding didn't succeed
  724. * `minetest.delete_particlespawner(id)`
  725. * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
  726. ### Misc.
  727. * `minetest.parse_json(string[, nullvalue])`: returns something
  728. * Convert a string containing JSON data into the Lua equivalent
  729. * `nullvalue`: returned in place of the JSON null; defaults to `nil`
  730. * On success returns a table, a string, a number, a boolean or `nullvalue`
  731. * On failure outputs an error message and returns `nil`
  732. * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
  733. * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
  734. * Convert a Lua table into a JSON string
  735. * styled: Outputs in a human-readable format if this is set, defaults to false
  736. * Unserializable things like functions and userdata are saved as null.
  737. * **Warning**: JSON is more strict than the Lua table format.
  738. 1. You can only use strings and positive integers of at least one as keys.
  739. 2. You can not mix string and integer keys.
  740. This is due to the fact that JSON has two distinct array and object values.
  741. * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
  742. * `minetest.serialize(table)`: returns a string
  743. * Convert a table containing tables, strings, numbers, booleans and `nil`s
  744. into string form readable by `minetest.deserialize`
  745. * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
  746. * `minetest.deserialize(string)`: returns a table
  747. * Convert a string returned by `minetest.deserialize` into a table
  748. * `string` is loaded in an empty sandbox environment.
  749. * Will load functions, but they cannot access the global environment.
  750. * Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
  751. * Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
  752. * `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
  753. * `minetest.compress(data, method, ...)`: returns `compressed_data`
  754. * Compress a string of data.
  755. * `method` is a string identifying the compression method to be used.
  756. * Supported compression methods:
  757. * Deflate (zlib): `"deflate"`
  758. * `...` indicates method-specific arguments. Currently defined arguments are:
  759. * Deflate: `level` - Compression level, `0`-`9` or `nil`.
  760. * `minetest.decompress(compressed_data, method, ...)`: returns data
  761. * Decompress a string of data (using ZLib).
  762. * See documentation on `minetest.compress()` for supported compression methods.
  763. * currently supported.
  764. * `...` indicates method-specific arguments. Currently, no methods use this.
  765. * `minetest.rgba(red, green, blue[, alpha])`: returns a string
  766. * Each argument is a 8 Bit unsigned integer
  767. * Returns the ColorString from rgb or rgba values
  768. * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
  769. * `minetest.encode_base64(string)`: returns string encoded in base64
  770. * Encodes a string in base64.
  771. * `minetest.decode_base64(string)`: returns string or nil on failure
  772. * Padding characters are only supported starting at version 5.4.0, where
  773. 5.5.0 and newer perform proper checks.
  774. * Decodes a string encoded in base64.
  775. * `minetest.gettext(string)` : returns string
  776. * look up the translation of a string in the gettext message catalog
  777. * `fgettext_ne(string, ...)`
  778. * call minetest.gettext(string), replace "$1"..."$9" with the given
  779. extra arguments and return the result
  780. * `fgettext(string, ...)` : returns string
  781. * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
  782. * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
  783. * returns the exact position on the surface of a pointed node
  784. * `minetest.global_exists(name)`
  785. * Checks if a global variable has been set, without triggering a warning.
  786. ### UI
  787. * `minetest.ui.minimap`
  788. * Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods.
  789. * If client disabled minimap (using enable_minimap setting) this reference will be nil.
  790. * `minetest.camera`
  791. * Reference to the camera object. See [`Camera`](#camera) class reference for methods.
  792. * `minetest.show_formspec(formname, formspec)` : returns true on success
  793. * Shows a formspec to the player
  794. * `minetest.display_chat_message(message)` returns true on success
  795. * Shows a chat message to the current player.
  796. Class reference
  797. ---------------
  798. ### ModChannel
  799. An interface to use mod channels on client and server
  800. #### Methods
  801. * `leave()`: leave the mod channel.
  802. * Client leaves channel `channel_name`.
  803. * No more incoming or outgoing messages can be sent to this channel from client mods.
  804. * This invalidate all future object usage
  805. * Ensure your set mod_channel to nil after that to free Lua resources
  806. * `is_writeable()`: returns true if channel is writable and mod can send over it.
  807. * `send_all(message)`: Send `message` though the mod channel.
  808. * If mod channel is not writable or invalid, message will be dropped.
  809. * Message size is limited to 65535 characters by protocol.
  810. ### Minimap
  811. An interface to manipulate minimap on client UI
  812. #### Methods
  813. * `show()`: shows the minimap (if not disabled by server)
  814. * `hide()`: hides the minimap
  815. * `set_pos(pos)`: sets the minimap position on screen
  816. * `get_pos()`: returns the minimap current position
  817. * `set_angle(deg)`: sets the minimap angle in degrees
  818. * `get_angle()`: returns the current minimap angle in degrees
  819. * `set_mode(mode)`: sets the minimap mode (0 to 6)
  820. * `get_mode()`: returns the current minimap mode
  821. * `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round)
  822. * `get_shape()`: Gets the minimap shape. (0 = square, 1 = round)
  823. ### Camera
  824. An interface to get or set information about the camera and camera-node.
  825. Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.
  826. #### Methods
  827. * `set_camera_mode(mode)`
  828. * Pass `0` for first-person, `1` for third person, and `2` for third person front
  829. * `get_camera_mode()`
  830. * Returns 0, 1, or 2 as described above
  831. * `get_fov()`
  832. * Returns a table with X, Y, maximum and actual FOV in degrees:
  833. ```lua
  834. {
  835. x = number,
  836. y = number,
  837. max = number,
  838. actual = number
  839. }
  840. ```
  841. * `get_pos()`
  842. * Returns position of camera with view bobbing
  843. * `get_offset()`
  844. * Returns eye offset vector
  845. * `get_look_dir()`
  846. * Returns eye direction unit vector
  847. * `get_look_vertical()`
  848. * Returns pitch in radians
  849. * `get_look_horizontal()`
  850. * Returns yaw in radians
  851. * `get_aspect_ratio()`
  852. * Returns aspect ratio of screen
  853. ### LocalPlayer
  854. An interface to retrieve information about the player.
  855. This object will only be available after the client is initialized. Earlier accesses will yield a `nil` value.
  856. Methods:
  857. * `get_pos()`
  858. * returns current player current position
  859. * `get_velocity()`
  860. * returns player speed vector
  861. * `get_hp()`
  862. * returns player HP
  863. * `get_name()`
  864. * returns player name
  865. * `get_wield_index()`
  866. * returns the index of the wielded item
  867. * `get_wielded_item()`
  868. * returns the itemstack the player is holding
  869. * `is_attached()`
  870. * returns true if player is attached
  871. * `is_touching_ground()`
  872. * returns true if player touching ground
  873. * `is_in_liquid()`
  874. * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)
  875. * `is_in_liquid_stable()`
  876. * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
  877. * `get_move_resistance()`
  878. * returns move resistance of current node, the higher the slower the player moves
  879. * `is_climbing()`
  880. * returns true if player is climbing
  881. * `swimming_vertical()`
  882. * returns true if player is swimming in vertical
  883. * `get_physics_override()`
  884. * returns:
  885. ```lua
  886. {
  887. speed = float,
  888. jump = float,
  889. gravity = float,
  890. sneak = boolean,
  891. sneak_glitch = boolean,
  892. new_move = boolean,
  893. }
  894. ```
  895. * `get_override_pos()`
  896. * returns override position
  897. * `get_last_pos()`
  898. * returns last player position before the current client step
  899. * `get_last_velocity()`
  900. * returns last player speed
  901. * `get_breath()`
  902. * returns the player's breath
  903. * `get_movement_acceleration()`
  904. * returns acceleration of the player in different environments:
  905. ```lua
  906. {
  907. fast = float,
  908. air = float,
  909. default = float,
  910. }
  911. ```
  912. * `get_movement_speed()`
  913. * returns player's speed in different environments:
  914. ```lua
  915. {
  916. walk = float,
  917. jump = float,
  918. crouch = float,
  919. fast = float,
  920. climb = float,
  921. }
  922. ```
  923. * `get_movement()`
  924. * returns player's movement in different environments:
  925. ```lua
  926. {
  927. liquid_fluidity = float,
  928. liquid_sink = float,
  929. liquid_fluidity_smooth = float,
  930. gravity = float,
  931. }
  932. ```
  933. * `get_last_look_horizontal()`:
  934. * returns last look horizontal angle
  935. * `get_last_look_vertical()`:
  936. * returns last look vertical angle
  937. * `get_control()`:
  938. * returns pressed player controls
  939. ```lua
  940. {
  941. up = boolean,
  942. down = boolean,
  943. left = boolean,
  944. right = boolean,
  945. jump = boolean,
  946. aux1 = boolean,
  947. sneak = boolean,
  948. zoom = boolean,
  949. dig = boolean,
  950. place = boolean,
  951. }
  952. ```
  953. * `get_armor_groups()`
  954. * returns a table with the armor group ratings
  955. * `hud_add(definition)`
  956. * add a HUD element described by HUD def, returns ID number on success and `nil` on failure.
  957. * See [`HUD definition`](#hud-definition-hud_add-hud_get)
  958. * `hud_get(id)`
  959. * returns the [`definition`](#hud-definition-hud_add-hud_get) of the HUD with that ID number or `nil`, if non-existent.
  960. * `hud_remove(id)`
  961. * remove the HUD element of the specified id, returns `true` on success
  962. * `hud_change(id, stat, value)`
  963. * change a value of a previously added HUD element
  964. * element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
  965. * Returns `true` on success, otherwise returns `nil`
  966. ### Settings
  967. An interface to read config files in the format of `minetest.conf`.
  968. It can be created via `Settings(filename)`.
  969. #### Methods
  970. * `get(key)`: returns a value
  971. * `get_bool(key)`: returns a boolean
  972. * `set(key, value)`
  973. * `remove(key)`: returns a boolean (`true` for success)
  974. * `get_names()`: returns `{key1,...}`
  975. * `write()`: returns a boolean (`true` for success)
  976. * write changes to file
  977. * `to_table()`: returns `{[key1]=value1,...}`
  978. ### NodeMetaRef
  979. Node metadata: reference extra data and functionality stored in a node.
  980. Can be obtained via `minetest.get_meta(pos)`.
  981. #### Methods
  982. * `get_string(name)`
  983. * `get_int(name)`
  984. * `get_float(name)`
  985. * `to_table()`: returns `nil` or a table with keys:
  986. * `fields`: key-value storage
  987. * `inventory`: `{list1 = {}, ...}}`
  988. ### `Raycast`
  989. A raycast on the map. It works with selection boxes.
  990. Can be used as an iterator in a for loop as:
  991. local ray = Raycast(...)
  992. for pointed_thing in ray do
  993. ...
  994. end
  995. The map is loaded as the ray advances. If the map is modified after the
  996. `Raycast` is created, the changes may or may not have an effect on the object.
  997. It can be created via `Raycast(pos1, pos2, objects, liquids)` or
  998. `minetest.raycast(pos1, pos2, objects, liquids)` where:
  999. * `pos1`: start of the ray
  1000. * `pos2`: end of the ray
  1001. * `objects`: if false, only nodes will be returned. Default is true.
  1002. * `liquids`: if false, liquid nodes won't be returned. Default is false.
  1003. #### Methods
  1004. * `next()`: returns a `pointed_thing` with exact pointing location
  1005. * Returns the next thing pointed by the ray or nil.
  1006. -----------------
  1007. ### Definitions
  1008. * `minetest.get_node_def(nodename)`
  1009. * Returns [node definition](#node-definition) table of `nodename`
  1010. * `minetest.get_item_def(itemstring)`
  1011. * Returns item definition table of `itemstring`
  1012. #### Node Definition
  1013. ```lua
  1014. {
  1015. has_on_construct = bool, -- Whether the node has the on_construct callback defined
  1016. has_on_destruct = bool, -- Whether the node has the on_destruct callback defined
  1017. has_after_destruct = bool, -- Whether the node has the after_destruct callback defined
  1018. name = string, -- The name of the node e.g. "air", "default:dirt"
  1019. groups = table, -- The groups of the node
  1020. paramtype = string, -- Paramtype of the node
  1021. paramtype2 = string, -- ParamType2 of the node
  1022. drawtype = string, -- Drawtype of the node
  1023. mesh = <string>, -- Mesh name if existant
  1024. minimap_color = <Color>, -- Color of node on minimap *May not exist*
  1025. visual_scale = number, -- Visual scale of node
  1026. alpha = number, -- Alpha of the node. Only used for liquids
  1027. color = <Color>, -- Color of node *May not exist*
  1028. palette_name = <string>, -- Filename of palette *May not exist*
  1029. palette = <{ -- List of colors
  1030. Color,
  1031. Color
  1032. }>,
  1033. waving = number, -- 0 of not waving, 1 if waving
  1034. connect_sides = number, -- Used for connected nodes
  1035. connects_to = { -- List of nodes to connect to
  1036. "node1",
  1037. "node2"
  1038. },
  1039. post_effect_color = Color, -- Color overlayed on the screen when the player is in the node
  1040. leveled = number, -- Max level for node
  1041. sunlight_propogates = bool, -- Whether light passes through the block
  1042. light_source = number, -- Light emitted by the block
  1043. is_ground_content = bool, -- Whether caves should cut through the node
  1044. walkable = bool, -- Whether the player collides with the node
  1045. pointable = bool, -- Whether the player can select the node
  1046. diggable = bool, -- Whether the player can dig the node
  1047. climbable = bool, -- Whether the player can climb up the node
  1048. buildable_to = bool, -- Whether the player can replace the node by placing a node on it
  1049. rightclickable = bool, -- Whether the player can place nodes pointing at this node
  1050. damage_per_second = number, -- HP of damage per second when the player is in the node
  1051. liquid_type = <string>, -- A string containing "none", "flowing", or "source" *May not exist*
  1052. liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
  1053. liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
  1054. liquid_viscosity = <number>, -- How slow the liquid flows *May not exist*
  1055. liquid_renewable = <boolean>, -- Whether the liquid makes an infinite source *May not exist*
  1056. liquid_range = <number>, -- How far the liquid flows *May not exist*
  1057. drowning = bool, -- Whether the player will drown in the node
  1058. floodable = bool, -- Whether nodes will be replaced by liquids (flooded)
  1059. node_box = table, -- Nodebox to draw the node with
  1060. collision_box = table, -- Nodebox to set the collision area
  1061. selection_box = table, -- Nodebox to set the area selected by the player
  1062. sounds = { -- Table of sounds that the block makes
  1063. sound_footstep = SimpleSoundSpec,
  1064. sound_dig = SimpleSoundSpec,
  1065. sound_dug = SimpleSoundSpec
  1066. },
  1067. legacy_facedir_simple = bool, -- Whether to use old facedir
  1068. legacy_wallmounted = bool -- Whether to use old wallmounted
  1069. move_resistance = <number>, -- How slow players can move through the node *May not exist*
  1070. }
  1071. ```
  1072. #### Item Definition
  1073. ```lua
  1074. {
  1075. name = string, -- Name of the item e.g. "default:stone"
  1076. description = string, -- Description of the item e.g. "Stone"
  1077. type = string, -- Item type: "none", "node", "craftitem", "tool"
  1078. inventory_image = string, -- Image in the inventory
  1079. wield_image = string, -- Image in wieldmesh
  1080. palette_image = string, -- Image for palette
  1081. color = Color, -- Color for item
  1082. wield_scale = Vector, -- Wieldmesh scale
  1083. stack_max = number, -- Number of items stackable together
  1084. usable = bool, -- Has on_use callback defined
  1085. liquids_pointable = bool, -- Whether you can point at liquids with the item
  1086. tool_capabilities = <table>, -- If the item is a tool, tool capabilities of the item
  1087. groups = table, -- Groups of the item
  1088. sound_place = SimpleSoundSpec, -- Sound played when placed
  1089. sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed
  1090. node_placement_prediction = string -- Node placed in client until server catches up
  1091. }
  1092. ```
  1093. -----------------
  1094. ### Chat command definition (`register_chatcommand`)
  1095. {
  1096. params = "<name> <privilege>", -- Short parameter description
  1097. description = "Remove privilege from player", -- Full description
  1098. func = function(param), -- Called when command is run.
  1099. -- Returns boolean success and text output.
  1100. }
  1101. ### Server info
  1102. ```lua
  1103. {
  1104. address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
  1105. ip = "203.0.113.156", -- The IP address of the server.
  1106. port = 30000, -- The port the client is connected to.
  1107. 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.
  1108. }
  1109. ```
  1110. ### HUD Definition (`hud_add`, `hud_get`)
  1111. ```lua
  1112. {
  1113. hud_elem_type = "image", -- see HUD element types, default "text"
  1114. -- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
  1115. position = {x=0.5, y=0.5},
  1116. -- ^ Left corner position of element, default `{x=0,y=0}`.
  1117. name = "<name>", -- default ""
  1118. scale = {x=2, y=2}, -- default {x=0,y=0}
  1119. text = "<text>", -- default ""
  1120. number = 2, -- default 0
  1121. item = 3, -- default 0
  1122. -- ^ Selected item in inventory. 0 for no item selected.
  1123. direction = 0, -- default 0
  1124. -- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
  1125. alignment = {x=0, y=0}, -- default {x=0, y=0}
  1126. -- ^ See "HUD Element Types"
  1127. offset = {x=0, y=0}, -- default {x=0, y=0}
  1128. -- ^ See "HUD Element Types"
  1129. size = { x=100, y=100 }, -- default {x=0, y=0}
  1130. -- ^ Size of element in pixels
  1131. style = 0,
  1132. -- ^ For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace
  1133. }
  1134. ```
  1135. Escape sequences
  1136. ----------------
  1137. Most text can contain escape sequences, that can for example color the text.
  1138. There are a few exceptions: tab headers, dropdowns and vertical labels can't.
  1139. The following functions provide escape sequences:
  1140. * `minetest.get_color_escape_sequence(color)`:
  1141. * `color` is a [ColorString](#colorstring)
  1142. * The escape sequence sets the text color to `color`
  1143. * `minetest.colorize(color, message)`:
  1144. * Equivalent to:
  1145. `minetest.get_color_escape_sequence(color) ..
  1146. message ..
  1147. minetest.get_color_escape_sequence("#ffffff")`
  1148. * `minetest.get_background_escape_sequence(color)`
  1149. * `color` is a [ColorString](#colorstring)
  1150. * The escape sequence sets the background of the whole text element to
  1151. `color`. Only defined for item descriptions and tooltips.
  1152. * `minetest.strip_foreground_colors(str)`
  1153. * Removes foreground colors added by `get_color_escape_sequence`.
  1154. * `minetest.strip_background_colors(str)`
  1155. * Removes background colors added by `get_background_escape_sequence`.
  1156. * `minetest.strip_colors(str)`
  1157. * Removes all color escape sequences.
  1158. `ColorString`
  1159. -------------
  1160. `#RGB` defines a color in hexadecimal format.
  1161. `#RGBA` defines a color in hexadecimal format and alpha channel.
  1162. `#RRGGBB` defines a color in hexadecimal format.
  1163. `#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
  1164. Named colors are also supported and are equivalent to
  1165. [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
  1166. To specify the value of the alpha channel, append `#A` or `#AA` to the end of
  1167. the color name (e.g. `colorname#08`).
  1168. `Color`
  1169. -------------
  1170. `{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color.
  1171. HUD element types
  1172. -----------------
  1173. The position field is used for all element types.
  1174. To account for differing resolutions, the position coordinates are the percentage
  1175. of the screen, ranging in value from `0` to `1`.
  1176. The name field is not yet used, but should contain a description of what the
  1177. HUD element represents. The direction field is the direction in which something
  1178. is drawn.
  1179. `0` draws from left to right, `1` draws from right to left, `2` draws from
  1180. top to bottom, and `3` draws from bottom to top.
  1181. The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`,
  1182. with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down.
  1183. Fractional values can be used.
  1184. The `offset` field specifies a pixel offset from the position. Contrary to position,
  1185. the offset is not scaled to screen size. This allows for some precisely-positioned
  1186. items in the HUD.
  1187. **Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor!
  1188. Below are the specific uses for fields in each type; fields not listed for that type are ignored.
  1189. **Note**: Future revisions to the HUD API may be incompatible; the HUD API is still
  1190. in the experimental stages.
  1191. ### `image`
  1192. Displays an image on the HUD.
  1193. * `scale`: The scale of the image, with 1 being the original texture size.
  1194. Only the X coordinate scale is used (positive values).
  1195. Negative values represent that percentage of the screen it
  1196. should take; e.g. `x=-100` means 100% (width).
  1197. * `text`: The name of the texture that is displayed.
  1198. * `alignment`: The alignment of the image.
  1199. * `offset`: offset in pixels from position.
  1200. ### `text`
  1201. Displays text on the HUD.
  1202. * `scale`: Defines the bounding rectangle of the text.
  1203. A value such as `{x=100, y=100}` should work.
  1204. * `text`: The text to be displayed in the HUD element.
  1205. * `number`: An integer containing the RGB value of the color used to draw the text.
  1206. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on.
  1207. * `alignment`: The alignment of the text.
  1208. * `offset`: offset in pixels from position.
  1209. ### `statbar`
  1210. Displays a horizontal bar made up of half-images.
  1211. * `text`: The name of the texture that is used.
  1212. * `number`: The number of half-textures that are displayed.
  1213. If odd, will end with a vertically center-split texture.
  1214. * `direction`
  1215. * `offset`: offset in pixels from position.
  1216. * `size`: If used, will force full-image size to this value (override texture pack image size)
  1217. ### `inventory`
  1218. * `text`: The name of the inventory list to be displayed.
  1219. * `number`: Number of items in the inventory to be displayed.
  1220. * `item`: Position of item that is selected.
  1221. * `direction`
  1222. * `offset`: offset in pixels from position.
  1223. ### `waypoint`
  1224. Displays distance to selected world position.
  1225. * `name`: The name of the waypoint.
  1226. * `text`: Distance suffix. Can be blank.
  1227. * `precision`: Waypoint precision, integer >= 0. Defaults to 10.
  1228. If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`.
  1229. When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point.
  1230. `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`).
  1231. `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on:
  1232. `precision = n` will show multiples of `1/n`
  1233. * `number:` An integer containing the RGB value of the color used to draw the
  1234. text.
  1235. * `world_pos`: World position of the waypoint.
  1236. * `offset`: offset in pixels from position.
  1237. * `alignment`: The alignment of the waypoint.
  1238. ### `image_waypoint`
  1239. Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint.
  1240. * `scale`: The scale of the image, with 1 being the original texture size.
  1241. Only the X coordinate scale is used (positive values).
  1242. Negative values represent that percentage of the screen it
  1243. should take; e.g. `x=-100` means 100% (width).
  1244. * `text`: The name of the texture that is displayed.
  1245. * `alignment`: The alignment of the image.
  1246. * `world_pos`: World position of the waypoint.
  1247. * `offset`: offset in pixels from position.
  1248. ### Particle definition (`add_particle`)
  1249. {
  1250. pos = {x=0, y=0, z=0},
  1251. velocity = {x=0, y=0, z=0},
  1252. acceleration = {x=0, y=0, z=0},
  1253. -- ^ Spawn particle at pos with velocity and acceleration
  1254. expirationtime = 1,
  1255. -- ^ Disappears after expirationtime seconds
  1256. size = 1,
  1257. collisiondetection = false,
  1258. -- ^ collisiondetection: if true collides with physical objects
  1259. collision_removal = false,
  1260. -- ^ collision_removal: if true then particle is removed when it collides,
  1261. -- ^ requires collisiondetection = true to have any effect
  1262. vertical = false,
  1263. -- ^ vertical: if true faces player using y axis only
  1264. texture = "image.png",
  1265. -- ^ Uses texture (string)
  1266. animation = {Tile Animation definition},
  1267. -- ^ optional, specifies how to animate the particle texture
  1268. glow = 0
  1269. -- ^ optional, specify particle self-luminescence in darkness
  1270. }
  1271. ### `ParticleSpawner` definition (`add_particlespawner`)
  1272. {
  1273. amount = 1,
  1274. time = 1,
  1275. -- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
  1276. minpos = {x=0, y=0, z=0},
  1277. maxpos = {x=0, y=0, z=0},
  1278. minvel = {x=0, y=0, z=0},
  1279. maxvel = {x=0, y=0, z=0},
  1280. minacc = {x=0, y=0, z=0},
  1281. maxacc = {x=0, y=0, z=0},
  1282. minexptime = 1,
  1283. maxexptime = 1,
  1284. minsize = 1,
  1285. maxsize = 1,
  1286. -- ^ The particle's properties are random values in between the bounds:
  1287. -- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
  1288. -- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
  1289. collisiondetection = false,
  1290. -- ^ collisiondetection: if true uses collision detection
  1291. collision_removal = false,
  1292. -- ^ collision_removal: if true then particle is removed when it collides,
  1293. -- ^ requires collisiondetection = true to have any effect
  1294. vertical = false,
  1295. -- ^ vertical: if true faces player using y axis only
  1296. texture = "image.png",
  1297. -- ^ Uses texture (string)
  1298. }