menu_lua_api.txt 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369
  1. Minetest Lua Mainmenu API Reference 5.6.0
  2. =========================================
  3. Introduction
  4. -------------
  5. The main menu is defined as a formspec by Lua in builtin/mainmenu/
  6. Description of formspec language to show your menu is in lua_api.txt
  7. Callbacks
  8. ---------
  9. core.button_handler(fields): called when a button is pressed.
  10. ^ fields = {name1 = value1, name2 = value2, ...}
  11. core.event_handler(event)
  12. ^ event: "MenuQuit", "KeyEnter", "ExitButton" or "EditBoxEnter"
  13. Gamedata
  14. --------
  15. The "gamedata" table is read when calling core.start(). It should contain:
  16. {
  17. playername = <name>,
  18. password = <password>,
  19. address = <IP/adress>,
  20. port = <port>,
  21. selected_world = <index>, -- 0 for client mode
  22. singleplayer = <true/false>,
  23. }
  24. Functions
  25. ---------
  26. core.start()
  27. core.close()
  28. core.get_min_supp_proto()
  29. ^ returns the minimum supported network protocol version
  30. core.get_max_supp_proto()
  31. ^ returns the maximum supported network protocol version
  32. core.open_url(url)
  33. ^ opens the URL in a web browser, returns false on failure.
  34. ^ Must begin with http:// or https://
  35. core.open_dir(path)
  36. ^ opens the path in the system file browser/explorer, returns false on failure.
  37. ^ Must be an existing directory.
  38. core.get_version() (possible in async calls)
  39. ^ returns current core version
  40. Filesystem
  41. ----------
  42. core.get_builtin_path()
  43. ^ returns path to builtin root
  44. core.create_dir(absolute_path) (possible in async calls)
  45. ^ absolute_path to directory to create (needs to be absolute)
  46. ^ returns true/false
  47. core.delete_dir(absolute_path) (possible in async calls)
  48. ^ absolute_path to directory to delete (needs to be absolute)
  49. ^ returns true/false
  50. core.copy_dir(source,destination,keep_soure) (possible in async calls)
  51. ^ source folder
  52. ^ destination folder
  53. ^ keep_source DEFAULT true --> if set to false source is deleted after copying
  54. ^ returns true/false
  55. core.is_dir(path) (possible in async calls)
  56. ^ returns true if path is a valid dir
  57. core.extract_zip(zipfile,destination) [unzip within path required]
  58. ^ zipfile to extract
  59. ^ destination folder to extract to
  60. ^ returns true/false
  61. core.sound_play(spec, looped) -> handle
  62. ^ spec = SimpleSoundSpec (see lua-api.txt)
  63. ^ looped = bool
  64. core.sound_stop(handle)
  65. core.get_video_drivers()
  66. ^ get list of video drivers supported by engine (not all modes are guaranteed to work)
  67. ^ returns list of available video drivers' settings name and 'friendly' display name
  68. ^ e.g. { {name="opengl", friendly_name="OpenGL"}, {name="software", friendly_name="Software Renderer"} }
  69. ^ first element of returned list is guaranteed to be the NULL driver
  70. core.get_mapgen_names([include_hidden=false]) -> table of map generator algorithms
  71. registered in the core (possible in async calls)
  72. core.get_cache_path() -> path of cache
  73. core.get_temp_path([param]) (possible in async calls)
  74. ^ param=true: returns path to a temporary file
  75. ^ otherwise: returns path to the temporary folder
  76. HTTP Requests
  77. -------------
  78. * core.download_file(url, target) (possible in async calls)
  79. * url to download, and target to store to
  80. * returns true/false
  81. * `minetest.get_http_api()` (possible in async calls)
  82. * returns `HTTPApiTable` containing http functions.
  83. * The returned table contains the functions `fetch_sync`, `fetch_async` and
  84. `fetch_async_get` described below.
  85. * Function only exists if minetest server was built with cURL support.
  86. * `HTTPApiTable.fetch_sync(HTTPRequest req)`: returns HTTPRequestResult
  87. * Performs given request synchronously
  88. * `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
  89. * Performs given request asynchronously and returns handle for
  90. `HTTPApiTable.fetch_async_get`
  91. * `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
  92. * Return response data for given asynchronous HTTP request
  93. ### `HTTPRequest` definition
  94. Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`.
  95. {
  96. url = "http://example.org",
  97. timeout = 10,
  98. -- Timeout for connection in seconds. Default is 3 seconds.
  99. post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
  100. -- Optional, if specified a POST request with post_data is performed.
  101. -- Accepts both a string and a table. If a table is specified, encodes
  102. -- table as x-www-form-urlencoded key-value pairs.
  103. -- If post_data is not specified, a GET request is performed instead.
  104. user_agent = "ExampleUserAgent",
  105. -- Optional, if specified replaces the default minetest user agent with
  106. -- given string
  107. extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
  108. -- Optional, if specified adds additional headers to the HTTP request.
  109. -- You must make sure that the header strings follow HTTP specification
  110. -- ("Key: Value").
  111. multipart = boolean
  112. -- Optional, if true performs a multipart HTTP request.
  113. -- Default is false.
  114. }
  115. ### `HTTPRequestResult` definition
  116. Passed to `HTTPApiTable.fetch` callback. Returned by
  117. `HTTPApiTable.fetch_async_get`.
  118. {
  119. completed = true,
  120. -- If true, the request has finished (either succeeded, failed or timed
  121. -- out)
  122. succeeded = true,
  123. -- If true, the request was successful
  124. timeout = false,
  125. -- If true, the request timed out
  126. code = 200,
  127. -- HTTP status code
  128. data = "response"
  129. }
  130. Formspec
  131. --------
  132. core.update_formspec(formspec)
  133. core.get_table_index(tablename) -> index
  134. ^ can also handle textlists
  135. core.formspec_escape(string) -> string
  136. ^ escapes characters [ ] \ , ; that can not be used in formspecs
  137. core.explode_table_event(string) -> table
  138. ^ returns e.g. {type="CHG", row=1, column=2}
  139. ^ type: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
  140. core.explode_textlist_event(string) -> table
  141. ^ returns e.g. {type="CHG", index=1}
  142. ^ type: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
  143. core.set_formspec_prepend(formspec)
  144. ^ string to be added to every mainmenu formspec, to be used for theming.
  145. GUI
  146. ---
  147. core.set_background(type, texturepath,[tile],[minsize])
  148. ^ type: "background", "overlay", "header" or "footer"
  149. ^ tile: tile the image instead of scaling (background only)
  150. ^ minsize: minimum tile size, images are scaled to at least this size prior
  151. ^ doing tiling (background only)
  152. core.set_clouds(<true/false>)
  153. core.set_topleft_text(text)
  154. core.show_keys_menu()
  155. core.show_path_select_dialog(formname, caption, is_file_select)
  156. ^ shows a path select dialog
  157. ^ formname is base name of dialog response returned in fields
  158. ^ -if dialog was accepted "_accepted"
  159. ^ will be added to fieldname containing the path
  160. ^ -if dialog was canceled "_cancelled"
  161. ^ will be added to fieldname value is set to formname itself
  162. ^ if `is_file_select` is `true`, a file and not a folder will be selected
  163. ^ returns nil or selected file/folder
  164. core.get_screen_info()
  165. ^ returns {
  166. density = <screen density 0.75,1.0,2.0,3.0 ... (dpi)>,
  167. display_width = <width of display>,
  168. display_height = <height of display>,
  169. window_width = <current window width>,
  170. window_height = <current window height>,
  171. render_info = <active render information>
  172. }
  173. Content and Packages
  174. --------------------
  175. Content - an installed mod, modpack, game, or texture pack (txt)
  176. Package - content which is downloadable from the content db, may or may not be installed.
  177. * core.get_user_path() (possible in async calls)
  178. * returns path to global user data,
  179. the directory that contains user-provided mods, worlds, games, and texture packs.
  180. * core.get_modpath() (possible in async calls)
  181. * returns path to global modpath in the user path, where mods can be installed
  182. * core.get_modpaths() (possible in async calls)
  183. * returns table of virtual path to global modpaths, where mods have been installed
  184. The difference with "core.get_modpath" is that no mods should be installed in these
  185. directories by Minetest -- they might be read-only.
  186. Ex:
  187. ```
  188. {
  189. mods = "/home/user/.minetest/mods",
  190. share = "/usr/share/minetest/mods",
  191. -- Custom dirs can be specified by the MINETEST_MOD_DIR env variable
  192. ["/path/to/custom/dir"] = "/path/to/custom/dir",
  193. }
  194. ```
  195. * core.get_clientmodpath() (possible in async calls)
  196. * returns path to global client-side modpath
  197. * core.get_gamepath() (possible in async calls)
  198. * returns path to global gamepath
  199. * core.get_texturepath() (possible in async calls)
  200. * returns path to default textures
  201. * core.get_game(index)
  202. * `name` in return value is deprecated, use `title` instead.
  203. * returns:
  204. {
  205. id = <id>,
  206. path = <full path to game>,
  207. gamemods_path = <path>,
  208. title = <title of game>,
  209. menuicon_path = <full path to menuicon>,
  210. author = "author",
  211. DEPRECATED:
  212. addon_mods_paths = {[1] = <path>,},
  213. }
  214. * core.get_games() -> table of all games in upper format (possible in async calls)
  215. * core.get_content_info(path)
  216. * returns
  217. {
  218. name = "technical_id",
  219. type = "mod" or "modpack" or "game" or "txp",
  220. title = "Human readable title",
  221. description = "description",
  222. author = "author",
  223. path = "path/to/content",
  224. depends = {"mod", "names"}, -- mods only
  225. optional_depends = {"mod", "names"}, -- mods only
  226. }
  227. Logging
  228. -------
  229. core.debug(line) (possible in async calls)
  230. ^ Always printed to stderr and logfile (print() is redirected here)
  231. core.log(line) (possible in async calls)
  232. core.log(loglevel, line) (possible in async calls)
  233. ^ loglevel one of "error", "action", "info", "verbose"
  234. Settings
  235. --------
  236. core.settings:set(name, value)
  237. core.settings:get(name) -> string or nil (possible in async calls)
  238. core.settings:set_bool(name, value)
  239. core.settings:get_bool(name) -> bool or nil (possible in async calls)
  240. core.settings:save() -> nil, save all settings to config file
  241. For a complete list of methods of the Settings object see
  242. [lua_api.txt](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt)
  243. Worlds
  244. ------
  245. core.get_worlds() -> list of worlds (possible in async calls)
  246. ^ returns {
  247. [1] = {
  248. path = <full path to world>,
  249. name = <name of world>,
  250. gameid = <gameid of world>,
  251. },
  252. }
  253. core.create_world(worldname, gameid)
  254. core.delete_world(index)
  255. Helpers
  256. -------
  257. core.get_us_time()
  258. ^ returns time with microsecond precision
  259. core.gettext(string) -> string
  260. ^ look up the translation of a string in the gettext message catalog
  261. fgettext_ne(string, ...)
  262. ^ call core.gettext(string), replace "$1"..."$9" with the given
  263. ^ extra arguments and return the result
  264. fgettext(string, ...) -> string
  265. ^ same as fgettext_ne(), but calls core.formspec_escape before returning result
  266. core.parse_json(string[, nullvalue]) -> something (possible in async calls)
  267. ^ see core.parse_json (lua_api.txt)
  268. dump(obj, dumped={})
  269. ^ Return object serialized as a string
  270. string:split(separator)
  271. ^ eg. string:split("a,b", ",") == {"a","b"}
  272. string:trim()
  273. ^ eg. string.trim("\n \t\tfoo bar\t ") == "foo bar"
  274. core.is_yes(arg) (possible in async calls)
  275. ^ returns whether arg can be interpreted as yes
  276. minetest.encode_base64(string) (possible in async calls)
  277. ^ Encodes a string in base64.
  278. minetest.decode_base64(string) (possible in async calls)
  279. ^ Decodes a string encoded in base64.
  280. Async
  281. -----
  282. core.handle_async(async_job,parameters,finished)
  283. ^ execute a function asynchronously
  284. ^ async_job is a function receiving one parameter and returning one parameter
  285. ^ parameters parameter table passed to async_job
  286. ^ finished function to be called once async_job has finished
  287. ^ the result of async_job is passed to this function
  288. Limitations of Async operations
  289. -No access to global lua variables, don't even try
  290. -Limited set of available functions
  291. e.g. No access to functions modifying menu like core.start,core.close,
  292. core.show_path_select_dialog
  293. Background music
  294. ----------------
  295. The main menu supports background music.
  296. It looks for a `main_menu` sound in `$USER_PATH/sounds`. The same naming
  297. conventions as for normal sounds apply.
  298. This means the player can add a custom sound.
  299. It will be played in the main menu (gain = 1.0), looped.