1 Minetest Lua Mainmenu API Reference 5.7.0
2 =========================================
7 The main menu is defined as a formspec by Lua in `builtin/mainmenu/`
8 Description of formspec language to show your menu is in `lua_api.txt`
14 * `core.button_handler(fields)`: called when a button is pressed.
15 * `fields` = `{name1 = value1, name2 = value2, ...}`
16 * `core.event_handler(event)`
17 * `event`: `"MenuQuit"`, `"KeyEnter"`, `"ExitButton"` or `"EditBoxEnter"`
23 The "gamedata" table is read when calling `core.start()`. It should contain:
27 password = <password>,
28 address = <IP/address>,
30 selected_world = <index>, -- 0 for client mode
31 singleplayer = <true/false>,
40 * `core.get_min_supp_proto()`
41 * returns the minimum supported network protocol version
42 * `core.get_max_supp_proto()`
43 * returns the maximum supported network protocol version
44 * `core.open_url(url)`
45 * opens the URL in a web browser, returns false on failure.
46 * Must begin with http:// or https://
47 * `core.open_dir(path)`
48 * opens the path in the system file browser/explorer, returns false on failure.
49 * Must be an existing directory.
50 * `core.share_file(path)`
51 * Android only. Shares file using the share popup
52 * `core.get_version()` (possible in async calls)
53 * returns current core version
60 * `core.get_builtin_path()`
61 * returns path to builtin root
62 * `core.create_dir(absolute_path)` (possible in async calls)
63 * `absolute_path` to directory to create (needs to be absolute)
65 * `core.delete_dir(absolute_path)` (possible in async calls)
66 * `absolute_path` to directory to delete (needs to be absolute)
68 * `core.copy_dir(source,destination,keep_source)` (possible in async calls)
70 * `destination` folder
71 * `keep_source` DEFAULT true --> if set to false `source` is deleted after copying
73 * `core.is_dir(path)` (possible in async calls)
74 * returns true if `path` is a valid dir
75 * `core.extract_zip(zipfile,destination)` [unzip within path required]
76 * `zipfile` to extract
77 * `destination` folder to extract to
79 * `core.sound_play(spec, looped)` -> handle
80 * `spec` = `SimpleSoundSpec` (see `lua_api.txt`)
82 * `core.sound_stop(handle)`
83 * `core.get_video_drivers()`
84 * get list of video drivers supported by engine (not all modes are guaranteed to work)
85 * returns list of available video drivers' settings name and 'friendly' display name
86 e.g. `{ {name="opengl", friendly_name="OpenGL"}, {name="software", friendly_name="Software Renderer"} }`
87 * first element of returned list is guaranteed to be the NULL driver
88 * `core.get_mapgen_names([include_hidden=false])` -> table of map generator algorithms
89 registered in the core (possible in async calls)
90 * `core.get_cache_path()` -> path of cache
91 * `core.get_temp_path([param])` (possible in async calls)
92 * `param`=true: returns path to a temporary file
93 otherwise: returns path to the temporary folder
99 * `core.download_file(url, target)` (possible in async calls)
100 * `url` to download, and `target` to store to
102 * `minetest.get_http_api()` (possible in async calls)
103 * returns `HTTPApiTable` containing http functions.
104 * The returned table contains the functions `fetch_sync`, `fetch_async` and
105 `fetch_async_get` described below.
106 * Function only exists if minetest server was built with cURL support.
107 * `HTTPApiTable.fetch_sync(HTTPRequest req)`: returns HTTPRequestResult
108 * Performs given request synchronously
109 * `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
110 * Performs given request asynchronously and returns handle for
111 `HTTPApiTable.fetch_async_get`
112 * `HTTPApiTable.fetch_async_get(handle)`: returns `HTTPRequestResult`
113 * Return response data for given asynchronous HTTP request
115 ### `HTTPRequest` definition
117 Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`.
120 url = "http://example.org",
123 -- Timeout for connection in seconds. Default is 3 seconds.
125 post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
126 -- Optional, if specified a POST request with post_data is performed.
127 -- Accepts both a string and a table. If a table is specified, encodes
128 -- table as x-www-form-urlencoded key-value pairs.
129 -- If post_data is not specified, a GET request is performed instead.
131 user_agent = "ExampleUserAgent",
132 -- Optional, if specified replaces the default minetest user agent with
135 extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
136 -- Optional, if specified adds additional headers to the HTTP request.
137 -- You must make sure that the header strings follow HTTP specification
141 -- Optional, if true performs a multipart HTTP request.
145 ### `HTTPRequestResult` definition
147 Passed to `HTTPApiTable.fetch` callback. Returned by
148 `HTTPApiTable.fetch_async_get`.
152 -- If true, the request has finished (either succeeded, failed or timed
156 -- If true, the request was successful
159 -- If true, the request timed out
171 * `core.update_formspec(formspec)`
172 * `core.get_table_index(tablename)` -> index
173 * can also handle textlists
174 * `core.formspec_escape(string)` -> string
175 * escapes characters [ ] \ , ; that cannot be used in formspecs
176 * `core.explode_table_event(string)` -> table
177 * returns e.g. `{type="CHG", row=1, column=2}`
178 * `type`: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
179 * `core.explode_textlist_event(string)` -> table
180 * returns e.g. `{type="CHG", index=1}`
181 * `type`: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
182 * `core.set_formspec_prepend(formspec)`
183 * `formspec`: string to be added to every mainmenu formspec, to be used for theming.
189 * `core.set_background(type,texturepath,[tile],[minsize])`
190 * `type`: "background", "overlay", "header" or "footer"
191 * `tile`: tile the image instead of scaling (background only)
192 * `minsize`: minimum tile size, images are scaled to at least this size prior
193 doing tiling (background only)
194 * `core.set_clouds(<true/false>)`
195 * `core.set_topleft_text(text)`
196 * `core.show_keys_menu()`
197 * `core.show_path_select_dialog(formname, caption, is_file_select)`
198 * shows a path select dialog
199 * `formname` is base name of dialog response returned in fields
200 - if dialog was accepted `"_accepted"`
201 will be added to fieldname containing the path
202 - if dialog was canceled `"_cancelled"`
203 will be added to fieldname value is set to formname itself
204 * if `is_file_select` is `true`, a file and not a folder will be selected
205 * returns nil or selected file/folder
206 * `core.get_screen_info()`
210 density = <screen density 0.75,1.0,2.0,3.0 ... (dpi)>,
211 display_width = <width of display>,
212 display_height = <height of display>,
213 window_width = <current window width>,
214 window_height = <current window height>,
215 render_info = <active render information>
222 Content - an installed mod, modpack, game, or texture pack (txt)
223 Package - content which is downloadable from the content db, may or may not be installed.
225 * `core.get_user_path()` (possible in async calls)
226 * returns path to global user data,
227 the directory that contains user-provided mods, worlds, games, and texture packs.
228 * `core.get_modpath()` (possible in async calls)
229 * returns path to global modpath in the user path, where mods can be installed
230 * `core.get_modpaths()` (possible in async calls)
231 * returns table of virtual path to global modpaths, where mods have been installed
232 The difference with `core.get_modpath` is that no mods should be installed in these
233 directories by Minetest -- they might be read-only.
239 mods = "/home/user/.minetest/mods",
240 share = "/usr/share/minetest/mods",
242 -- Custom dirs can be specified by the MINETEST_MOD_DIR env variable
243 ["/path/to/custom/dir"] = "/path/to/custom/dir",
247 * `core.get_clientmodpath()` (possible in async calls)
248 * returns path to global client-side modpath
249 * `core.get_gamepath()` (possible in async calls)
250 * returns path to global gamepath
251 * `core.get_texturepath()` (possible in async calls)
252 * returns path to default textures
253 * `core.get_games()` -> table of all games (possible in async calls)
254 * `name` in return value is deprecated, use `title` instead.
255 * returns a table (ipairs) with values:
259 path = <full path to game>,
260 gamemods_path = <path>,
261 title = <title of game>,
262 menuicon_path = <full path to menuicon>,
265 addon_mods_paths = {[1] = <path>,},
267 * `core.get_content_info(path)`
271 name = "technical_id",
272 type = "mod" or "modpack" or "game" or "txp",
273 title = "Human readable title",
274 description = "description",
276 path = "path/to/content",
277 depends = {"mod", "names"}, -- mods only
278 optional_depends = {"mod", "names"}, -- mods only
280 * `core.check_mod_configuration(world_path, mod_paths)`
281 * Checks whether configuration is valid.
282 * `world_path`: path to the world
283 * `mod_paths`: list of enabled mod paths
287 is_consistent = true, -- true is consistent, false otherwise
288 unsatisfied_mods = {}, -- list of mod specs
289 satisfied_mods = {}, -- list of mod specs
290 error_message = "", -- message or nil
296 * `core.debug(line)` (possible in async calls)
297 * Always printed to `stderr` and logfile (`print()` is redirected here)
298 * `core.log(line)` (possible in async calls)
299 * `core.log(loglevel, line)` (possible in async calls)
300 * `loglevel` one of "error", "action", "info", "verbose"
306 * `core.settings:set(name, value)`
307 * `core.settings:get(name)` -> string or nil (possible in async calls)
308 * `core.settings:set_bool(name, value)`
309 * `core.settings:get_bool(name)` -> bool or nil (possible in async calls)
310 * `core.settings:save()` -> nil, save all settings to config file
312 For a complete list of methods of the `Settings` object see
313 [lua_api.txt](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt)
319 * `core.get_worlds()` -> list of worlds (possible in async calls)
324 path = <full path to world>,
325 name = <name of world>,
326 gameid = <gameid of world>,
329 * `core.create_world(worldname, gameid, init_settings)`
330 * `core.delete_world(index)`
336 * `core.get_us_time()`
337 * returns time with microsecond precision
338 * `core.gettext(string)` -> string
339 * look up the translation of a string in the gettext message catalog
340 * `fgettext_ne(string, ...)`
341 * call `core.gettext(string)`, replace "$1"..."$9" with the given
342 extra arguments and return the result
343 * `fgettext(string, ...)` -> string
344 * same as `fgettext_ne()`, but calls `core.formspec_escape` before returning result
345 * `core.parse_json(string[, nullvalue])` -> something (possible in async calls)
346 * see `core.parse_json` (`lua_api.txt`)
347 * `dump(obj, dumped={})`
348 * Return object serialized as a string
349 * `string:split(separator)`
350 * eg. `string:split("a,b", ",")` == `{"a","b"}`
352 * eg. `string.trim("\n \t\tfoo bar\t ")` == `"foo bar"`
353 * `core.is_yes(arg)` (possible in async calls)
354 * returns whether `arg` can be interpreted as yes
355 * `minetest.encode_base64(string)` (possible in async calls)
356 * Encodes a string in base64.
357 * `minetest.decode_base64(string)` (possible in async calls)
358 * Decodes a string encoded in base64.
364 * `core.handle_async(async_job,parameters,finished)`
365 * execute a function asynchronously
366 * `async_job` is a function receiving one parameter and returning one parameter
367 * `parameters` parameter table passed to `async_job`
368 * `finished` function to be called once `async_job` has finished
369 the result of `async_job` is passed to this function
371 ### Limitations of Async operations
372 * No access to global lua variables, don't even try
373 * Limited set of available functions
374 e.g. No access to functions modifying menu like `core.start`, `core.close`,
375 `core.show_path_select_dialog`
381 The main menu supports background music.
382 It looks for a `main_menu` sound in `$USER_PATH/sounds`. The same naming
383 conventions as for normal sounds apply.
384 This means the player can add a custom sound.
385 It will be played in the main menu (gain = 1.0), looped.