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_active_renderer()`: Ex: "OpenGL 4.6".
207 * `core.get_window_info()`: Same as server-side `get_player_window_information` API.
209 -- Note that none of these things are constant, they are likely to change
210 -- as the player resizes the window and moves it between monitors
212 -- real_gui_scaling and real_hud_scaling can be used instead of DPI.
213 -- OSes don't necessarily give the physical DPI, as they may allow user configuration.
214 -- real_*_scaling is just OS DPI / 96 but with another level of user configuration.
216 -- Current size of the in-game render target.
218 -- This is usually the window size, but may be smaller in certain situations,
219 -- such as side-by-side mode.
225 -- Estimated maximum formspec size before Minetest will start shrinking the
226 -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than
227 -- this and `padding[-0.01,-0.01]`.
228 max_formspec_size = {
233 -- GUI Scaling multiplier
234 -- Equal to the setting `gui_scaling` multiplied by `dpi / 96`
235 real_gui_scaling = 1,
237 -- HUD Scaling multiplier
238 -- Equal to the setting `hud_scaling` multiplied by `dpi / 96`
239 real_hud_scaling = 1,
247 Content - an installed mod, modpack, game, or texture pack (txt)
248 Package - content which is downloadable from the content db, may or may not be installed.
250 * `core.get_user_path()` (possible in async calls)
251 * returns path to global user data,
252 the directory that contains user-provided mods, worlds, games, and texture packs.
253 * `core.get_modpath()` (possible in async calls)
254 * returns path to global modpath in the user path, where mods can be installed
255 * `core.get_modpaths()` (possible in async calls)
256 * returns table of virtual path to global modpaths, where mods have been installed
257 The difference with `core.get_modpath` is that no mods should be installed in these
258 directories by Minetest -- they might be read-only.
264 mods = "/home/user/.minetest/mods",
265 share = "/usr/share/minetest/mods",
267 -- Custom dirs can be specified by the MINETEST_MOD_DIR env variable
268 ["/path/to/custom/dir"] = "/path/to/custom/dir",
272 * `core.get_clientmodpath()` (possible in async calls)
273 * returns path to global client-side modpath
274 * `core.get_gamepath()` (possible in async calls)
275 * returns path to global gamepath
276 * `core.get_texturepath()` (possible in async calls)
277 * returns path to default textures
278 * `core.get_games()` -> table of all games (possible in async calls)
279 * `name` in return value is deprecated, use `title` instead.
280 * returns a table (ipairs) with values:
284 path = <full path to game>,
285 gamemods_path = <path>,
286 title = <title of game>,
287 menuicon_path = <full path to menuicon>,
290 addon_mods_paths = {[1] = <path>,},
292 * `core.get_content_info(path)`
296 name = "technical_id",
297 type = "mod" or "modpack" or "game" or "txp",
298 title = "Human readable title",
299 description = "description",
301 path = "path/to/content",
302 depends = {"mod", "names"}, -- mods only
303 optional_depends = {"mod", "names"}, -- mods only
305 * `core.check_mod_configuration(world_path, mod_paths)`
306 * Checks whether configuration is valid.
307 * `world_path`: path to the world
308 * `mod_paths`: list of enabled mod paths
312 is_consistent = true, -- true is consistent, false otherwise
313 unsatisfied_mods = {}, -- list of mod specs
314 satisfied_mods = {}, -- list of mod specs
315 error_message = "", -- message or nil
321 * `core.debug(line)` (possible in async calls)
322 * Always printed to `stderr` and logfile (`print()` is redirected here)
323 * `core.log(line)` (possible in async calls)
324 * `core.log(loglevel, line)` (possible in async calls)
325 * `loglevel` one of "error", "action", "info", "verbose"
331 * `core.settings:set(name, value)`
332 * `core.settings:get(name)` -> string or nil (possible in async calls)
333 * `core.settings:set_bool(name, value)`
334 * `core.settings:get_bool(name)` -> bool or nil (possible in async calls)
335 * `core.settings:save()` -> nil, save all settings to config file
337 For a complete list of methods of the `Settings` object see
338 [lua_api.txt](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt)
344 * `core.get_worlds()` -> list of worlds (possible in async calls)
349 path = <full path to world>,
350 name = <name of world>,
351 gameid = <gameid of world>,
354 * `core.create_world(worldname, gameid, init_settings)`
355 * `core.delete_world(index)`
361 * `core.get_us_time()`
362 * returns time with microsecond precision
363 * `core.gettext(string)` -> string
364 * look up the translation of a string in the gettext message catalog
365 * `fgettext_ne(string, ...)`
366 * call `core.gettext(string)`, replace "$1"..."$9" with the given
367 extra arguments and return the result
368 * `fgettext(string, ...)` -> string
369 * same as `fgettext_ne()`, but calls `core.formspec_escape` before returning result
370 * `core.parse_json(string[, nullvalue])` -> something (possible in async calls)
371 * see `core.parse_json` (`lua_api.txt`)
372 * `dump(obj, dumped={})`
373 * Return object serialized as a string
374 * `string:split(separator)`
375 * eg. `string:split("a,b", ",")` == `{"a","b"}`
377 * eg. `string.trim("\n \t\tfoo bar\t ")` == `"foo bar"`
378 * `core.is_yes(arg)` (possible in async calls)
379 * returns whether `arg` can be interpreted as yes
380 * `minetest.encode_base64(string)` (possible in async calls)
381 * Encodes a string in base64.
382 * `minetest.decode_base64(string)` (possible in async calls)
383 * Decodes a string encoded in base64.
389 * `core.handle_async(async_job,parameters,finished)`
390 * execute a function asynchronously
391 * `async_job` is a function receiving one parameter and returning one parameter
392 * `parameters` parameter table passed to `async_job`
393 * `finished` function to be called once `async_job` has finished
394 the result of `async_job` is passed to this function
396 ### Limitations of Async operations
397 * No access to global lua variables, don't even try
398 * Limited set of available functions
399 e.g. No access to functions modifying menu like `core.start`, `core.close`,
400 `core.show_path_select_dialog`
406 The main menu supports background music.
407 It looks for a `main_menu` sound in `$USER_PATH/sounds`. The same naming
408 conventions as for normal sounds apply.
409 This means the player can add a custom sound.
410 It will be played in the main menu (gain = 1.0), looped.