From e5add369f8acf28bafe21a125a905d81af443427 Mon Sep 17 00:00:00 2001 From: rubenwardy Date: Thu, 24 Dec 2020 13:38:26 +0000 Subject: [PATCH] Remove lua_api.html --- .vscode/settings.json | 3 +- _en/items/node_drawtypes.md | 6 +- _en/map/objects.md | 2 +- _en/players/formspecs.md | 4 +- _en/players/hud.md | 16 +- _en/players/player_physics.md | 2 +- _en/quality/readmore.md | 2 +- _it/items/node_drawtypes.md | 6 +- _it/map/objects.md | 10 +- _it/players/formspecs.md | 4 +- _it/players/hud.md | 16 +- _it/players/player_physics.md | 6 +- _it/quality/readmore.md | 2 +- _layouts/default.html | 2 - lua_api.html | 6954 +-------------------------------- sitemap.json | 8 - utils/requirements.txt | 2 - utils/update_lua_api.py | 112 - 18 files changed, 40 insertions(+), 7117 deletions(-) delete mode 100644 utils/requirements.txt delete mode 100644 utils/update_lua_api.py diff --git a/.vscode/settings.json b/.vscode/settings.json index 3c19226..12f62c6 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -4,7 +4,6 @@ ], "spellright.documentTypes": [ "latex", - "plaintext", - "markdown" + "plaintext" ] } \ No newline at end of file diff --git a/_en/items/node_drawtypes.md b/_en/items/node_drawtypes.md index b194706..24fb6ae 100644 --- a/_en/items/node_drawtypes.md +++ b/_en/items/node_drawtypes.md @@ -28,12 +28,12 @@ The node params are used to control how a node is individually rendered. - [Cubic Nodes: Normal and Allfaces](#cubic-nodes-normal-and-allfaces) - [Glasslike Nodes](#glasslike-nodes) - - [Glasslike_Framed](#glasslikeframed) + - [Glasslike_Framed](#glasslike_framed) - [Airlike Nodes](#airlike-nodes) - [Lighting and Sunlight Propagation](#lighting-and-sunlight-propagation) - [Liquid Nodes](#liquid-nodes) - [Node Boxes](#node-boxes) - - [Wallmounted Node Boxes](#wallmounted-node-boxes) + - [Wallmounted Node Boxes](#wallmounted-node-boxes) - [Mesh Nodes](#mesh-nodes) - [Signlike Nodes](#signlike-nodes) - [Plantlike Nodes](#plantlike-nodes) @@ -442,5 +442,5 @@ This is not a comprehensive list, there are more types including: The torches in Minetest Game actually use two different node definitions of mesh nodes (default:torch and default:torch_wall). -As always, read the [Lua API documentation](../../lua_api.html#node-drawtypes) +As always, read the [Lua API documentation](https://minetest.gitlab.io/minetest/nodes/#node-drawtypes) for the complete list. diff --git a/_en/map/objects.md b/_en/map/objects.md index 1b86fac..1adf098 100644 --- a/_en/map/objects.md +++ b/_en/map/objects.md @@ -151,7 +151,7 @@ print("entity is at " .. minetest.pos_to_string(object:get_pos())) ``` There are a number of available callbacks for use with entities. -A complete list can be found in [lua_api.txt]({{ page.root }}/lua_api.html#registered-entities). +A complete list can be found in [lua_api.txt](https://minetest.gitlab.io/minetest/minetest-namespace-reference/#registered-definition-tables). ```lua function MyEntity:on_step(dtime) diff --git a/_en/players/formspecs.md b/_en/players/formspecs.md index e3ba1db..a3061d8 100644 --- a/_en/players/formspecs.md +++ b/_en/players/formspecs.md @@ -77,7 +77,7 @@ on multiple lines, like so: Elements are items such as text boxes or buttons, or can be metadata such as size or background. You should refer to -[lua_api.txt](../../lua_api.html#elements) +[lua_api.txt](https://minetest.gitlab.io/minetest/formspec/) for a list of all possible elements. @@ -89,7 +89,7 @@ game-wide theme should be applied. The elements in the header must be defined in a specific order, otherwise you will see an error. This order is given in the above paragraph, and, as always, -documented in [lua_api.txt](../../lua_api.html#sizewhfixed_size). +documented in the Lua API reference. The size is in formspec slots - a unit of measurement which is roughly around 64 pixels, but varies based on the screen density and scaling diff --git a/_en/players/hud.md b/_en/players/hud.md index 0a757c1..991c944 100644 --- a/_en/players/hud.md +++ b/_en/players/hud.md @@ -14,15 +14,15 @@ Heads Up Display (HUD) elements allow you to show text, images, and other graphi The HUD doesn't accept user input; for that, you should use a [formspec](formspecs.html). - [Positioning](#positioning) - - [Position and Offset](#position-and-offset) - - [Alignment](#alignment) - - [Scoreboard](#scoreboard) + - [Position and Offset](#position-and-offset) + - [Alignment](#alignment) + - [Scoreboard](#scoreboard) - [Text Elements](#text-elements) - - [Parameters](#parameters) - - [Our Example](#our-example) + - [Parameters](#parameters) + - [Our Example](#our-example) - [Image Elements](#image-elements) - - [Parameters](#parameters-1) - - [Scale](#scale) + - [Parameters](#parameters-1) + - [Scale](#scale) - [Changing an Element](#changing-an-element) - [Storing IDs](#storing-ids) - [Other Elements](#other-elements) @@ -291,4 +291,4 @@ end) ## Other Elements -Read [lua_api.txt]({{ page.root }}/lua_api.html#hud-element-types) for a complete list of HUD elements. +Read [lua_api.txt](https://minetest.gitlab.io/minetest/hud/) for a complete list of HUD elements. diff --git a/_en/players/player_physics.md b/_en/players/player_physics.md index 321cdb4..e94c5fd 100644 --- a/_en/players/player_physics.md +++ b/_en/players/player_physics.md @@ -42,7 +42,7 @@ minetest.register_chatcommand("antigravity", { ## Available Overrides `player:set_physics_override()` is given a table of overrides.\\ -According to [lua_api.txt]({{ page.root }}/lua_api.html#player-only-no-op-for-other-objects), +According to [lua_api.txt](https://minetest.gitlab.io/minetest/class-reference/#player-only-no-op-for-other-objects), these can be: * speed: multiplier to default walking speed value (default: 1) diff --git a/_en/quality/readmore.md b/_en/quality/readmore.md index 8dc1218..7ce3dc9 100644 --- a/_en/quality/readmore.md +++ b/_en/quality/readmore.md @@ -12,7 +12,7 @@ After you've read this book, take a look at the following. ### Minetest Modding -* Minetest's Lua API Reference - [HTML version]({{ page.root }}/lua_api.html) | +* Minetest's Lua API Reference - [HTML version](https://minetest.gitlab.io/minetest/class-reference/#player-only-no-op-for-other-objects) | [Text version](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt). * Explore the [Developer Wiki](http://dev.minetest.net/Main_Page). * Look at [existing mods](https://forum.minetest.net/viewforum.php?f=11). diff --git a/_it/items/node_drawtypes.md b/_it/items/node_drawtypes.md index 4a8b16e..1460949 100644 --- a/_it/items/node_drawtypes.md +++ b/_it/items/node_drawtypes.md @@ -9,8 +9,8 @@ redirect_from: /it/chapters/node_drawtypes.html ## Introduzione -Il metodo col quale un nodo viene disegnato in gioco è chiamato *drawtype*. -Ci sono diversi tipi di drawtype: il loro comportamento è determinato dalle proprietà impostate durante la definizione del tipo di nodo. +Il metodo col quale un nodo viene disegnato in gioco è chiamato *drawtype*. +Ci sono diversi tipi di drawtype: il loro comportamento è determinato dalle proprietà impostate durante la definizione del tipo di nodo. Queste proprietà sono fisse, uguali per tutte le istanze, tuttavia è possibile manipolarne alcune per singolo nodo usando una cosa chiamata `param2`. Il concetto di nodo è stato introdotto nello scorso capitolo, ma non è mai stata data una definizione completa. @@ -410,4 +410,4 @@ Questa non è una lista esaustiva, in quanto ci sono infatti altri tipi di nodi Le torce in Minetest Game usano in verità due diverse definizioni dei nodi mesh (default:torch e default:torch_wall). -Come al solito, consulta la [documentazione sull'API Lua](../../lua_api.html#node-drawtypes) per l'elenco completo. +Come al solito, consulta la [documentazione sull'API Lua](https://minetest.gitlab.io/minetest/nodes/#node-drawtypes) per l'elenco completo. diff --git a/_it/map/objects.md b/_it/map/objects.md index 657fb40..6b1d082 100644 --- a/_it/map/objects.md +++ b/_it/map/objects.md @@ -15,10 +15,10 @@ degrad: In questo capitolo imparerai come manipolare gli oggetti e come definirne di tuoi. -- [Cosa sono gli oggetti, i giocatori e le entità?](#cosa-sono-gli-oggetti-i-giocatori-e-le-entita) -- [Posizione e velocità](#posizione-e-velocita) -- [Proprietà degli oggetti](#proprieta-degli-oggetti) -- [Entità](#entita) +- [Cosa sono gli oggetti, i giocatori e le entità?](#cosa-sono-gli-oggetti-i-giocatori-e-le-entità) +- [Posizione e velocità](#posizione-e-velocità) +- [Proprietà degli oggetti](#proprietà-degli-oggetti) +- [Entità](#entità) - [Oggetti figli](#oggetti-figli) - [Il tuo turno](#il-tuo-turno) @@ -129,7 +129,7 @@ print("L'entità si trova a " .. minetest.pos_to_string(oggetto:get_pos())) ``` Ci sono diversi callback disponibili da usare per le entità. -Una lista completa può essere trovata in [lua_api.txt]({{ page.root }}/lua_api.html#registered-entities). +Una lista completa può essere trovata in [lua_api.txt](https://minetest.gitlab.io/minetest/minetest-namespace-reference/#registered-definition-tables). ```lua function MiaEntita:on_step(dtime) diff --git a/_it/players/formspecs.md b/_it/players/formspecs.md index 11baae8..26083b7 100644 --- a/_it/players/formspecs.md +++ b/_it/players/formspecs.md @@ -64,7 +64,7 @@ Si possono concatenare più elementi, piazzandoli eventualmente su più linee: bo[param1] Gli elementi sono o oggetti come i campi di testo e i pulsanti, o dei metadati come la grandezza e lo sfondo. -Per una lista esaustiva di tutti i possibili elementi, si rimanda a [lua_api.txt](../../lua_api.html#elements). +Per una lista esaustiva di tutti i possibili elementi, si rimanda a [lua_api.txt](https://minetest.gitlab.io/minetest/formspec/). ### Intestazione @@ -72,7 +72,7 @@ L'intestazione di un formspec contiene informazioni che devono apparire prima di Questo include la grandezza del formspec, la posizione, l'ancoraggio, e se il tema specifico del gioco debba venir applicato. Gli elementi nell'intestazione devono essere definiti in un ordine preciso, altrimenti ritorneranno un errore. -L'ordine è dato nel paragrafo qui in alto e, come sempre, documentato in [lua_api.txt](../../lua_api.html#sizewhfixed_size). +L'ordine è dato nel paragrafo qui in alto e, come sempre, documentato inlua_api.txt. La grandezza è in caselle formspec - un'unità di misura che è circa 64 pixel, ma varia a seconda della densità dello schermo e delle impostazioni del client. Ecco un formspec di 2x2: diff --git a/_it/players/hud.md b/_it/players/hud.md index 986b5f2..899dfba 100644 --- a/_it/players/hud.md +++ b/_it/players/hud.md @@ -13,15 +13,15 @@ Le HUD (Heads Up Display) ti permettono di mostrare testi, immagini e altri elem Le HUD, infatti, non accettano input dall'utente, lasciando quel ruolo ai [formspec](formspecs.html). - [Posizionamento](#posizionamento) - - [Posizione e scostamento](#posizione-e-scostamento) - - [Allineamento](#allineamento) - - [Esempio: tabellone segnapunti](#esempio-tabellone-segnapunti) + - [Posizione e scostamento](#posizione-e-scostamento) + - [Allineamento](#allineamento) + - [Esempio: tabellone segnapunti](#esempio-tabellone-segnapunti) - [Elementi di testo](#elementi-di-testo) - - [Parametri](#parametri) - - [Tornando all'esempio](#tornando-all-esempio) + - [Parametri](#parametri) + - [Tornando all'esempio](#tornando-allesempio) - [Elementi immagine](#elementi-immagine) - - [Parametri](#parametri-1) - - [Tornando all'esempio](#tornando-all-esempio-1) + - [Parametri](#parametri-1) + - [Tornando all'esempio](#tornando-allesempio-1) - [Cambiare un elemento](#cambiare-un-elemento) - [Salvare gli ID](#salvare-gli-id) - [Altri elementi](#altri-elementi) @@ -278,4 +278,4 @@ end) ## Altri elementi -Dai un occhio a [lua_api.txt]({{ page.root }}/lua_api.html#hud-element-types) per una lista completa degli elementi HUD. +Dai un occhio a [lua_api.txt](https://minetest.gitlab.io/minetest/hud/) per una lista completa degli elementi HUD. diff --git a/_it/players/player_physics.md b/_it/players/player_physics.md index 8575862..22aa9b4 100644 --- a/_it/players/player_physics.md +++ b/_it/players/player_physics.md @@ -14,8 +14,8 @@ Per esempio, un valore di 2 sulla gravità, renderà la gravità di un utente du - [Esempio base](#esempio-base) - [Sovrascritture disponibili](#sovrascritture-disponibili) - - [Vecchio sistema di movimento](#vecchio-sistema-di-movimento) -- [Incompatibilità tra mod](#incompatibilita-tra-mod) + - [Vecchio sistema di movimento](#vecchio-sistema-di-movimento) +- [Incompatibilità tra mod](#incompatibilità-tra-mod) - [Il tuo turno](#il-tuo-turno) ## Esempio base @@ -36,7 +36,7 @@ minetest.register_chatcommand("antigrav", { ## Sovrascritture disponibili -`set_physics_override()` è una tabella. Stando a [lua_api.txt]({{ page.root }}/lua_api.html#player-only-no-op-for-other-objects), le chiavi possono essere: +`set_physics_override()` è una tabella. Stando a [lua_api.txt](https://minetest.gitlab.io/minetest/class-reference/#player-only-no-op-for-other-objects), le chiavi possono essere: * `speed`: moltiplicatore della velocità di movimento (predefinito: 1) * `jump`: moltiplicatore del salto (predefinito: 1) diff --git a/_it/quality/readmore.md b/_it/quality/readmore.md index 295b8ea..add445b 100644 --- a/_it/quality/readmore.md +++ b/_it/quality/readmore.md @@ -12,7 +12,7 @@ Dopo aver letto questo libro, se mastichi l'inglese dai un occhio a ciò che seg ### Modding di Minetest -* Riferimento alla API Lua di Minetest - [versione HTML]({{ page.root }}/lua_api.html) | +* Riferimento alla API Lua di Minetest - [versione HTML](https://minetest.gitlab.io/minetest/) | [versione solo testo](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt). * Esplora la [Wiki Sviluppatore](http://dev.minetest.net/Main_Page). * Spulcia le [mod esistenti](https://forum.minetest.net/viewforum.php?f=11). diff --git a/_layouts/default.html b/_layouts/default.html index 83222ae..4ad7444 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -31,8 +31,6 @@ layout: base {% assign last_section = section %} {% assign num = num | plus:1 %} {% endfor %} - -
  • Lua Modding API Reference
  • Download Examples
    • diff --git a/lua_api.html b/lua_api.html index b151a64..f4ed7bb 100644 --- a/lua_api.html +++ b/lua_api.html @@ -1,6955 +1,3 @@ --- -title: Lua Modding API Reference -layout: default -root: . +redirect_to: https://minetest.gitlab.io/minetest/ --- -
    -

    This is lua_api.txt nicely formated: I did not write this

    -This page was last updated 29/March/2018.
    See doc/lua_api.txt for the latest version (in plaintext).
    Generated using a Python script.
    -

    Table of Contents

    -
    - -
    - -

    Introduction

    -

    Content and functionality can be added to Minetest using Lua scripting -in run-time loaded mods.

    -

    A mod is a self-contained bunch of scripts, textures and other related -things, which is loaded by and interfaces with Minetest.

    -

    Mods are contained and ran solely on the server side. Definitions and media -files are automatically transferred to the client.

    -

    If you see a deficiency in the API, feel free to attempt to add the -functionality in the engine and API, and to document it here.

    -This page was last updated 29/March/2018.
    See doc/lua_api.txt for the latest version (in plaintext).
    Generated using a Python script.

    Programming in Lua

    -

    If you have any difficulty in understanding this, please read -Programming in Lua.

    -

    Startup

    -

    Mods are loaded during server startup from the mod load paths by running -the init.lua scripts in a shared environment.

    -

    Paths

    - -

    Games

    -

    Games are looked up from:

    - -

    Where gameid is unique to each game.

    -

    The game directory can contain the following files:

    - - -

    Games can provide custom main menu images. They are put inside a menu -directory inside the game directory.

    -

    The images are named $identifier.png, where $identifier is one of -overlay, background, footer, header. -If you want to specify multiple images for one identifier, add additional -images named like $identifier.$n.png, with an ascending number $n starting -with 1, and a random image will be chosen from the provided ones.

    -

    Mod load path

    -

    Generic:

    - -

    In a run-in-place version (e.g. the distributed windows version):

    - -

    On an installed version on Linux:

    - -

    Mod load path for world-specific games

    -

    It is possible to include a game in a world; in this case, no mods or -games are loaded or checked from anywhere else.

    -

    This is useful for e.g. adventure worlds.

    -

    This happens if the following directory exists:

    -
    $world/game/
-
    -

    Mods should be then be placed in:

    -
    $world/game/mods/
-
    -

    Modpack support

    -

    Mods can be put in a subdirectory, if the parent directory, which otherwise -should be a mod, contains a file named modpack.txt. This file shall be -empty, except for lines starting with #, which are comments.

    -

    Mod directory structure

    -
    mods
-|-- modname
-|   |-- mod.conf
-|   |-- screenshot.png
-|   |-- settingtypes.txt
-|   |-- init.lua
-|   |-- models
-|   |-- textures
-|   |   |-- modname_stuff.png
-|   |   `-- modname_something_else.png
-|   |-- sounds
-|   |-- media
-|   |-- locale
-|   `-- <custom data>
-`-- another
-
    -

    modname

    -

    The location of this directory can be fetched by using -minetest.get_modpath(modname).

    -

    mod.conf

    -

    A key-value store of mod details.

    - -

    Note: to support 0.4.x, please also provide depends.txt.

    -

    screenshot.png

    -

    A screenshot shown in the mod manager within the main menu. It should -have an aspect ratio of 3:2 and a minimum size of 300×200 pixels.

    -

    depends.txt

    -

    Deprecated: you should use mod.conf instead.

    -

    This file is used if there are no dependencies in mod.conf.

    -

    List of mods that have to be loaded before loading this mod.

    -

    A single line contains a single modname.

    -

    Optional dependencies can be defined by appending a question mark -to a single modname. This means that if the specified mod -is missing, it does not prevent this mod from being loaded.

    -

    description.txt

    -

    Deprecated: you should use mod.conf instead.

    -

    This file is used if there is no description in mod.conf.

    -

    A file containing a description to be shown in the Mods tab of the mainmenu.

    -

    settingtypes.txt

    -

    A file in the same format as the one in builtin. It will be parsed by the -settings menu and the settings will be displayed in the "Mods" category.

    -

    init.lua

    -

    The main Lua script. Running this script should register everything it -wants to register. Subsequent execution depends on minetest calling the -registered callbacks.

    -

    minetest.settings can be used to read custom or existing settings at load -time, if necessary. (See Settings)

    -

    models

    -

    Models for entities or meshnodes.

    -

    textures, sounds, media

    -

    Media files (textures, sounds, whatever) that will be transferred to the -client and will be available for use by the mod.

    -

    locale

    -

    Translation files for the clients. (See Translations)

    -

    Naming convention for registered textual names

    -

    Registered names should generally be in this format:

    -
    `modname:<whatever>`
-
    -

    <whatever> can have these characters:

    -
    a-zA-Z0-9_
-
    -

    This is to prevent conflicting names from corrupting maps and is -enforced by the mod loader.

    -

    Example

    -

    In the mod experimental, there is the ideal item/node/entity name tnt. -So the name should be experimental:tnt.

    -

    Enforcement can be overridden by prefixing the name with :. This can -be used for overriding the registrations of some other mod.

    -

    Example: Any mod can redefine experimental:tnt by using the name

    -
    :experimental:tnt
-
    -

    when registering it. -(also that mod is required to have experimental as a dependency)

    -

    The : prefix can also be used for maintaining backwards compatibility.

    -

    Aliases

    -

    Aliases can be added by using minetest.register_alias(name, convert_to) or -minetest.register_alias_force(name, convert_to).

    -

    This converts anything called name to convert_to.

    -

    The only difference between minetest.register_alias and -minetest.register_alias_force is that if an item called name exists, -minetest.register_alias will do nothing while -minetest.register_alias_force will unregister it.

    -

    This can be used for maintaining backwards compatibility.

    -

    This can also set quick access names for things, e.g. if -you have an item called epiclylongmodname:stuff, you could do

    -
    minetest.register_alias("stuff", "epiclylongmodname:stuff")
-
    -

    and be able to use /giveme stuff.

    -

    Mapgen aliases

    -

    In a game, a certain number of these must be set to tell core mapgens which -of the game's nodes are to be used by the core mapgens. For example:

    -
    minetest.register_alias("mapgen_stone", "default:stone")
-
    -

    Aliases needed for all mapgens except Mapgen v6

    -

    Base terrain:

    -

    "mapgen_stone" -"mapgen_water_source" -"mapgen_river_water_source"

    -

    Caves:

    -

    "mapgen_lava_source"

    -

    Dungeons:

    -

    Only needed for registered biomes where 'node_stone' is stone: -"mapgen_cobble" -"mapgen_stair_cobble" -"mapgen_mossycobble" -Only needed for registered biomes where 'node_stone' is desert stone: -"mapgen_desert_stone" -"mapgen_stair_desert_stone" -Only needed for registered biomes where 'node_stone' is sandstone: -"mapgen_sandstone" -"mapgen_sandstonebrick" -"mapgen_stair_sandstone_block"

    -

    Aliases needed for Mapgen v6

    -

    Terrain and biomes:

    -

    "mapgen_stone" -"mapgen_water_source" -"mapgen_lava_source" -"mapgen_dirt" -"mapgen_dirt_with_grass" -"mapgen_sand" -"mapgen_gravel" -"mapgen_desert_stone" -"mapgen_desert_sand" -"mapgen_dirt_with_snow" -"mapgen_snowblock" -"mapgen_snow" -"mapgen_ice"

    -

    Flora:

    -

    "mapgen_tree" -"mapgen_leaves" -"mapgen_apple" -"mapgen_jungletree" -"mapgen_jungleleaves" -"mapgen_junglegrass" -"mapgen_pine_tree" -"mapgen_pine_needles"

    -

    Dungeons:

    -

    "mapgen_cobble" -"mapgen_stair_cobble" -"mapgen_mossycobble" -"mapgen_stair_desert_stone"

    -

    Textures

    -

    Mods should generally prefix their textures with modname_, e.g. given -the mod name foomod, a texture could be called:

    -
    foomod_foothing.png
-
    -

    Textures are referred to by their complete name, or alternatively by -stripping out the file extension:

    - -

    Texture modifiers

    -

    There are various texture modifiers that can be used -to generate textures on-the-fly.

    -

    Texture overlaying

    -

    Textures can be overlaid by putting a ^ between them.

    -

    Example:

    -
    default_dirt.png^default_grass_side.png
-
    -

    default_grass_side.png is overlaid over default_dirt.png. -The texture with the lower resolution will be automatically upscaled to -the higher resolution texture.

    -

    Texture grouping

    -

    Textures can be grouped together by enclosing them in ( and ).

    -

    Example: cobble.png^(thing1.png^thing2.png)

    -

    A texture for thing1.png^thing2.png is created and the resulting -texture is overlaid on top of cobble.png.

    -

    Escaping

    -

    Modifiers that accept texture names (e.g. [combine) accept escaping to allow -passing complex texture names as arguments. Escaping is done with backslash and -is required for ^ and :.

    -

    Example: cobble.png^[lowpart:50:color.png\^[mask\:trans.png

    -

    The lower 50 percent of color.png^[mask:trans.png are overlaid -on top of cobble.png.

    -

    Advanced texture modifiers

    -

    Crack

    - -

    Parameters: - <t> = tile count (in each direction) - <n> = animation frame count -* <p> = current animation frame

    -

    Draw a step of the crack animation on the texture. -crack draws it normally, while cracko lays it over, keeping transparent -pixels intact.

    -

    Example:

    -
    default_cobble.png^[crack:10:1
-
    -

    [combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>:...

    - -

    Creates a texture of size <w> times <h> and blits the listed files to their -specified coordinates.

    -

    Example:

    -
    [combine:16x32:0,0=default_cobble.png:0,16=default_wood.png
-
    -

    [resize:<w>x<h>

    -

    Resizes the texture to the given dimensions.

    -

    Example:

    -
    default_sandstone.png^[resize:16x16
-
    -

    [opacity:<r>

    -

    Makes the base image transparent according to the given ratio.

    -

    r must be between 0 and 255. -0 means totally transparent. 255 means totally opaque.

    -

    Example:

    -
    default_sandstone.png^[opacity:127
-
    -

    [invert:<mode>

    -

    Inverts the given channels of the base image. -Mode may contain the characters "r", "g", "b", "a". -Only the channels that are mentioned in the mode string will be inverted.

    -

    Example:

    -
    default_apple.png^[invert:rgb
-
    -

    [brighten

    -

    Brightens the texture.

    -

    Example:

    -
    tnt_tnt_side.png^[brighten
-
    -

    [noalpha

    -

    Makes the texture completely opaque.

    -

    Example:

    -
    default_leaves.png^[noalpha
-
    -

    [makealpha:<r>,<g>,<b>

    -

    Convert one color to transparency.

    -

    Example:

    -
    default_cobble.png^[makealpha:128,128,128
-
    -

    [transform<t>

    - -

    Rotates and/or flips the image.

    -

    <t> can be a number (between 0 and 7) or a transform name. -Rotations are counter-clockwise.

    -
    0  I      identity
-1  R90    rotate by 90 degrees
-2  R180   rotate by 180 degrees
-3  R270   rotate by 270 degrees
-4  FX     flip X
-5  FXR90  flip X then rotate by 90 degrees
-6  FY     flip Y
-7  FYR90  flip Y then rotate by 90 degrees
-
    -

    Example:

    -
    default_stone.png^[transformFXR90
-
    -

    [inventorycube{<top>{<left>{<right>

    -

    Escaping does not apply here and ^ is replaced by & in texture names -instead.

    -

    Create an inventory cube texture using the side textures.

    -

    Example:

    -
    [inventorycube{grass.png{dirt.png&grass_side.png{dirt.png&grass_side.png
-
    -

    Creates an inventorycube with grass.png, dirt.png^grass_side.png and -dirt.png^grass_side.png textures

    -

    [lowpart:<percent>:<file>

    -

    Blit the lower <percent>% part of <file> on the texture.

    -

    Example:

    -
    base.png^[lowpart:25:overlay.png
-
    -

    [verticalframe:<t>:<n>

    - -

    Crops the texture to a frame of a vertical animation.

    -

    Example:

    -
    default_torch_animated.png^[verticalframe:16:8
-
    -

    [mask:<file>

    -

    Apply a mask to the base image.

    -

    The mask is applied using binary AND.

    -

    [sheet:<w>x<h>:<x>,<y>

    -

    Retrieves a tile at position x,y from the base image -which it assumes to be a tilesheet with dimensions w,h.

    -

    [colorize:<color>:<ratio>

    -

    Colorize the textures with the given color. -<color> is specified as a ColorString. -<ratio> is an int ranging from 0 to 255 or the word "alpha". If -it is an int, then it specifies how far to interpolate between the -colors where 0 is only the texture color and 255 is only <color>. If -omitted, the alpha of <color> will be used as the ratio. If it is -the word "alpha", then each texture pixel will contain the RGB of -<color> and the alpha of <color> multiplied by the alpha of the -texture pixel.

    -

    [multiply:<color>

    -

    Multiplies texture colors with the given color. -<color> is specified as a ColorString. -Result is more like what you'd expect if you put a color on top of another -color. Meaning white surfaces get a lot of your new color while black parts -don't change very much.

    -

    Hardware coloring

    -

    The goal of hardware coloring is to simplify the creation of -colorful nodes. If your textures use the same pattern, and they only -differ in their color (like colored wool blocks), you can use hardware -coloring instead of creating and managing many texture files. -All of these methods use color multiplication (so a white-black texture -with red coloring will result in red-black color).

    -

    Static coloring

    -

    This method is useful if you wish to create nodes/items with -the same texture, in different colors, each in a new node/item definition.

    -

    Global color

    -

    When you register an item or node, set its color field (which accepts a -ColorSpec) to the desired color.

    -

    An ItemStacks static color can be overwritten by the color metadata -field. If you set that field to a ColorString, that color will be used.

    -

    Tile color

    -

    Each tile may have an individual static color, which overwrites every -other coloring methods. To disable the coloring of a face, -set its color to white (because multiplying with white does nothing). -You can set the color property of the tiles in the node's definition -if the tile is in table format.

    -

    Palettes

    -

    For nodes and items which can have many colors, a palette is more -suitable. A palette is a texture, which can contain up to 256 pixels. -Each pixel is one possible color for the node/item. -You can register one node/item, which can have up to 256 colors.

    -

    Palette indexing

    -

    When using palettes, you always provide a pixel index for the given -node or ItemStack. The palette is read from left to right and from -top to bottom. If the palette has less than 256 pixels, then it is -stretched to contain exactly 256 pixels (after arranging the pixels -to one line). The indexing starts from 0.

    -

    Examples:

    - -

    Using palettes with items

    -

    When registering an item, set the item definition's palette field to -a texture. You can also use texture modifiers.

    -

    The ItemStack's color depends on the palette_index field of the -stack's metadata. palette_index is an integer, which specifies the -index of the pixel to use.

    -

    Linking palettes with nodes

    -

    When registering a node, set the item definition's palette field to -a texture. You can also use texture modifiers. -The node's color depends on its param2, so you also must set an -appropriate paramtype2:

    - -

    To colorize a node on the map, set its param2 value (according -to the node's paramtype2).

    -

    Conversion between nodes in the inventory and the on the map

    -

    Static coloring is the same for both cases, there is no need -for conversion.

    -

    If the ItemStack's metadata contains the color field, it will be -lost on placement, because nodes on the map can only use palettes.

    -

    If the ItemStack's metadata contains the palette_index field, it is -automatically transferred between node and item forms by the engine, -when a player digs or places a colored node. -You can disable this feature by setting the drop field of the node -to itself (without metadata). -To transfer the color to a special drop, you need a drop table.

    -

    Example:

    -
    minetest.register_node("mod:stone", {
-    description = "Stone",
-    tiles = {"default_stone.png"},
-    paramtype2 = "color",
-    palette = "palette.png",
-    drop = {
-        items = {
-            -- assume that mod:cobblestone also has the same palette
-            {items = {"mod:cobblestone"}, inherit_color = true },
-        }
-    }
-})
-
    -

    Colored items in craft recipes

    -

    Craft recipes only support item strings, but fortunately item strings -can also contain metadata. Example craft recipe registration:

    -
    minetest.register_craft({
-    output = minetest.itemstring_with_palette("wool:block", 3),
-    type = "shapeless",
-    recipe = {
-        "wool:block",
-        "dye:red",
-    },
-})
-
    -

    To set the color field, you can use minetest.itemstring_with_color.

    -

    Metadata field filtering in the recipe field are not supported yet, -so the craft output is independent of the color of the ingredients.

    -

    Soft texture overlay

    -

    Sometimes hardware coloring is not enough, because it affects the -whole tile. Soft texture overlays were added to Minetest to allow -the dynamic coloring of only specific parts of the node's texture. -For example a grass block may have colored grass, while keeping the -dirt brown.

    -

    These overlays are 'soft', because unlike texture modifiers, the layers -are not merged in the memory, but they are simply drawn on top of each -other. This allows different hardware coloring, but also means that -tiles with overlays are drawn slower. Using too much overlays might -cause FPS loss.

    -

    For inventory and wield images you can specify overlays which -hardware coloring does not modify. You have to set inventory_overlay -and wield_overlay fields to an image name.

    -

    To define a node overlay, simply set the overlay_tiles field of the node -definition. These tiles are defined in the same way as plain tiles: -they can have a texture name, color etc. -To skip one face, set that overlay tile to an empty string.

    -

    Example (colored grass block):

    -
    minetest.register_node("default:dirt_with_grass", {
-    description = "Dirt with Grass",
-    -- Regular tiles, as usual
-    -- The dirt tile disables palette coloring
-    tiles = { {name = "default_grass.png"},
-        {name = "default_dirt.png", color = "white"}},
-    -- Overlay tiles: define them in the same style
-    -- The top and bottom tile does not have overlay
-    overlay_tiles = {"", "",
-        {name = "default_grass_side.png", tileable_vertical = false}},
-    -- Global color, used in inventory
-    color = "green",
-    -- Palette in the world
-    paramtype2 = "color",
-    palette = "default_foilage.png",
-})
-
    -

    Sounds

    -

    Only Ogg Vorbis files are supported.

    -

    For positional playing of sounds, only single-channel (mono) files are -supported. Otherwise OpenAL will play them non-positionally.

    -

    Mods should generally prefix their sounds with modname_, e.g. given -the mod name "foomod", a sound could be called:

    -
    foomod_foosound.ogg
-
    -

    Sounds are referred to by their name with a dot, a single digit and the -file extension stripped out. When a sound is played, the actual sound file -is chosen randomly from the matching sounds.

    -

    When playing the sound foomod_foosound, the sound is chosen randomly -from the available ones of the following files:

    - -

    Examples of sound parameter tables:

    -
    -- Play locationless on all clients
-{
-    gain = 1.0, -- default
-    fade = 0.0, -- default, change to a value > 0 to fade the sound in
-    pitch = 1.0, -- default
-}
--- Play locationless to one player
-{
-    to_player = name,
-    gain = 1.0, -- default
-    fade = 0.0, -- default, change to a value > 0 to fade the sound in
-    pitch = 1.0, -- default
-}
--- Play locationless to one player, looped
-{
-    to_player = name,
-    gain = 1.0, -- default
-    loop = true,
-}
--- Play in a location
-{
-    pos = {x = 1, y = 2, z = 3},
-    gain = 1.0, -- default
-    max_hear_distance = 32, -- default, uses an euclidean metric
-}
--- Play connected to an object, looped
-{
-    object = <an ObjectRef>,
-    gain = 1.0, -- default
-    max_hear_distance = 32, -- default, uses an euclidean metric
-    loop = true,
-}
-
    -

    Looped sounds must either be connected to an object or played locationless to -one player using to_player = name,

    -

    SimpleSoundSpec

    - -

    Registered definitions of stuff

    -

    Anything added using certain minetest.register_* functions get added to -the global minetest.registered_* tables.

    - -

    Note that in some cases you will stumble upon things that are not contained -in these tables (e.g. when a mod has been removed). Always check for -existence before trying to access the fields.

    -

    Example: If you want to check the drawtype of a node, you could do:

    -
    local function get_nodedef_field(nodename, fieldname)
-    if not minetest.registered_nodes[nodename] then
-        return nil
-    end
-    return minetest.registered_nodes[nodename][fieldname]
-end
-local drawtype = get_nodedef_field(nodename, "drawtype")
-
    -

    Example: minetest.get_item_group(name, group) has been implemented as:

    -
    function minetest.get_item_group(name, group)
-    if not minetest.registered_items[name] or not
-            minetest.registered_items[name].groups[group] then
-        return 0
-    end
-    return minetest.registered_items[name].groups[group]
-end
-
    -

    Nodes

    -

    Nodes are the bulk data of the world: cubes and other things that take the -space of a cube. Huge amounts of them are handled efficiently, but they -are quite static.

    -

    The definition of a node is stored and can be accessed by name in

    -
    minetest.registered_nodes[node.name]
-
    -

    See "Registered definitions of stuff".

    -

    Nodes are passed by value between Lua and the engine. -They are represented by a table:

    -
    {name="name", param1=num, param2=num}
-
    -

    param1 and param2 are 8-bit integers ranging from 0 to 255. The engine uses -them for certain automated functions. If you don't use these functions, you can -use them to store arbitrary values.

    -

    The functions of param1 and param2 are determined by certain fields in the -node definition:

    -

    param1 is reserved for the engine when paramtype != "none":

    -
    paramtype = "light"
-^ The value stores light with and without sun in its upper and lower 4 bits
-  respectively. Allows light to propagate from or through the node with
-  light value falling by 1 per node. This is essential for a light source
-  node to spread its light.
-
    -

    param2 is reserved for the engine when any of these are used:

    -
    liquidtype == "flowing"
-^ The level and some flags of the liquid is stored in param2
-drawtype == "flowingliquid"
-^ The drawn liquid level is read from param2
-drawtype == "torchlike"
-drawtype == "signlike"
-paramtype2 == "wallmounted"
-^ The rotation of the node is stored in param2. You can make this value
-  by using minetest.dir_to_wallmounted().
-paramtype2 == "facedir"
-^ The rotation of the node is stored in param2. Furnaces and chests are
-  rotated this way. Can be made by using minetest.dir_to_facedir().
-  Values range 0 - 23
-  facedir / 4 = axis direction:
-  0 = y+    1 = z+    2 = z-    3 = x+    4 = x-    5 = y-
-  facedir modulo 4 = rotation around that axis
-paramtype2 == "leveled"
-^ Only valid for "nodebox" with 'type = "leveled"', and "plantlike_rooted".
-  Leveled nodebox:
-    The level of the top face of the nodebox is stored in param2.
-    The other faces are defined by 'fixed = {}' like 'type = "fixed"'
-    nodeboxes.
-    The nodebox height is (param2 / 64) nodes.
-    The maximum accepted value of param2 is 127.
-  Rooted plantlike:
-    The height of the 'plantlike' section is stored in param2.
-    The height is (param2 / 16) nodes.
-paramtype2 == "degrotate"
-^ Only valid for "plantlike". The rotation of the node is stored in param2.
-  Values range 0 - 179. The value stored in param2 is multiplied by two to
-  get the actual rotation in degrees of the node.
-paramtype2 == "meshoptions"
-^ Only valid for "plantlike". The value of param2 becomes a bitfield which
-  can be used to change how the client draws plantlike nodes.
-  Bits 0, 1 and 2 form a mesh selector.
-  Currently the following meshes are choosable:
-    0 = a "x" shaped plant (ordinary plant)
-    1 = a "+" shaped plant (just rotated 45 degrees)
-    2 = a "*" shaped plant with 3 faces instead of 2
-    3 = a "#" shaped plant with 4 faces instead of 2
-    4 = a "#" shaped plant with 4 faces that lean outwards
-    5-7 are unused and reserved for future meshes.
-  Bits 3 through 7 are optional flags that can be combined and give these
-  effects:
-    bit 3 (0x08) - Makes the plant slightly vary placement horizontally
-    bit 4 (0x10) - Makes the plant mesh 1.4x larger
-    bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max)
-    bits 6-7 are reserved for future use.
-paramtype2 == "color"
-^ `param2` tells which color is picked from the palette.
-  The palette should have 256 pixels.
-paramtype2 == "colorfacedir"
-^ Same as `facedir`, but with colors.
-  The first three bits of `param2` tells which color
-  is picked from the palette.
-  The palette should have 8 pixels.
-paramtype2 == "colorwallmounted"
-^ Same as `wallmounted`, but with colors.
-  The first five bits of `param2` tells which color
-  is picked from the palette.
-  The palette should have 32 pixels.
-paramtype2 == "glasslikeliquidlevel"
-^ Only valid for "glasslike_framed" or "glasslike_framed_optional"
-  drawtypes.
-  param2 values 0-63 define 64 levels of internal liquid, 0 being empty and
-  63 being full.
-  Liquid texture is defined using `special_tiles = {"modname_tilename.png"},`
-
    -

    Nodes can also contain extra data. See "Node Metadata".

    -

    Node drawtypes

    -

    There are a bunch of different looking node types.

    -

    Look for examples in games/minimal or games/minetest_game.

    - -

    *_optional drawtypes need less rendering time if deactivated -(always client-side).

    -

    Node boxes

    -

    Node selection boxes are defined using "node boxes".

    -

    A nodebox is defined as any of:

    -
    {
-    -- A normal cube; the default in most things
-    type = "regular"
-}
-{
-    -- A fixed box (or boxes) (facedir param2 is used, if applicable)
-    type = "fixed",
-    fixed = box OR {box1, box2, ...}
-}
-{
-    -- A variable height box (or boxes) with the top face position defined
-    -- by the node parameter 'leveled = ', or if 'paramtype2 == "leveled"'
-    -- by param2.
-    -- Other faces are defined by 'fixed = {}' as with 'type = "fixed"'.
-    type = "leveled",
-    fixed = box OR {box1, box2, ...}
-}
-{
-    -- A box like the selection box for torches
-    -- (wallmounted param2 is used, if applicable)
-    type = "wallmounted",
-    wall_top = box,
-    wall_bottom = box,
-    wall_side = box
-}
-{
-    -- A node that has optional boxes depending on neighbouring nodes'
-    -- presence and type. See also `connects_to`.
-    type = "connected",
-    fixed = box OR {box1, box2, ...}
-    connect_top = box OR {box1, box2, ...}
-    connect_bottom = box OR {box1, box2, ...}
-    connect_front = box OR {box1, box2, ...}
-    connect_left = box OR {box1, box2, ...}
-    connect_back = box OR {box1, box2, ...}
-    connect_right = box OR {box1, box2, ...}
-    -- The following `disconnected_*` boxes are the opposites of the
-    -- `connect_*` ones above, i.e. when a node has no suitable neighbour
-    -- on the respective side, the corresponding disconnected box is drawn.
-    disconnected_top = box OR {box1, box2, ...}
-    disconnected_bottom = box OR {box1, box2, ...}
-    disconnected_front = box OR {box1, box2, ...}
-    disconnected_left = box OR {box1, box2, ...}
-    disconnected_back = box OR {box1, box2, ...}
-    disconnected_right = box OR {box1, box2, ...}
-    disconnected = box OR {box1, box2, ...} -- when there is *no* neighbour
-    disconnected_sides = box OR {box1, box2, ...} -- when there are *no*
-                                                    neighbours to the sides
-}
-
    -

    A box is defined as:

    -
    {x1, y1, z1, x2, y2, z2}
-
    -

    A box of a regular node would look like:

    -
    {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
-
    -

    Perlin noise

    -

    Perlin noise creates a continuously-varying value depending on the input values. -Usually in Minetest the input values are either 2D or 3D co-ordinates in nodes. -The result is used during map generation to create the terrain shape, vary heat -and humidity to distribute biomes, vary the density of decorations or vary the -structure of ores.

    -

    Structure of perlin noise

    -

    An 'octave' is a simple noise generator that outputs a value between -1 and 1. -The smooth wavy noise it generates has a single characteristic scale, almost -like a 'wavelength', so on its own does not create fine detail. -Due to this perlin noise combines several octaves to create variation on -multiple scales. Each additional octave has a smaller 'wavelength' than the -previous.

    -

    This combination results in noise varying very roughly between -2.0 and 2.0 and -with an average value of 0.0, so scale and offset are then used to multiply -and offset the noise variation.

    -

    The final perlin noise variation is created as follows:

    -

    noise = offset + scale * (octave1 + - octave2 * persistence + - octave3 * persistence ^ 2 + - octave4 * persistence ^ 3 + - ...)

    -

    Noise Parameters

    -

    Noise Parameters are commonly called NoiseParams.

    -

    offset

    -

    After the multiplication by scale this is added to the result and is the final -step in creating the noise value. -Can be positive or negative.

    -

    scale

    -

    Once all octaves have been combined, the result is multiplied by this. -Can be positive or negative.

    -

    spread

    -

    For octave1, this is roughly the change of input value needed for a very large -variation in the noise value generated by octave1. It is almost like a -'wavelength' for the wavy noise variation. -Each additional octave has a 'wavelength' that is smaller than the previous -octave, to create finer detail. spread will therefore roughly be the typical -size of the largest structures in the final noise variation.

    -

    spread is a vector with values for x, y, z to allow the noise variation to be -stretched or compressed in the desired axes. -Values are positive numbers.

    -

    seed

    -

    This is a whole number that determines the entire pattern of the noise -variation. Altering it enables different noise patterns to be created. -With other parameters equal, different seeds produce different noise patterns -and identical seeds produce identical noise patterns.

    -

    For this parameter you can randomly choose any whole number. Usually it is -preferable for this to be different from other seeds, but sometimes it is useful -to be able to create identical noise patterns.

    -

    When used in mapgen this is actually a 'seed offset', it is added to the -'world seed' to create the seed used by the noise, to ensure the noise has a -different pattern in different worlds.

    -

    octaves

    -

    The number of simple noise generators that are combined. -A whole number, 1 or more. -Each additional octave adds finer detail to the noise but also increases the -noise calculation load. -3 is a typical minimum for a high quality, complex and natural-looking noise -variation. 1 octave has a slight 'gridlike' appearence.

    -

    Choose the number of octaves according to the spread and lacunarity, and the -size of the finest detail you require. For example: -if spread is 512 nodes, lacunarity is 2.0 and finest detail required is 16 -nodes, octaves will be 6 because the 'wavelengths' of the octaves will be -512, 256, 128, 64, 32, 16 nodes.

    -

    persistence

    -

    Each additional octave has an amplitude that is the amplitude of the previous -octave multiplied by persistence, to reduce the amplitude of finer details, -as is often helpful and natural to do so. -Since this controls the balance of fine detail to large-scale detail -persistence can be thought of as the 'roughness' of the noise.

    -

    A positive or negative non-zero number, often between 0.3 and 1.0. -A common medium value is 0.5, such that each octave has half the amplitude of -the previous octave. -This may need to be tuned when altering lacunarity; when doing so consider -that a common medium value is 1 / lacunarity.

    -

    lacunarity

    -

    Each additional octave has a 'wavelength' that is the 'wavelength' of the -previous octave multiplied by 1 / lacunarity, to create finer detail. -'lacunarity' is often 2.0 so 'wavelength' often halves per octave.

    -

    A positive number no smaller than 1.0. -Values below 2.0 create higher quality noise at the expense of requiring more -octaves to cover a paticular range of 'wavelengths'.

    -

    flags

    -

    Leave this field unset for no special handling. -Currently supported are defaults, eased and absvalue:

    -

    defaults

    -

    Specify this if you would like to keep auto-selection of eased/not-eased while -specifying some other flags.

    -

    eased

    -

    Maps noise gradient values onto a quintic S-curve before performing -interpolation. This results in smooth, rolling noise. -Disable this (noeased) for sharp-looking noise with a slightly gridded -appearence. -If no flags are specified (or defaults is), 2D noise is eased and 3D noise is -not eased. -Easing a 3D noise significantly increases the noise calculation load, so use -with restraint.

    -

    absvalue

    -

    The absolute value of each octave's noise variation is used when combining the -octaves. The final perlin noise variation is created as follows:

    -

    noise = offset + scale * (abs(octave1) + - abs(octave2) * persistence + - abs(octave3) * persistence ^ 2 + - abs(octave4) * persistence ^ 3 + - ...)

    -

    Format example

    -

    For 2D or 3D perlin noise or perlin noise maps:

    -
    np_terrain = {
-    offset = 0,
-    scale = 1,
-    spread = {x = 500, y = 500, z = 500},
-    seed = 571347,
-    octaves = 5,
-    persist = 0.63,
-    lacunarity = 2.0,
-    flags = "defaults, absvalue",
-}
-
    -

    For 2D noise the Z component of spread is still defined but is ignored. -A single noise parameter table can be used for 2D or 3D noise.

    -

    Ore types

    -

    These tell in what manner the ore is generated.

    -

    All default ores are of the uniformly-distributed scatter type.

    -

    scatter

    -

    Randomly chooses a location and generates a cluster of ore.

    -

    If noise_params is specified, the ore will be placed if the 3D perlin noise -at that point is greater than the noise_threshold, giving the ability to -create a non-equal distribution of ore.

    -

    sheet

    -

    Creates a sheet of ore in a blob shape according to the 2D perlin noise -described by noise_params and noise_threshold. This is essentially an -improved version of the so-called "stratus" ore seen in some unofficial mods.

    -

    This sheet consists of vertical columns of uniform randomly distributed height, -varying between the inclusive range column_height_min and column_height_max. -If column_height_min is not specified, this parameter defaults to 1. -If column_height_max is not specified, this parameter defaults to clust_size -for reverse compatibility. New code should prefer column_height_max.

    -

    The column_midpoint_factor parameter controls the position of the column at -which ore emanates from. -If 1, columns grow upward. If 0, columns grow downward. If 0.5, columns grow -equally starting from each direction. -column_midpoint_factor is a decimal number ranging in value from 0 to 1. If -this parameter is not specified, the default is 0.5.

    -

    The ore parameters clust_scarcity and clust_num_ores are ignored for this -ore type.

    -

    puff

    -

    Creates a sheet of ore in a cloud-like puff shape.

    -

    As with the sheet ore type, the size and shape of puffs are described by -noise_params and noise_threshold and are placed at random vertical -positions within the currently generated chunk.

    -

    The vertical top and bottom displacement of each puff are determined by the -noise parameters np_puff_top and np_puff_bottom, respectively.

    -

    blob

    -

    Creates a deformed sphere of ore according to 3d perlin noise described by -noise_params. The maximum size of the blob is clust_size, and -clust_scarcity has the same meaning as with the scatter type.

    -

    vein

    -

    Creates veins of ore varying in density by according to the intersection of two -instances of 3d perlin noise with different seeds, both described by -noise_params.

    -

    random_factor varies the influence random chance has on placement of an ore -inside the vein, which is 1 by default. Note that modifying this parameter -may require adjusting noise_threshold.

    -

    The parameters clust_scarcity, clust_num_ores, and clust_size are ignored -by this ore type.

    -

    This ore type is difficult to control since it is sensitive to small changes. -The following is a decent set of parameters to work from:

    -
    noise_params = {
-    offset  = 0,
-    scale   = 3,
-    spread  = {x=200, y=200, z=200},
-    seed    = 5390,
-    octaves = 4,
-    persist = 0.5,
-    lacunarity = 2.0,
-    flags = "eased",
-},
-noise_threshold = 1.6
-
    -

    WARNING: Use this ore type very sparingly since it is ~200x more -computationally expensive than any other ore.

    -

    stratum

    -

    Creates a single undulating ore stratum that is continuous across mapchunk -borders and horizontally spans the world.

    -

    The 2D perlin noise described by noise_params defines the Y co-ordinate of -the stratum midpoint. The 2D perlin noise described by np_stratum_thickness -defines the stratum's vertical thickness (in units of nodes). Due to being -continuous across mapchunk borders the stratum's vertical thickness is -unlimited.

    -

    If the noise parameter noise_params is omitted the ore will occur from y_min -to y_max in a simple horizontal stratum.

    -

    A parameter stratum_thickness can be provided instead of the noise parameter -np_stratum_thickness, to create a constant thickness.

    -

    Leaving out one or both noise parameters makes the ore generation less -intensive, useful when adding multiple strata.

    -

    y_min and y_max define the limits of the ore generation and for performance -reasons should be set as close together as possible but without clipping the -stratum's Y variation.

    -

    Each node in the stratum has a 1-in-clust_scarcity chance of being ore, so a -solid-ore stratum would require a clust_scarcity of 1.

    -

    The parameters clust_num_ores, clust_size, noise_threshold and -random_factor are ignored by this ore type.

    -

    Ore attributes

    -

    See section "Flag Specifier Format".

    -

    Currently supported flags: -puff_cliffs, puff_additive_composition.

    -

    puff_cliffs

    -

    If set, puff ore generation will not taper down large differences in -displacement when approaching the edge of a puff. This flag has no effect for -ore types other than puff.

    -

    puff_additive_composition

    -

    By default, when noise described by np_puff_top or np_puff_bottom results -in a negative displacement, the sub-column at that point is not generated. With -this attribute set, puff ore generation will instead generate the absolute -difference in noise displacement values. This flag has no effect for ore types -other than puff.

    -

    Decoration types

    -

    The varying types of decorations that can be placed.

    -

    simple

    -

    Creates a 1 times H times 1 column of a specified node (or a random node from -a list, if a decoration list is specified). Can specify a certain node it must -spawn next to, such as water or lava, for example. Can also generate a -decoration of random height between a specified lower and upper bound. -This type of decoration is intended for placement of grass, flowers, cacti, -papyri, waterlilies and so on.

    -

    schematic

    -

    Copies a box of MapNodes from a specified schematic file (or raw description). -Can specify a probability of a node randomly appearing when placed. -This decoration type is intended to be used for multi-node sized discrete -structures, such as trees, cave spikes, rocks, and so on.

    -

    Schematic specifier

    -

    A schematic specifier identifies a schematic by either a filename to a -Minetest Schematic file (.mts) or through raw data supplied through Lua, -in the form of a table. This table specifies the following fields:

    - -

    About probability values:

    - -

    Schematic attributes

    -

    See section "Flag Specifier Format".

    -

    Currently supported flags: place_center_x, place_center_y, place_center_z, - force_placement.

    - -

    HUD element types

    -

    The position field is used for all element types.

    -

    To account for differing resolutions, the position coordinates are the -percentage of the screen, ranging in value from 0 to 1.

    -

    The name field is not yet used, but should contain a description of what the -HUD element represents. The direction field is the direction in which something -is drawn.

    -

    0 draws from left to right, 1 draws from right to left, 2 draws from -top to bottom, and 3 draws from bottom to top.

    -

    The alignment field specifies how the item will be aligned. It ranges from --1 to 1, with 0 being the center. -1 is moved to the left/up, and 1 -is to the right/down. Fractional values can be used.

    -

    The offset field specifies a pixel offset from the position. Contrary to -position, the offset is not scaled to screen size. This allows for some -precisely positioned items in the HUD.

    -

    Note: offset will adapt to screen DPI as well as user defined scaling -factor!

    -

    Below are the specific uses for fields in each type; fields not listed for that -type are ignored.

    -

    Note: Future revisions to the HUD API may be incompatible; the HUD API is -still in the experimental stages.

    -

    image

    -

    Displays an image on the HUD.

    - -

    text

    -

    Displays text on the HUD.

    - -

    statbar

    -

    Displays a horizontal bar made up of half-images.

    - -

    inventory

    - -

    waypoint

    -

    Displays distance to selected world position.

    - -

    Representations of simple things

    -

    Position/vector

    -
    {x=num, y=num, z=num}
-
    -

    For helper functions see "Vector helpers".

    -

    pointed_thing

    - -

    Flag Specifier Format

    -

    Flags using the standardized flag specifier format can be specified in either -of two ways, by string or table.

    -

    The string format is a comma-delimited set of flag names; whitespace and -unrecognized flag fields are ignored. Specifying a flag in the string sets the -flag, and specifying a flag prefixed by the string "no" explicitly -clears the flag from whatever the default may be.

    -

    In addition to the standard string flag format, the schematic flags field can -also be a table of flag names to boolean values representing whether or not the -flag is set. Additionally, if a field with the flag name prefixed with "no" -is present, mapped to a boolean of any value, the specified flag is unset.

    -

    E.g. A flag field of value

    -
    {place_center_x = true, place_center_y=false, place_center_z=true}
-
    -

    is equivalent to

    -
    {place_center_x = true, noplace_center_y=true, place_center_z=true}
-
    -

    which is equivalent to

    -
    "place_center_x, noplace_center_y, place_center_z"
-
    -

    or even

    -
    "place_center_x, place_center_z"
-
    -

    since, by default, no schematic attributes are set.

    -

    Items

    -

    Item types

    -

    There are three kinds of items: nodes, tools and craftitems.

    - -

    Amount and wear

    -

    All item stacks have an amount between 0 to 65535. It is 1 by -default. Tool item stacks can not have an amount greater than 1.

    -

    Tools use a wear (=damage) value ranging from 0 to 65535. The -value 0 is the default and used is for unworn tools. The values -1 to 65535 are used for worn tools, where a higher value stands for -a higher wear. Non-tools always have a wear value of 0.

    -

    Item formats

    -

    Items and item stacks can exist in three formats: Serializes, table format -and ItemStack.

    -

    Serialized

    -

    This is called "stackstring" or "itemstring". It is a simple string with -1-3 components: the full item identifier, an optional amount and an optional -wear value. Syntax:

    -
    <identifier> [<amount>[ <wear>]]
-
    -

    Examples:

    - -

    Table format

    -

    Examples:

    -

    5 dirt nodes:

    -
    {name="default:dirt", count=5, wear=0, metadata=""}
-
    -

    A wooden pick about 1/3 worn out:

    -
    {name="default:pick_wood", count=1, wear=21323, metadata=""}
-
    -

    An apple:

    -
    {name="default:apple", count=1, wear=0, metadata=""}
-
    -

    ItemStack

    -

    A native C++ format with many helper methods. Useful for converting -between formats. See the Class reference section for details.

    -

    When an item must be passed to a function, it can usually be in any of -these formats.

    -

    Groups

    -

    In a number of places, there is a group table. Groups define the -properties of a thing (item, node, armor of entity, capabilities of -tool) in such a way that the engine and other mods can can interact with -the thing without actually knowing what the thing is.

    -

    Usage

    -

    Groups are stored in a table, having the group names with keys and the -group ratings as values. For example:

    -
    groups = {crumbly=3, soil=1}
--- ^ Default dirt
-
-groups = {crumbly=2, soil=1, level=2, outerspace=1}
--- ^ A more special dirt-kind of thing
-
    -

    Groups always have a rating associated with them. If there is no -useful meaning for a rating for an enabled group, it shall be 1.

    -

    When not defined, the rating of a group defaults to 0. Thus when you -read groups, you must interpret nil and 0 as the same value, 0.

    -

    You can read the rating of a group for an item or a node by using

    -
    minetest.get_item_group(itemname, groupname)
-
    -

    Groups of items

    -

    Groups of items can define what kind of an item it is (e.g. wool).

    -

    Groups of nodes

    -

    In addition to the general item things, groups are used to define whether -a node is destroyable and how long it takes to destroy by a tool.

    -

    Groups of entities

    -

    For entities, groups are, as of now, used only for calculating damage. -The rating is the percentage of damage caused by tools with this damage group. -See "Entity damage mechanism".

    -
    object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100})
-object.set_armor_groups({fleshy=30, cracky=80})
-
    -

    Groups of tools

    -

    Groups in tools define which groups of nodes and entities they are -effective towards.

    -

    Groups in crafting recipes

    -

    An example: Make meat soup from any meat, any water and any bowl:

    -
    {
-    output = 'food:meat_soup_raw',
-    recipe = {
-        {'group:meat'},
-        {'group:water'},
-        {'group:bowl'},
-    },
-    -- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
-}
-
    -

    Another example: Make red wool from white wool and red dye:

    -
    {
-    type = 'shapeless',
-    output = 'wool:red',
-    recipe = {'wool:white', 'group:dye,basecolor_red'},
-}
-
    -

    Special groups

    - -

    Known damage and digging time defining groups

    - -

    Examples of custom groups

    -

    Item groups are often used for defining, well, groups of items.

    - -

    Digging time calculation specifics

    -

    Groups such as crumbly, cracky and snappy are used for this -purpose. Rating is 1, 2 or 3. A higher rating for such a group implies -faster digging time.

    -

    The level group is used to limit the toughness of nodes a tool can dig -and to scale the digging times / damage to a greater extent.

    -

    Please do understand this, otherwise you cannot use the system to it's -full potential.

    -

    Tools define their properties by a list of parameters for groups. They -cannot dig other groups; thus it is important to use a standard bunch of -groups to enable interaction with tools.

    -

    Tools definition

    -

    Tools define:

    - -

    Full punch interval

    -

    When used as a weapon, the tool will do full damage if this time is spent -between punches. If e.g. half the time is spent, the tool will do half -damage.

    -

    Maximum drop level

    -

    Suggests the maximum level of node, when dug with the tool, that will drop -it's useful item. (e.g. iron ore to drop a lump of iron).

    -

    This is not automated; it is the responsibility of the node definition -to implement this.

    -

    Uses

    -

    Determines how many uses the tool has when it is used for digging a node, -of this group, of the maximum level. For lower leveled nodes, the use count -is multiplied by 3^leveldiff.

    - -

    Maximum level

    -

    Tells what is the maximum level of a node of this group that the tool will -be able to dig.

    -

    Digging times

    -

    List of digging times for different ratings of the group, for nodes of the -maximum level.

    -

    For example, as a Lua table, times={2=2.00, 3=0.70}. This would -result in the tool to be able to dig nodes that have a rating of 2 or 3 -for this group, and unable to dig the rating 1, which is the toughest. -Unless there is a matching group that enables digging otherwise.

    -

    If the result digging time is 0, a delay of 0.15 seconds is added between -digging nodes; If the player releases LMB after digging, this delay is set to 0, -i.e. players can more quickly click the nodes away instead of holding LMB.

    -

    Damage groups

    -

    List of damage for groups of entities. See "Entity damage mechanism".

    -

    Example definition of the capabilities of a tool

    -
    tool_capabilities = {
-    full_punch_interval=1.5,
-    max_drop_level=1,
-    groupcaps={
-        crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
-    }
-    damage_groups = {fleshy=2},
-}
-
    -

    This makes the tool be able to dig nodes that fulfil both of these:

    - -

    Table of resulting digging times:

    -
    crumbly        0     1     2     3     4  <- level
-     ->  0     -     -     -     -     -
-         1  0.80  1.60  1.60     -     -
-         2  0.60  1.20  1.20     -     -
-         3  0.40  0.80  0.80     -     -
-
-level diff:    2     1     0    -1    -2
-
    -

    Table of resulting tool uses:

    -
    ->  0     -     -     -     -     -
-    1   180    60    20     -     -
-    2   180    60    20     -     -
-    3   180    60    20     -     -
-
    -

    Notes:

    - -

    Entity damage mechanism

    -

    Damage calculation:

    -
    damage = 0
-foreach group in cap.damage_groups:
-    damage += cap.damage_groups[group] * limit(actual_interval /
-           cap.full_punch_interval, 0.0, 1.0)
-        * (object.armor_groups[group] / 100.0)
-        -- Where object.armor_groups[group] is 0 for inexistent values
-return damage
-
    -

    Client predicts damage based on damage groups. Because of this, it is able to -give an immediate response when an entity is damaged or dies; the response is -pre-defined somehow (e.g. by defining a sprite animation) (not implemented; -TODO). -Currently a smoke puff will appear when an entity dies.

    -

    The group immortal completely disables normal damage.

    -

    Entities can define a special armor group, which is punch_operable. This -group disables the regular damage mechanism for players punching it by hand or -a non-tool item, so that it can do something else than take damage.

    -

    On the Lua side, every punch calls:

    -

    entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, damage)

    -

    This should never be called directly, because damage is usually not handled by -the entity itself.

    - -

    To punch an entity/object in Lua, call:

    -

    object:punch(puncher, time_from_last_punch, tool_capabilities, direction)

    - -

    Node Metadata

    -

    The instance of a node in the world normally only contains the three values -mentioned in "Nodes". However, it is possible to insert extra data into a -node. It is called "node metadata"; See NodeMetaRef.

    -

    Node metadata contains two things:

    - -

    Some of the values in the key-value store are handled specially:

    - -

    Example stuff:

    -
    local meta = minetest.get_meta(pos)
-meta:set_string("formspec",
-        "size[8,9]"..
-        "list[context;main;0,0;8,4;]"..
-        "list[current_player;main;0,5;8,4;]")
-meta:set_string("infotext", "Chest");
-local inv = meta:get_inventory()
-inv:set_size("main", 8*4)
-print(dump(meta:to_table()))
-meta:from_table({
-    inventory = {
-        main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "",
-                [5] = "", [6] = "", [7] = "", [8] = "", [9] = "",
-                [10] = "", [11] = "", [12] = "", [13] = "",
-                [14] = "default:cobble", [15] = "", [16] = "", [17] = "",
-                [18] = "", [19] = "", [20] = "default:cobble", [21] = "",
-                [22] = "", [23] = "", [24] = "", [25] = "", [26] = "",
-                [27] = "", [28] = "", [29] = "", [30] = "", [31] = "",
-                [32] = ""}
-    },
-    fields = {
-        formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
-        infotext = "Chest"
-    }
-})
-
    -

    Item Metadata

    -

    Item stacks can store metadata too. See ItemStackMetaRef.

    -

    Item metadata only contains a key-value store.

    -

    Some of the values in the key-value store are handled specially:

    - -

    Example stuff:

    -
    local meta = stack:get_meta()
-meta:set_string("key", "value")
-print(dump(meta:to_table()))
-
    -

    Formspec

    -

    Formspec defines a menu. Currently not much else than inventories are -supported. It is a string, with a somewhat strange format.

    -

    Spaces and newlines can be inserted between the blocks, as is used in the -examples.

    -

    WARNING: Minetest allows you to add elements to every single formspec instance -using player:set_formspec_prepend(), which may be the reason backgrounds are -appearing when you don't expect them to. See no_prepend[]

    -

    Examples

    -

    Chest

    -
    size[8,9]
-list[context;main;0,0;8,4;]
-list[current_player;main;0,5;8,4;]
-
    -

    Furnace

    -
    size[8,9]
-list[context;fuel;2,3;1,1;]
-list[context;src;2,1;1,1;]
-list[context;dst;5,1;2,2;]
-list[current_player;main;0,5;8,4;]
-
    -

    Minecraft-like player inventory

    -
    size[8,7.5]
-image[1,0.6;1,2;player.png]
-list[current_player;main;0,3.5;8,4;]
-list[current_player;craft;3,0;3,3;]
-list[current_player;craftpreview;7,1;1,1;]
-
    -

    Elements

    -

    size[<W>,<H>,<fixed_size>]

    - -

    position[<X>,<Y>]

    - -

    anchor[<X>,<Y>]

    - -

    no_prepend[]

    - -

    container[<X>,<Y>]

    - -

    container_end[]

    - -

    list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]

    - -

    list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]

    - -

    listring[<inventory location>;<list name>]

    - -

    listring[]

    - -

    listcolors[<slot_bg_normal>;<slot_bg_hover>]

    - -

    listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]

    - -

    listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]

    - -

    tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>;<fontcolor>]

    - -

    image[<X>,<Y>;<W>,<H>;<texture name>]

    - -

    item_image[<X>,<Y>;<W>,<H>;<item name>]

    - -

    bgcolor[<color>;<fullscreen>]

    - -

    background[<X>,<Y>;<W>,<H>;<texture name>]

    - -

    background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]

    - -

    pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]

    - -

    field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]

    - -

    field[<name>;<label>;<default>]

    - -

    field_close_on_enter[<name>;<close_on_enter>]

    - -

    textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]

    - -

    label[<X>,<Y>;<label>]

    - -

    vertlabel[<X>,<Y>;<label>]

    - -

    button[<X>,<Y>;<W>,<H>;<name>;<label>]

    - -

    image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]

    - -

    image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]

    - -

    item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]

    - -

    button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]

    - -

    image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]

    - -

    textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]

    - -

    textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]

    - -

    tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]

    - -

    box[<X>,<Y>;<W>,<H>;<color>]

    - - - -

    checkbox[<X>,<Y>;<name>;<label>;<selected>]

    - -

    scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]

    - -

    table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]

    - -

    tableoptions[<opt 1>;<opt 2>;...]

    - -

    tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]

    - -

    Note: do not use a element name starting with key_; those names are -reserved to pass key press events to formspec!

    -

    Inventory locations

    - -

    Player Inventory lists

    - -

    ColorString

    -

    #RGB defines a color in hexadecimal format.

    -

    #RGBA defines a color in hexadecimal format and alpha channel.

    -

    #RRGGBB defines a color in hexadecimal format.

    -

    #RRGGBBAA defines a color in hexadecimal format and alpha channel.

    -

    Named colors are also supported and are equivalent to -CSS Color Module Level 4. -To specify the value of the alpha channel, append #AA to the end of the color -name (e.g. colorname#08). For named colors the hexadecimal string -representing the alpha value must (always) be two hexadecimal digits.

    -

    ColorSpec

    -

    A ColorSpec specifies a 32-bit color. It can be written in either: -table form, each element ranging from 0..255 (a, if absent, defaults to 255): - colorspec = {a=255, r=0, g=255, b=0} -numerical form, the raw integer value of an ARGB8 quad: - colorspec = 0xFF00FF00 -or string form, a ColorString (defined above): - colorspec = "green"

    -

    Escape sequences

    -

    Most text can contain escape sequences, that can for example color the text. -There are a few exceptions: tab headers, dropdowns and vertical labels can't. -The following functions provide escape sequences:

    - -

    Spatial Vectors

    -

    For the following functions, v, v1, v2 are vectors, -p1, p2 are positions:

    - -

    For the following functions x can be either a vector or a number:

    - -

    Helper functions

    - -

    Translations

    -

    Texts can be translated client-side with the help of minetest.translate and -translation files.

    -

    Translating a string

    -

    Two functions are provided to translate strings: minetest.translate and -minetest.get_translator.

    - -

    As an extra commodity, if textdomain is nil, it is assumed to be "" instead.

    - -

    For instance, suppose we want to translate "@1 Wool" with "@1" being replaced - by the translation of "Red". We can do the following:

    -
    local S = minetest.get_translator()
-S("@1 Wool", S("Red"))
-
    -

    This will be displayed as "Red Wool" on old clients and on clients that do - not have localization enabled. However, if we have for instance a translation - file named wool.fr.tr containing the following:

    -
    @1 Wool=Laine @1
-Red=Rouge
-
    -

    this will be displayed as "Laine Rouge" on clients with a French locale.

    -

    Operations on translated strings

    -

    The output of minetest.translate is a string, with escape sequences adding -additional information to that string so that it can be translated on the -different clients. In particular, you can't expect operations like string.length -to work on them like you would expect them to, or string.gsub to work in the -expected manner. However, string concatenation will still work as expected -(note that you should only use this for things like formspecs; do not translate -sentences by breaking them into parts; arguments should be used instead), and -operations such as minetest.colorize which are also concatenation.

    -

    Translation file format

    -

    A translation file has the suffix .[lang].tr, where [lang] is the language -it corresponds to. -The file should be a text file, with the following format:

    - -

    Escapes

    -

    Strings that need to be translated can contain several escapes, preceded by @.

    - -

    minetest namespace reference

    -

    Utilities

    - -

    Logging

    - -

    Registration functions

    -

    Call these functions only at load time!

    - -

    Global callback registration functions

    -

    Call these functions only at load time!

    - -

    Other registration functions

    - - - -

    Authentication

    - -

    minetest.set_player_password, minetest_set_player_privs, -minetest_get_player_privs and minetest.auth_reload call the authentication -handler.

    -

    Chat

    - -

    Environment access

    - -

    Mod channels

    -

    You can find mod channels communication scheme in docs/mod_channels.png.

    - -

    Inventory

    -

    minetest.get_inventory(location): returns an InvRef

    - -

    Formspec

    - -

    Item handling

    - -

    Rollback

    - -

    Defaults for the on_* item definition functions

    -

    These functions return the leftover itemstack.

    - -

    Defaults for the on_punch and on_dig node definition callbacks

    - -

    Sounds

    - -

    Timing

    - -

    Server

    - -

    Bans

    - -

    Particles

    - -

    Schematics

    - -

    HTTP Requests:

    - -

    Storage API:

    - -

    Misc.

    - -

    Global objects

    - -

    Global tables

    - -

    Class reference

    -

    ModChannel

    -

    An interface to use mod channels on client and server

    -

    Methods

    - -

    MetaDataRef

    -

    See StorageRef, NodeMetaRef and ItemStackMetaRef.

    -

    Methods

    - -

    NodeMetaRef

    -

    Node metadata: reference extra data and functionality stored in a node. -Can be obtained via minetest.get_meta(pos).

    -

    Methods

    - -

    ItemStackMetaRef

    -

    ItemStack metadata: reference extra data and functionality stored in a stack. -Can be obtained via item:get_meta().

    -

    Methods

    - -

    StorageRef

    -

    Mod metadata: per mod metadata, saved automatically. -Can be obtained via minetest.get_mod_storage() during load time.

    -

    Methods

    - -

    NodeTimerRef

    -

    Node Timers: a high resolution persistent per-node timer. -Can be gotten via minetest.get_node_timer(pos).

    -

    Methods

    - -

    ObjectRef

    -

    Moving things in the game are generally these.

    -

    This is basically a reference to a C++ ServerActiveObject

    -

    Methods

    - -
    LuaEntitySAO-only (no-op for other objects)
    - -
    Player-only (no-op for other objects)
    - -

    InvRef

    -

    An InvRef is a reference to an inventory.

    -

    Methods

    - -

    AreaStore

    -

    A fast access data structure to store areas, and find areas near a given -position or area. -Every area has a data string attribute to store additional information. -You can create an empty AreaStore by calling AreaStore(), or -AreaStore(type_name). -If you chose the parameter-less constructor, a fast implementation will be -automatically chosen for you.

    -

    Methods

    - -

    ItemStack

    -

    An ItemStack is a stack of items.

    -

    It can be created via ItemStack(x), where x is an ItemStack, -an itemstring, a table or nil.

    -

    Methods

    - -

    PseudoRandom

    -

    A 16-bit pseudorandom number generator. -Uses a well-known LCG algorithm introduced by K&R.

    -

    It can be created via PseudoRandom(seed).

    -

    Methods

    - -

    PcgRandom

    -

    A 32-bit pseudorandom number generator. -Uses PCG32, an algorithm of the permuted congruential generator family, -offering very strong randomness.

    -

    It can be created via PcgRandom(seed) or PcgRandom(seed, sequence).

    -

    Methods

    - -

    SecureRandom

    -

    Interface for the operating system's crypto-secure PRNG.

    -

    It can be created via SecureRandom(). The constructor returns nil if a -secure random device cannot be found on the system.

    -

    Methods

    - -

    PerlinNoise

    -

    A perlin noise generator. -It can be created via PerlinNoise(seed, octaves, persistence, scale) -or PerlinNoise(noiseparams). -Alternatively with minetest.get_perlin(seeddiff, octaves, persistence, scale) -or minetest.get_perlin(noiseparams).

    -

    Methods

    - -

    PerlinNoiseMap

    -

    A fast, bulk perlin noise generator.

    -

    It can be created via PerlinNoiseMap(noiseparams, size) or -minetest.get_perlin_map(noiseparams, size).

    -

    Format of size is {x=dimx, y=dimy, z=dimz}. The z component is omitted -for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise -nil is returned).

    -

    For each of the functions with an optional buffer parameter: If buffer is -not nil, this table will be used to store the result instead of creating a new -table.

    -

    Methods

    - -

    VoxelManip

    -

    About VoxelManip

    -

    VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator' -facility. The purpose of this object is for fast, low-level, bulk access to -reading and writing Map content. As such, setting map nodes through VoxelManip -will lack many of the higher level features and concepts you may be used to -with other methods of setting nodes. For example, nodes will not have their -construction and destruction callbacks run, and no rollback information is -logged.

    -

    It is important to note that VoxelManip is designed for speed, and not ease -of use or flexibility. If your mod requires a map manipulation facility that -will handle 100% of all edge cases, or the use of high level node placement -features, perhaps minetest.set_node() is better suited for the job.

    -

    In addition, VoxelManip might not be faster, or could even be slower, for your -specific use case. VoxelManip is most effective when setting large areas of map -at once - for example, if only setting a 3x3x3 node area, a -minetest.set_node() loop may be more optimal. Always profile code using both -methods of map manipulation to determine which is most appropriate for your -usage.

    -

    A recent simple test of setting cubic areas showed that minetest.set_node() -is faster than a VoxelManip for a 3x3x3 node cube or smaller.

    -

    Using VoxelManip

    -

    A VoxelManip object can be created any time using either: -VoxelManip([p1, p2]), or minetest.get_voxel_manip([p1, p2]).

    -

    If the optional position parameters are present for either of these routines, -the specified region will be pre-loaded into the VoxelManip object on creation. -Otherwise, the area of map you wish to manipulate must first be loaded into the -VoxelManip object using VoxelManip:read_from_map().

    -

    Note that VoxelManip:read_from_map() returns two position vectors. The region -formed by these positions indicate the minimum and maximum (respectively) -positions of the area actually loaded in the VoxelManip, which may be larger -than the area requested. For convenience, the loaded area coordinates can also -be queried any time after loading map data with VoxelManip:get_emerged_area().

    -

    Now that the VoxelManip object is populated with map data, your mod can fetch a -copy of this data using either of two methods. VoxelManip:get_node_at(), -which retrieves an individual node in a MapNode formatted table at the position -requested is the simplest method to use, but also the slowest.

    -

    Nodes in a VoxelManip object may also be read in bulk to a flat array table -using:

    - -

    See section 'Flat array format' for more details.

    -

    It is very important to understand that the tables returned by any of the above -three functions represent a snapshot of the VoxelManip's internal state at the -time of the call. This copy of the data will not magically update itself if -another function modifies the internal VoxelManip state. -Any functions that modify a VoxelManip's contents work on the VoxelManip's -internal state unless otherwise explicitly stated.

    -

    Once the bulk data has been edited to your liking, the internal VoxelManip -state can be set using:

    - -

    The parameter to each of the above three functions can use any table at all in -the same flat array format as produced by get_data() etc. and is not required -to be a table retrieved from get_data().

    -

    Once the internal VoxelManip state has been modified to your liking, the -changes can be committed back to the map by calling VoxelManip:write_to_map()

    -
    Flat array format
    -

    Let - Nx = p2.X - p1.X + 1, - Ny = p2.Y - p1.Y + 1, and - Nz = p2.Z - p1.Z + 1.

    -

    Then, for a loaded region of p1..p2, this array ranges from 1 up to and -including the value of the expression Nx * Ny * Nz.

    -

    Positions offset from p1 are present in the array with the format of:

    -

    [ - (0, 0, 0), (1, 0, 0), (2, 0, 0), ... (Nx, 0, 0), - (0, 1, 0), (1, 1, 0), (2, 1, 0), ... (Nx, 1, 0), - ... - (0, Ny, 0), (1, Ny, 0), (2, Ny, 0), ... (Nx, Ny, 0), - (0, 0, 1), (1, 0, 1), (2, 0, 1), ... (Nx, 0, 1), - ... - (0, Ny, 2), (1, Ny, 2), (2, Ny, 2), ... (Nx, Ny, 2), - ... - (0, Ny, Nz), (1, Ny, Nz), (2, Ny, Nz), ... (Nx, Ny, Nz) -]

    -

    and the array index for a position p contained completely in p1..p2 is:

    -

    (p.Z - p1.Z) * Ny * Nx + (p.Y - p1.Y) * Nx + (p.X - p1.X) + 1

    -

    Note that this is the same "flat 3D array" format as -PerlinNoiseMap:get3dMap_flat(). -VoxelArea objects (see section 'VoxelArea') can be used to simplify calculation -of the index for a single point in a flat VoxelManip array.

    -
    Content IDs
    -

    A Content ID is a unique integer identifier for a specific node type. -These IDs are used by VoxelManip in place of the node name string for -VoxelManip:get_data() and VoxelManip:set_data(). You can use -minetest.get_content_id() to look up the Content ID for the specified node -name, and minetest.get_name_from_content_id() to look up the node name string -for a given Content ID. -After registration of a node, its Content ID will remain the same throughout -execution of the mod. -Note that the node being queried needs to have already been been registered.

    -

    The following builtin node types have their Content IDs defined as constants:

    - -
    Mapgen VoxelManip objects
    -

    Inside of on_generated() callbacks, it is possible to retrieve the same -VoxelManip object used by the core's Map Generator (commonly abbreviated -Mapgen). Most of the rules previously described still apply but with a few -differences:

    - -
    Other API functions operating on a VoxelManip
    -

    If any VoxelManip contents were set to a liquid node, -VoxelManip:update_liquids() must be called for these liquid nodes to begin -flowing. It is recommended to call this function only after having written all -buffered data back to the VoxelManip object, save for special situations where -the modder desires to only have certain liquid nodes begin flowing.

    -

    The functions minetest.generate_ores() and minetest.generate_decorations() -will generate all registered decorations and ores throughout the full area -inside of the specified VoxelManip object.

    -

    minetest.place_schematic_on_vmanip() is otherwise identical to -minetest.place_schematic(), except instead of placing the specified schematic -directly on the map at the specified position, it will place the schematic -inside the VoxelManip.

    -
    Notes
    - -

    Methods

    - -

    VoxelArea

    -

    A helper class for voxel areas. -It can be created via VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}. -The coordinates are inclusive, like most other things in Minetest.

    -

    Methods

    - -

    Settings

    -

    An interface to read config files in the format of minetest.conf.

    -

    It can be created via Settings(filename).

    -

    Methods

    - -

    Raycast

    -

    A raycast on the map. It works with selection boxes. -Can be used as an iterator in a for loop.

    -

    The map is loaded as the ray advances. If the -map is modified after the Raycast is created, -the changes may or may not have an effect on -the object.

    -

    It can be created via Raycast(pos1, pos2, objects, liquids) or -minetest.raycast(pos1, pos2, objects, liquids) where: - pos1: start of the ray - pos2: end of the ray - objects : if false, only nodes will be returned. Default is true. - `liquids' : if false, liquid nodes won't be returned. Default is false.

    -

    Methods

    - -

    Mapgen objects

    -

    A mapgen object is a construct used in map generation. Mapgen objects can be -used by an on_generate callback to speed up operations by avoiding -unnecessary recalculations, these can be retrieved using the -minetest.get_mapgen_object() function. If the requested Mapgen object is -unavailable, or get_mapgen_object() was called outside of an on_generate() -callback, nil is returned.

    -

    The following Mapgen objects are currently available:

    -

    voxelmanip

    -

    This returns three values; the VoxelManip object to be used, minimum and -maximum emerged position, in that order. All mapgens support this object.

    -

    heightmap

    -

    Returns an array containing the y coordinates of the ground levels of nodes in -the most recently generated chunk by the current mapgen.

    -

    biomemap

    -

    Returns an array containing the biome IDs of nodes in the most recently -generated chunk by the current mapgen.

    -

    heatmap

    -

    Returns an array containing the temperature values of nodes in the most -recently generated chunk by the current mapgen.

    -

    humiditymap

    -

    Returns an array containing the humidity values of nodes in the most recently -generated chunk by the current mapgen.

    -

    gennotify

    -

    Returns a table mapping requested generation notification types to arrays of -positions at which the corresponding generated structures are located within -the current chunk. To set the capture of positions of interest to be recorded -on generate, use minetest.set_gen_notify(). -For decorations, the returned positions are the ground surface 'place_on' -nodes, not the decorations themselves. A 'simple' type decoration is often 1 -node above the returned position and possibly displaced by 'place_offset_y'.

    -

    Possible fields of the table returned are:

    - -

    Decorations have a key in the format of "decoration#id", where id is the -numeric unique decoration ID.

    -

    Registered entities

    - -

    L-system trees

    -

    Tree definition

    -
    treedef={
-    axiom,         --string  initial tree axiom
-    rules_a,       --string  rules set A
-    rules_b,       --string  rules set B
-    rules_c,       --string  rules set C
-    rules_d,       --string  rules set D
-    trunk,         --string  trunk node name
-    leaves,        --string  leaves node name
-    leaves2,       --string  secondary leaves node name
-    leaves2_chance,--num     chance (0-100) to replace leaves with leaves2
-    angle,         --num     angle in deg
-    iterations,    --num     max # of iterations, usually 2 -5
-    random_level,  --num     factor to lower nr of iterations, usually 0 - 3
-    trunk_type,    --string  single/double/crossed) type of trunk: 1 node,
-                   --        2x2 nodes or 3x3 in cross shape
-    thin_branches, --boolean true -> use thin (1 node) branches
-    fruit,         --string  fruit node name
-    fruit_chance,  --num     chance (0-100) to replace leaves with fruit node
-    seed,          --num     random seed, if no seed is provided, the engine
-                             will create one.
-}
-
    -

    Key for Special L-System Symbols used in Axioms

    - -

    Example

    -

    Spawn a small apple tree:

    -
    pos = {x=230,y=20,z=4}
-apple_tree={
-    axiom="FFFFFAFFBF",
-    rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
-    rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
-    trunk="default:tree",
-    leaves="default:leaves",
-    angle=30,
-    iterations=2,
-    random_level=0,
-    trunk_type="single",
-    thin_branches=true,
-    fruit_chance=10,
-    fruit="default:apple"
-}
-minetest.spawn_tree(pos,apple_tree)
-
    -

    Definition tables

    -

    Object Properties

    -
    {
-    hp_max = 1,
---  ^ For players: Defaults to `minetest.PLAYER_MAX_HP_DEFAULT`
-    breath_max = 0,
---  ^ For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`
-    zoom_fov = 0.0,
---  ^ For players only. Zoom FOV in degrees.
---    Note that zoom loads and/or generates world beyond the server's
---    maximum send and generate distances, so acts like a telescope.
---    Smaller zoomFOV values increase the distance loaded and/or generated.
---    Defaults to 15 in creative mode, 0 in survival mode.
---    zoom_fov = 0 disables zooming for the player.
-    eye_height = 1.625,
---  ^ For players only. Camera height above feet position in nodes.
---    Defaults to 1.625.
-    physical = true,
-    collide_with_objects = true,
---  ^ Collide with other objects if physical = true.
-    weight = 5,
-    collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5},
-    selectionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5},
---  ^ Default, uses collision box dimensions when not set.
---  ^ For both boxes: {xmin, ymin, zmin, xmax, ymax, zmax} in nodes from
---    object position.
-    pointable = true,
---  ^ Overrides selection box when false.
-    visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem",
---  ^ "cube" is a node-sized cube.
---  ^ "sprite" is a flat texture always facing the player.
---  ^ "upright_sprite" is a vertical flat texture.
---  ^ "mesh" uses the defined mesh model.
---  ^ "wielditem" is used for dropped items
---    (see builtin/game/item_entity.lua).
---    For this use 'textures = {itemname}'.
---    If the item has a 'wield_image' the object will be an extrusion of
---    that, otherwise:
---    If 'itemname' is a cubic node or nodebox the object will appear
---    identical to 'itemname'.
---    If 'itemname' is a plantlike node the object will be an extrusion of
---    its texture.
---    Otherwise for non-node items, the object will be an extrusion of
---    'inventory_image'.
-    visual_size = {x = 1, y = 1},
---  ^ `x` multiplies horizontal (X and Z) visual size.
---  ^ `y` multiplies vertical (Y) visual size.
-    mesh = "model",
-    textures = {},
---  ^ Number of required textures depends on visual.
---  ^ "cube" uses 6 textures in the way a node does.
---  ^ "sprite" uses 1 texture.
---  ^ "upright_sprite" uses 2 textures: {front, back}.
---  ^ "wielditem" expects 'textures = {itemname}' (see 'visual' above).
-    colors = {},
---  ^ Number of required colors depends on visual.
-    use_texture_alpha = false,
---  ^ Use texture's alpha channel, excludes "upright_sprite" and "wielditem"
---  ^ Note: currently causes visual issues when viewed through other
---  ^ semi-transparent materials such as water.
-    spritediv = {x = 1, y = 1},
---  ^ Used with spritesheet textures for animation and/or frame selection
---    according to position relative to player.
---  ^ Defines the number of columns and rows in the spritesheet:
---    {columns, rows}.
-    initial_sprite_basepos = {x = 0, y = 0},
---  ^ Used with spritesheet textures.
---  ^ Defines the {column, row} position of the initially used frame in the
---    spritesheet.
-    is_visible = true,
-    makes_footstep_sound = false,
-    automatic_rotate = 0,
---  ^ Set constant rotation in radians per second, positive or negative.
---  ^ Set to 0 to disable constant rotation.
-    stepheight = 0,
-    automatic_face_movement_dir = 0.0,
---  ^ Automatically set yaw to movement direction, offset in degrees,
---    'false' to disable.
-    automatic_face_movement_max_rotation_per_sec = -1,
---  ^ Limit automatic rotation to this value in degrees per second,
---    value < 0 no limit.
-    backface_culling = true,
---  ^ Set to false to disable backface_culling for model.
-    glow = 0,
---  ^ Add this much extra lighting when calculating texture color.
---    Value < 0 disables light's effect on texture color.
---    For faking self-lighting, UI style entities, or programmatic coloring
---    in mods.
-    nametag = "",
---  ^ By default empty, for players their name is shown if empty.
-    nametag_color = <color>,
---  ^ Sets color of nametag as ColorSpec.
-    infotext = "",
---  ^ By default empty, text to be shown when pointed at object.
-    static_save = true,
---  ^ If false, never save this object statically. It will simply be
---    deleted when the block gets unloaded.
---    The get_staticdata() callback is never called then.
---    Defaults to 'true'
-}
-
    -

    Entity definition (register_entity)

    -
    {
---  Deprecated: Everything in object properties is read directly from here
-
-    initial_properties = --[[<initial object properties>]],
-
-    on_activate = function(self, staticdata, dtime_s),
-    on_step = function(self, dtime),
-    on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
-    on_rightclick = function(self, clicker),
-    get_staticdata = function(self),
---  ^ Called sometimes; the string returned is passed to on_activate when
---    the entity is re-activated from static state
-
-    _custom_field = whatever,
---  ^ You can define arbitrary member variables here (see item definition
---    for more info) by using a '_' prefix.
-}
-
    -

    ABM (ActiveBlockModifier) definition (register_abm)

    -
    {
-    label = "Lava cooling",
-    ^ Descriptive label for profiling purposes (optional).
-      Definitions with identical labels will be listed as one.
-    nodenames = {"default:lava_source"},
-    ^ Apply `action` function to these nodes.
-    ^ `group:groupname` can also be used here.
-    neighbors = {"default:water_source", "default:water_flowing"},
-    ^ Only apply `action` to nodes that have one of, or any
-      combination of, these neighbors.
-    ^ If left out or empty, any neighbor will do.
-    ^ `group:groupname` can also be used here.
-    interval = 1.0,
-    ^ Operation interval in seconds.
-    chance = 1,
-    ^ Chance of triggering `action` per-node per-interval is 1.0 / this
-      value.
-    catch_up = true,
-    ^ If true, catch-up behaviour is enabled: The `chance` value is
-      temporarily reduced when returning to an area to simulate time lost
-      by the area being unattended. Note that the `chance` value can often
-      be reduced to 1.
-    action = function(pos, node, active_object_count, active_object_count_wider),
-    ^ Function triggered for each qualifying node.
-    ^ `active_object_count` is number of active objects in the node's
-      mapblock.
-    ^ `active_object_count_wider` is number of active objects in the node's
-      mapblock plus all 26 neighboring mapblocks. If any neighboring
-      mapblocks are unloaded an estmate is calculated for them based on
-      loaded mapblocks.
-}
-
    -

    LBM (LoadingBlockModifier) definition (register_lbm)

    -
    {
-    label = "Upgrade legacy doors",
---  ^ Descriptive label for profiling purposes (optional).
---    Definitions with identical labels will be listed as one.
-    name = "modname:replace_legacy_door",
-    nodenames = {"default:lava_source"},
---  ^ List of node names to trigger the LBM on.
---    Also non-registered nodes will work.
---    Groups (as of group:groupname) will work as well.
-    run_at_every_load = false,
---  ^ Whether to run the LBM's action every time a block gets loaded,
---    and not just for blocks that were saved last time before LBMs were
---    introduced to the world.
-    action = func(pos, node),
-}
-
    -

    Item definition (register_node, register_craftitem, register_tool)

    -
    {
-    description = "Steel Axe",
-    groups = {}, -- key = name, value = rating; rating = 1..3.
-                    if rating not applicable, use 1.
-                    e.g. {wool = 1, fluffy = 3}
-                        {soil = 2, outerspace = 1, crumbly = 1}
-                        {bendy = 2, snappy = 1},
-                        {hard = 1, metal = 1, spikes = 1}
-    inventory_image = "default_tool_steelaxe.png",
-    inventory_overlay = "overlay.png",
-    ^ An overlay which does not get colorized.
-    wield_image = "",
-    wield_overlay = "",
-    palette = "",
-    --[[
-    ^ An image file containing the palette of a node.
-    ^ You can set the currently used color as the
-    ^ "palette_index" field of the item stack metadata.
-    ^ The palette is always stretched to fit indices
-    ^ between 0 and 255, to ensure compatibility with
-    ^ "colorfacedir" and "colorwallmounted" nodes.
-    ]]
-    color = "0xFFFFFFFF",
-    ^ The color of the item. The palette overrides this.
-    wield_scale = {x = 1, y = 1, z = 1},
-    stack_max = 99,
-    range = 4.0,
-    liquids_pointable = false,
-    tool_capabilities = {
-        full_punch_interval = 1.0,
-        max_drop_level = 0,
-        groupcaps = {
-            -- For example:
-            choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00},
-                     uses = 20, maxlevel = 2},
-        },
-        damage_groups = {groupname = damage},
-    },
-    node_placement_prediction = nil,
-    --[[
-    ^ If nil and item is node, prediction is made automatically
-    ^ If nil and item is not a node, no prediction is made
-    ^ If "" and item is anything, no prediction is made
-    ^ Otherwise should be name of node which the client immediately places
-      on ground when the player places the item. Server will always update
-      actual result to client in a short moment.
-    ]]
-    node_dig_prediction = "air",
-    --[[
-    ^ if "", no prediction is made
-    ^ if "air", node is removed
-    ^ Otherwise should be name of node which the client immediately places
-      upon digging. Server will always update actual result shortly.
-    ]]
-    sound = {
-        breaks = "default_tool_break", -- tools only
-        place = --[[<SimpleSoundSpec>]],
-    },
-
-    on_place = func(itemstack, placer, pointed_thing),
-    --[[
-    ^ Shall place item and return the leftover itemstack
-    ^ The placer may be any ObjectRef or nil.
-    ^ default: minetest.item_place ]]
-    on_secondary_use = func(itemstack, user, pointed_thing),
-    --[[
-    ^ Same as on_place but called when pointing at nothing.
-    ^ The user may be any ObjectRef or nil.
-    ^ pointed_thing : always { type = "nothing" }
-    ]]
-    on_drop = func(itemstack, dropper, pos),
-    --[[
-    ^ Shall drop item and return the leftover itemstack
-    ^ The dropper may be any ObjectRef or nil.
-    ^ default: minetest.item_drop ]]
-    on_use = func(itemstack, user, pointed_thing),
-    --[[
-    ^  default: nil
-    ^ Function must return either nil if no item shall be removed from
-      inventory, or an itemstack to replace the original itemstack.
-      e.g. itemstack:take_item(); return itemstack
-    ^ Otherwise, the function is free to do what it wants.
-    ^ The user may be any ObjectRef or nil.
-    ^ The default functions handle regular use cases.
-    ]]
-    after_use = func(itemstack, user, node, digparams),
-    --[[
-    ^  default: nil
-    ^ If defined, should return an itemstack and will be called instead of
-      wearing out the tool. If returns nil, does nothing.
-      If after_use doesn't exist, it is the same as:
-        function(itemstack, user, node, digparams)
-          itemstack:add_wear(digparams.wear)
-          return itemstack
-        end
-    ^ The user may be any ObjectRef or nil.
-    ]]
-    _custom_field = whatever,
-    --[[
-    ^ Add your own custom fields. By convention, all custom field names
-      should start with `_` to avoid naming collisions with future engine
-      usage.
-    ]]
-}
-
    -

    Tile definition

    - -

    Tile animation definition

    -
    {
-    type = "vertical_frames",
-    aspect_w = 16,
-    -- ^ specify width of a frame in pixels
-    aspect_h = 16,
-    -- ^ specify height of a frame in pixels
-    length = 3.0,
-    -- ^ specify full loop length
-}
-
-{
-    type = "sheet_2d",
-    frames_w = 5,
-    -- ^ specify width in number of frames
-    frames_h = 3,
-    -- ^ specify height in number of frames
-    frame_length = 0.5,
-    -- ^ specify length of a single frame
-}
-
    -

    Node definition (register_node)

    -
    {
-    -- <all fields allowed in item definitions>,
-
-    drawtype = "normal", -- See "Node drawtypes"
-    visual_scale = 1.0, --[[
-    ^ Supported for drawtypes "plantlike", "signlike", "torchlike",
-    ^ "firelike", "mesh".
-    ^ For plantlike and firelike, the image will start at the bottom of the
-    ^ node, for the other drawtypes the image will be centered on the node.
-    ^ Note that positioning for "torchlike" may still change. ]]
-    tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[
-    ^ Textures of node; +Y, -Y, +X, -X, +Z, -Z
-    ^ Old field name was 'tile_images'.
-    ^ List can be shortened to needed length ]]
-    overlay_tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[
-    ^ Same as `tiles`, but these textures are drawn on top of the
-    ^ base tiles. You can use this to colorize only specific parts of
-    ^ your texture. If the texture name is an empty string, that
-    ^ overlay is not drawn. Since such tiles are drawn twice, it
-    ^ is not recommended to use overlays on very common nodes. ]]
-    special_tiles = {tile definition 1, Tile definition 2}, --[[
-    ^ Special textures of node; used rarely
-    ^ Old field name was 'special_materials'.
-    ^ List can be shortened to needed length ]]
-    color = ColorSpec, --[[
-    ^ The node's original color will be multiplied with this color.
-    ^ If the node has a palette, then this setting only has an effect
-    ^ in the inventory and on the wield item. ]]
-    use_texture_alpha = false,
-    ^ Use texture's alpha channel.
-    palette = "palette.png", --[[
-    ^ The node's `param2` is used to select a pixel from the image
-    ^ (pixels are arranged from left to right and from top to bottom).
-    ^ The node's color will be multiplied with the selected pixel's
-    ^ color. Tiles can override this behavior.
-    ^ Only when `paramtype2` supports palettes. ]]
-    post_effect_color = "green#0F",
-    ^ Screen tint if player is inside node, see "ColorSpec".
-    paramtype = "none", --[[
-    ^ See "Nodes".
-    ^ paramtype = "light" allows light to propagate from or through the
-    ^ node with light value falling by 1 per node. This line is essential
-    ^ for a light source node to spread its light. ]]
-    paramtype2 = "none", -- See "Nodes"
-    place_param2 = nil, -- Force value for param2 when player places node
-    is_ground_content = true,
-    ^ If false, the cave generator will not carve through this node.
-    sunlight_propagates = false,
-    ^ If true, sunlight will go infinitely through this.
-    walkable = true, -- If true, objects collide with node
-    pointable = true, -- If true, can be pointed at
-    diggable = true, -- If false, can never be dug
-    climbable = false, -- If true, can be climbed on (ladder)
-    buildable_to = false, -- If true, placed nodes can replace this node
-    floodable = false, --[[
-    ^ If true, liquids flow into and replace this node.
-    ^ Warning: making a liquid node 'floodable' will cause problems. ]]
-    liquidtype = "none", -- "none"/"source"/"flowing"
-    liquid_alternative_flowing = "", -- Flowing version of source liquid
-    liquid_alternative_source = "", -- Source version of flowing liquid
-    liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
-    liquid_renewable = true, --[[
-    ^ If true, a new liquid source can be created by placing two or more
-      sources nearby. ]]
-    leveled = 16, --[[
-    ^ Only valid for "nodebox" drawtype with 'type = "leveled"'.
-    ^ Allows defining the nodebox height without using param2.
-    ^ The nodebox height is 'leveled' / 64 nodes.
-    ^ The maximum value of 'leveled' is 127. ]]
-    liquid_range = 8, -- number of flowing nodes around source (max. 8)
-    drowning = 0,
-    ^ Player will take this amount of damage if no bubbles are left.
-    light_source = 0, --[[
-    ^ Amount of light emitted by node.
-    ^ To set the maximum (currently 14), use the value
-    ^ 'minetest.LIGHT_MAX'.
-    ^ A value outside the range 0 to minetest.LIGHT_MAX causes undefined
-    ^ behavior.]]
-    damage_per_second = 0,
-    ^ If player is inside node, this damage is caused.
-    node_box = {type="regular"}, -- See "Node boxes"
-    connects_to = nodenames, --[[
-    ^ Used for nodebox nodes with the type == "connected"
-    ^ Specifies to what neighboring nodes connections will be drawn
-    ^ e.g. `{"group:fence", "default:wood"}` or `"default:stone"` ]]
-    connect_sides = { "top", "bottom", "front", "left", "back", "right" },
-    -- [[
-    ^ Tells connected nodebox nodes to connect only to these sides of this
-    ^ node. ]]
-    mesh = "model",
-    selection_box = {type="regular"}, --[[
-    ^ See "Node boxes".
-    ^ If drawtype "nodebox" is used and selection_box is nil, then node_box
-    ^ is used. ]]
-    legacy_facedir_simple = false,
-    ^ Support maps made in and before January 2012.
-    legacy_wallmounted = false,
-    ^ Support maps made in and before January 2012.
-    waving = 0, --[[
-    ^ Valid for mesh, nodebox, plantlike, allfaces_optional nodes.
-    ^ 1 - wave node like plants (top of node moves, bottom is fixed)
-    ^ 2 - wave node like leaves (whole node moves side-to-side)
-    ^ caveats: not all models will properly wave.
-    ^ plantlike drawtype nodes can only wave like plants.
-    ^ allfaces_optional drawtype nodes can only wave like leaves. --]]
-    sounds = {
-        footstep = <SimpleSoundSpec>,
-        dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
-        dug = <SimpleSoundSpec>,
-        place = <SimpleSoundSpec>,
-        place_failed = <SimpleSoundSpec>,
-    },
-    drop = "",
-    ^ Name of dropped node when dug. Default is the node itself.
-    ^ Alternatively:
-    drop = {
-        max_items = 1,  -- Maximum number of items to drop.
-        items = {  -- Choose max_items randomly from this list.
-            {
-                items = {"foo:bar", "baz:frob"},  -- Items to drop.
-                rarity = 1,  -- Probability of dropping is 1 / rarity.
-                inherit_color = true, -- To inherit palette color from the
-                                         node.
-            },
-        },
-    },
-
-    on_construct = func(pos), --[[
-    ^ Node constructor; called after adding node
-    ^ Can set up metadata and stuff like that
-    ^ Not called for bulk node placement (i.e. schematics and VoxelManip)
-    ^ default: nil ]]
-
-    on_destruct = func(pos), --[[
-    ^ Node destructor; called before removing node
-    ^ Not called for bulk node placement (i.e. schematics and VoxelManip)
-    ^ default: nil ]]
-
-    after_destruct = func(pos, oldnode), --[[
-    ^ Node destructor; called after removing node
-    ^ Not called for bulk node placement (i.e. schematics and VoxelManip)
-    ^ default: nil ]]
-
-    on_flood = func(pos, oldnode, newnode), --[[
-    ^ Called when a liquid (newnode) is about to flood oldnode, if
-    ^ it has `floodable = true` in the nodedef. Not called for bulk
-    ^ node placement (i.e. schematics and VoxelManip) or air nodes. If
-    ^ return true the node is not flooded, but on_flood callback will
-    ^ most likely be called over and over again every liquid update
-    ^ interval. Default: nil.
-    ^ Warning: making a liquid node 'floodable' will cause problems. ]]
-
-    preserve_metadata = func(pos, oldnode, oldmeta, drops) --[[
-    ^ Called when oldnode is about be converted to an item, but before the
-    ^ node is deleted from the world or the drops are added. This is
-    ^ generally the result of either the node being dug or an attached node
-    ^ becoming detached.
-    ^ drops is a table of ItemStacks, so any metadata to be preserved can
-    ^ be added directly to one or more of the dropped items. See
-    ^ "ItemStackMetaRef".
-    ^ default: nil ]]
-
-    after_place_node = func(pos, placer, itemstack, pointed_thing) --[[
-    ^ Called after constructing node when node was placed using
-    ^ minetest.item_place_node / minetest.place_node
-    ^ If return true no item is taken from itemstack
-    ^ `placer` may be any valid ObjectRef or nil
-    ^ default: nil ]]
-
-    after_dig_node = func(pos, oldnode, oldmetadata, digger), --[[
-    ^ oldmetadata is in table format
-    ^ Called after destructing node when node was dug using
-    ^ minetest.node_dig / minetest.dig_node
-    ^ default: nil ]]
-
-    can_dig = function(pos, [player]) --[[
-    ^ returns true if node can be dug, or false if not
-    ^ default: nil ]]
-
-    on_punch = func(pos, node, puncher, pointed_thing), --[[
-    ^ default: minetest.node_punch
-    ^ By default: Calls minetest.register_on_punchnode callbacks ]]
-
-    on_rightclick = func(pos, node, clicker, itemstack, pointed_thing),
-    --[[
-    ^ default: nil
-    ^ itemstack will hold clicker's wielded item
-    ^ Shall return the leftover itemstack
-    ^ Note: pointed_thing can be nil, if a mod calls this function
-    ^ This function does not get triggered by clients <=0.4.16 if the
-    ^ "formspec" node metadata field is set ]]
-
-    on_dig = func(pos, node, digger), --[[
-    ^ default: minetest.node_dig
-    ^ By default: checks privileges, wears out tool and removes node ]]
-
-    on_timer = function(pos,elapsed), --[[
-    ^ default: nil
-    ^ called by NodeTimers, see minetest.get_node_timer and NodeTimerRef
-    ^ elapsed is the total time passed since the timer was started
-    ^ return true to run the timer for another cycle with the same timeout
-    ^ value. ]]
-
-    on_receive_fields = func(pos, formname, fields, sender), --[[
-    ^ fields = {name1 = value1, name2 = value2, ...}
-    ^ Called when an UI form (e.g. sign text input) returns data
-    ^ default: nil ]]
-
-    allow_metadata_inventory_move = func(pos, from_list, from_index, to_list, to_index, count, player),
-    --[[
-    ^ Called when a player wants to move items inside the inventory
-    ^ Return value: number of items allowed to move ]]
-
-    allow_metadata_inventory_put = func(pos, listname, index, stack, player),
-    --[[
-    ^ Called when a player wants to put something into the inventory
-    ^ Return value: number of items allowed to put
-    ^ Return value: -1: Allow and don't modify item count in inventory ]]
-
-    allow_metadata_inventory_take = func(pos, listname, index, stack, player),
-    --[[
-    ^ Called when a player wants to take something out of the inventory
-    ^ Return value: number of items allowed to take
-    ^ Return value: -1: Allow and don't modify item count in inventory ]]
-
-    on_metadata_inventory_move = func(pos, from_list, from_index, to_list, to_index, count, player),
-    on_metadata_inventory_put = func(pos, listname, index, stack, player),
-    on_metadata_inventory_take = func(pos, listname, index, stack, player),
-    --[[
-    ^ Called after the actual action has happened, according to what was
-    ^ allowed.
-    ^ No return value ]]
-
-    on_blast = func(pos, intensity), --[[
-    ^ intensity: 1.0 = mid range of regular TNT
-    ^ If defined, called when an explosion touches the node, instead of
-      removing the node ]]
-}
-
    -

    Recipe for register_craft (shaped)

    -
    {
-    output = 'default:pick_stone',
-    recipe = {
-        {'default:cobble', 'default:cobble', 'default:cobble'},
-        {'', 'default:stick', ''},
-        {'', 'default:stick', ''}, -- Also groups; e.g. 'group:crumbly'
-    },
-    replacements = --[[<optional list of item pairs,
-                    replace one input item with another item on crafting>]]
-}
-
    -

    Recipe for register_craft (shapeless)

    -
    {
-   type = "shapeless",
-   output = 'mushrooms:mushroom_stew',
-   recipe = {
-       "mushrooms:bowl",
-       "mushrooms:mushroom_brown",
-       "mushrooms:mushroom_red",
-   },
-   replacements = --[[<optional list of item pairs,
-                   replace one input item with another item on crafting>]]
-
    -

    }

    -

    Recipe for register_craft (tool repair)

    -
    {
-    type = "toolrepair",
-    additional_wear = -0.02,
-}
-
    -

    Recipe for register_craft (cooking)

    -
    {
-    type = "cooking",
-    output = "default:glass",
-    recipe = "default:sand",
-    cooktime = 3,
-}
-
    -

    Recipe for register_craft (furnace fuel)

    -
    {
-    type = "fuel",
-    recipe = "default:leaves",
-    burntime = 1,
-}
-
    -

    Ore definition (register_ore)

    -
    See 'Ore types' section above for essential information.
-
-{
-    ore_type = "scatter",
-    ore = "default:stone_with_coal",
-    ore_param2 = 3,
---  ^ Facedir rotation. Default is 0 (unchanged rotation)
-    wherein = "default:stone",
---  ^ a list of nodenames is supported too
-    clust_scarcity = 8 * 8 * 8,
---  ^ Ore has a 1 out of clust_scarcity chance of spawning in a node
---  ^ If the desired average distance between ores is 'd', set this to
---  ^ d * d * d.
-    clust_num_ores = 8,
---  ^ Number of ores in a cluster
-    clust_size = 3,
---  ^ Size of the bounding box of the cluster
---  ^ In this example, there is a 3 * 3 * 3 cluster where 8 out of the 27
---  ^ nodes are coal ore.
-    y_min = -31000,
-    y_max = 64,
---  ^ Lower and upper limits for ore.
-    flags = "",
---  ^ Attributes for this ore generation, see 'Ore attributes' section
---  ^ above.
-    noise_threshold = 0.5,
---  ^ If noise is above this threshold, ore is placed. Not needed for a
---  ^ uniform distribution.
-    noise_params = {
-        offset = 0,
-        scale = 1,
-        spread = {x = 100, y = 100, z = 100},
-        seed = 23,
-        octaves = 3,
-        persist = 0.7
-    },
---  ^ NoiseParams structure describing one of the perlin noises used for
---  ^ ore distribution.
---  ^ Needed by "sheet", "puff", "blob" and "vein" ores.
---  ^ Omit from "scatter" ore for a uniform ore distribution.
---  ^ Omit from "stratum ore for a simple horizontal strata from y_min to
---  ^ y_max.
-    biomes = {"desert", "rainforest"}
---  ^ List of biomes in which this decoration occurs.
---  ^ Occurs in all biomes if this is omitted, and ignored if the Mapgen
---  ^ being used does not support biomes.
---  ^ Can be a list of (or a single) biome names, IDs, or definitions.
-    column_height_min = 1,
-    column_height_max = 16,
-    column_midpoint_factor = 0.5,
---  ^ See 'Ore types' section above.
---  ^ The above 3 parameters are only valid for "sheet" ore.
-    np_puff_top = {
-        offset = 4,
-        scale = 2,
-        spread = {x = 100, y = 100, z = 100},
-        seed = 47,
-        octaves = 3,
-        persist = 0.7
-    },
-    np_puff_bottom = {
-        offset = 4,
-        scale = 2,
-        spread = {x = 100, y = 100, z = 100},
-        seed = 11,
-        octaves = 3,
-        persist = 0.7
-    },
---  ^ See 'Ore types' section above.
---  ^ The above 2 parameters are only valid for "puff" ore.
-    random_factor = 1.0,
---  ^ See 'Ore types' section above.
---  ^ Only valid for "vein" ore.
-    np_stratum_thickness = {
-        offset = 8,
-        scale = 4,
-        spread = {x = 100, y = 100, z = 100},
-        seed = 17,
-        octaves = 3,
-        persist = 0.7
-    },
-    stratum_thickness = 8,
---  ^ See 'Ore types' section above.
---  ^ The above 2 parameters are only valid for "stratum" ore.
-}
-
    -

    Biome definition (register_biome)

    -
    {
-    name = "tundra",
-    node_dust = "default:snow",
---  ^ Node dropped onto upper surface after all else is generated.
-    node_top = "default:dirt_with_snow",
-    depth_top = 1,
---  ^ Node forming surface layer of biome and thickness of this layer.
-    node_filler = "default:permafrost",
-    depth_filler = 3,
---  ^ Node forming lower layer of biome and thickness of this layer.
-    node_stone = "default:bluestone",
---  ^ Node that replaces all stone nodes between roughly y_min and y_max.
-    node_water_top = "default:ice",
-    depth_water_top = 10,
---  ^ Node forming a surface layer in seawater with the defined thickness.
-    node_water = "",
---  ^ Node that replaces all seawater nodes not in the defined surface
---  ^ layer.
-    node_river_water = "default:ice",
---  ^ Node that replaces river water in mapgens that use
---  ^ default:river_water.
-    node_riverbed = "default:gravel",
-    depth_riverbed = 2,
---  ^ Node placed under river water and thickness of this layer.
-    y_max = 31000,
-    y_min = 1,
---  ^ Upper and lower limits for biome.
---  ^ Alternatively you can use xyz limits as shown below.
-    max_pos = {x = 31000, y = 128, z = 31000},
-    min_pos = {x = -31000, y = 9, z = -31000},
---  ^ xyz limits for biome, an alternative to using 'y_min' and 'y_max'.
---  ^ Biome is limited to a cuboid defined by these positions.
---  ^ Any x, y or z field left undefined defaults to -31000 in 'min_pos' or
---  ^ 31000 in 'max_pos'.
-    vertical_blend = 8,
---  ^ Vertical distance in nodes above 'y_max' over which the biome will
---  ^ blend with the biome above.
---  ^ Set to 0 for no vertical blend. Defaults to 0.
-    heat_point = 0,
-    humidity_point = 50,
---  ^ Characteristic temperature and humidity for the biome.
---  ^ These values create 'biome points' on a voronoi diagram with heat and
---  ^ humidity as axes. The resulting voronoi cells determine the
---  ^ distribution of the biomes.
---  ^ Heat and humidity have average values of 50, vary mostly between
---  ^ 0 and 100 but can exceed these values.
-}
-
    -

    Decoration definition (register_decoration)

    -
    {
-    deco_type = "simple", -- See "Decoration types"
-    place_on = "default:dirt_with_grass",
---  ^ Node (or list of nodes) that the decoration can be placed on
-    sidelen = 8,
---  ^ Size of the square divisions of the mapchunk being generated.
---  ^ Determines the resolution of noise variation if used.
---  ^ If the chunk size is not evenly divisible by sidelen, sidelen is made
---  ^ equal to the chunk size.
-    fill_ratio = 0.02,
---  ^ The value determines 'decorations per surface node'.
---  ^ Used only if noise_params is not specified.
-    noise_params = {
-        offset = 0,
-        scale = 0.45,
-        spread = {x = 100, y = 100, z = 100},
-        seed = 354,
-        octaves = 3,
-        persist = 0.7,
-        lacunarity = 2.0,
-        flags = "absvalue"
-    },
---  ^ NoiseParams structure describing the perlin noise used for decoration
---  ^ distribution.
---  ^ A noise value is calculated for each square division and determines
---  ^ 'decorations per surface node' within each division.
-    biomes = {"Oceanside", "Hills", "Plains"},
---  ^ List of biomes in which this decoration occurs. Occurs in all biomes
---  ^ if this is omitted, and ignored if the Mapgen being used does not
---  ^ support biomes.
---  ^ Can be a list of (or a single) biome names, IDs, or definitions.
-    y_min = -31000
-    y_max = 31000
---  ^ Lower and upper limits for decoration.
---  ^ These parameters refer to the Y co-ordinate of the 'place_on' node.
-    spawn_by = "default:water",
---  ^ Node (or list of nodes) that the decoration only spawns next to.
---  ^ Checks two horizontal planes of 8 neighbouring nodes (including
---  ^ diagonal neighbours), one plane level with the 'place_on' node and a
---  ^ plane one node above that.
-    num_spawn_by = 1,
---  ^ Number of spawn_by nodes that must be surrounding the decoration
---  ^ position to occur.
---  ^ If absent or -1, decorations occur next to any nodes.
-    flags = "liquid_surface, force_placement, all_floors, all_ceilings",
---  ^ Flags for all decoration types.
---  ^ "liquid_surface": Instead of placement on the highest solid surface
---  ^   in a mapchunk column, placement is on the highest liquid surface.
---  ^   Placement is disabled if solid nodes are found above the liquid
---  ^   surface.
---  ^ "force_placement": Nodes other than "air" and "ignore" are replaced
---  ^   by the decoration.
---  ^ "all_floors", "all_ceilings": Instead of placement on the highest
---  ^   surface in a mapchunk the decoration is placed on all floor and/or
---  ^   ceiling surfaces, for example in caves.
---  ^   Ceiling decorations act as an inversion of floor decorations so the
---  ^   effect of 'place_offset_y' is inverted.
---  ^   If a single decoration registration has both flags the floor and
---  ^   ceiling decorations will be aligned vertically and may sometimes
---  ^   meet to form a column.
-
-    ----- Simple-type parameters
-    decoration = "default:grass",
---  ^ The node name used as the decoration.
---  ^ If instead a list of strings, a randomly selected node from the list
---  ^ is placed as the decoration.
-    height = 1,
---  ^ Decoration height in nodes.
---  ^ If height_max is not 0, this is the lower limit of a randomly
---  ^ selected height.
-    height_max = 0,
---  ^ Upper limit of the randomly selected height.
---  ^ If absent, the parameter 'height' is used as a constant.
-    param2 = 0,
---  ^ Param2 value of decoration nodes.
---  ^ If param2_max is not 0, this is the lower limit of a randomly
---  ^ selected param2.
-    param2_max = 0,
---  ^ Upper limit of the randomly selected param2.
---  ^ If absent, the parameter 'param2' is used as a constant.
-    place_offset_y = 0,
---  ^ Y offset of the decoration base node relative to the standard base
---  ^ node position.
---  ^ Can be positive or negative. Default is 0.
---  ^ Effect is inverted for "all_ceilings" decorations.
---  ^ Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer
---  ^ to the 'place_on' node.
-
-    ----- Schematic-type parameters
-    schematic = "foobar.mts",
---  ^ If schematic is a string, it is the filepath relative to the current
---  ^ working directory of the specified Minetest schematic file.
---  ^  - OR -, could be the ID of a previously registered schematic
---  ^  - OR -, could instead be a table containing two mandatory fields,
---  ^ size and data, and an optional table yslice_prob:
-    schematic = {
-        size = {x = 4, y = 6, z = 4},
-        data = {
-            {name = "default:cobble", param1 = 255, param2 = 0},
-            {name = "default:dirt_with_grass", param1 = 255, param2 = 0},
-            {name = "air", param1 = 255, param2 = 0},
-             ...
-        },
-        yslice_prob = {
-            {ypos = 2, prob = 128},
-            {ypos = 5, prob = 64},
-             ...
-        },
-    },
---  ^ See 'Schematic specifier' for details.
-    replacements = {["oldname"] = "convert_to", ...},
-    flags = "place_center_x, place_center_y, place_center_z",
---  ^ Flags for schematic decorations.  See 'Schematic attributes'.
-    rotation = "90",
---  ^ Rotation can be "0", "90", "180", "270", or "random".
-    place_offset_y = 0,
---  ^ If the flag 'place_center_y' is set this parameter is ignored.
---  ^ Y offset of the schematic base node layer relative to the 'place_on'
---  ^ node.
---  ^ Can be positive or negative. Default is 0.
---  ^ Effect is inverted for "all_ceilings" decorations.
---  ^ Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer
---  ^ to the 'place_on' node.
-}
-
    -

    Chat command definition (register_chatcommand)

    -
    {
-    params = "<name> <privilege>", -- Short parameter description
-    description = "Remove privilege from player", -- Full description
-    privs = {privs=true}, -- Require the "privs" privilege to run
-    func = function(name, param), -- Called when command is run.
-                                  -- Returns boolean success and text
-                                  -- output.
-}
-
    -

    Note that in params, use of symbols is as follows:

    - -

    Detached inventory callbacks

    -
    {
-    allow_move = func(inv, from_list, from_index, to_list, to_index, count, player),
---  ^ Called when a player wants to move items inside the inventory
---  ^ Return value: number of items allowed to move
-
-    allow_put = func(inv, listname, index, stack, player),
---  ^ Called when a player wants to put something into the inventory
---  ^ Return value: number of items allowed to put
---  ^ Return value: -1: Allow and don't modify item count in inventory
-
-    allow_take = func(inv, listname, index, stack, player),
---  ^ Called when a player wants to take something out of the inventory
---  ^ Return value: number of items allowed to take
---  ^ Return value: -1: Allow and don't modify item count in inventory
-
-    on_move = func(inv, from_list, from_index, to_list, to_index, count, player),
-    on_put = func(inv, listname, index, stack, player),
-    on_take = func(inv, listname, index, stack, player),
---  ^ Called after the actual action has happened, according to what was
---  ^ allowed.
---  ^ No return value
-}
-
    -

    HUD Definition (hud_add, hud_get)

    -
    {
-    hud_elem_type = "image", -- see HUD element types
---  ^ type of HUD element, can be either of "image", "text", "statbar",
-      "inventory".
-    position = {x=0.5, y=0.5},
---  ^ Left corner position of element
-    name = "<name>",
-    scale = {x = 2, y = 2},
-    text = "<text>",
-    number = 2,
-    item = 3,
---  ^ Selected item in inventory.  0 for no item selected.
-    direction = 0,
---  ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
-    alignment = {x=0, y=0},
---  ^ See "HUD Element Types"
-    offset = {x=0, y=0},
---  ^ See "HUD Element Types"
-    size = { x=100, y=100 },
---  ^ Size of element in pixels
-}
-
    -

    Particle definition (add_particle)

    -
    {
-    pos = {x=0, y=0, z=0},
-    velocity = {x=0, y=0, z=0},
-    acceleration = {x=0, y=0, z=0},
---  ^ Spawn particle at pos with velocity and acceleration
-    expirationtime = 1,
---  ^ Disappears after expirationtime seconds
-    size = 1,
-    collisiondetection = false,
---  ^ collisiondetection: if true collides with physical objects
-    collision_removal = false,
---  ^ collision_removal: if true then particle is removed when it collides,
---  ^ requires collisiondetection = true to have any effect
-    vertical = false,
---  ^ vertical: if true faces player using y axis only
-    texture = "image.png",
---  ^ Uses texture (string)
-    playername = "singleplayer",
---  ^ optional, if specified spawns particle only on the player's client
-    animation = {Tile Animation definition},
---  ^ optional, specifies how to animate the particle texture
-    glow = 0
---  ^ optional, specify particle self-luminescence in darkness
-}
-
    -

    ParticleSpawner definition (add_particlespawner)

    -
    {
-    amount = 1,
-    time = 1,
---  ^ If time is 0 has infinite lifespan and spawns the amount on a
---  ^ per-second basis.
-    minpos = {x=0, y=0, z=0},
-    maxpos = {x=0, y=0, z=0},
-    minvel = {x=0, y=0, z=0},
-    maxvel = {x=0, y=0, z=0},
-    minacc = {x=0, y=0, z=0},
-    maxacc = {x=0, y=0, z=0},
-    minexptime = 1,
-    maxexptime = 1,
-    minsize = 1,
-    maxsize = 1,
---  ^ The particle's properties are random values in between the bounds:
---  ^ minpos/maxpos, minvel/maxvel (velocity),
---  ^ minacc/maxacc (acceleration), minsize/maxsize,
---  ^ minexptime/maxexptime (expirationtime).
-    collisiondetection = false,
---  ^ collisiondetection: if true uses collision detection
-    collision_removal = false,
---  ^ collision_removal: if true then particle is removed when it collides,
---  ^ requires collisiondetection = true to have any effect
-    attached = ObjectRef,
---  ^ attached: if defined, particle positions, velocities and
---  ^ accelerations are relative to this object's position and yaw.
-    vertical = false,
---  ^ vertical: if true faces player using y axis only
-    texture = "image.png",
---  ^ Uses texture (string)
-    playername = "singleplayer"
---  ^ Playername is optional, if specified spawns particle only on the
---  ^ player's client.
-    animation = {Tile Animation definition},
---  ^ optional, specifies how to animate the particle texture
-    glow = 0
---  ^ optional, specify particle self-luminescence in darkness
-}
-
    -

    HTTPRequest definition (HTTPApiTable.fetch_async, HTTPApiTable.fetch_async)

    -
    {
-    url = "http://example.org",
-    timeout = 10,
---  ^ Timeout for connection in seconds. Default is 3 seconds.
-    post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
---  ^ Optional, if specified a POST request with post_data is performed.
---  ^ Accepts both a string and a table. If a table is specified, encodes
---  ^ table as x-www-form-urlencoded key-value pairs.
---  ^ If post_data ist not specified, a GET request is performed instead.
-    user_agent = "ExampleUserAgent",
---  ^ Optional, if specified replaces the default minetest user agent with
---  ^ given string.
-    extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
---  ^ Optional, if specified adds additional headers to the HTTP request.
---  ^ You must make sure that the header strings follow HTTP specification
---  ^ ("Key: Value").
-    multipart = boolean
---  ^ Optional, if true performs a multipart HTTP request.
---  ^ Default is false.
-}
-
    -

    HTTPRequestResult definition (HTTPApiTable.fetch callback, HTTPApiTable.fetch_async_get)

    -
    {
-    completed = true,
---  ^ If true, the request has finished (either succeeded, failed or timed
-      out).
-    succeeded = true,
---  ^ If true, the request was successful
-    timeout = false,
---  ^ If true, the request timed out
-    code = 200,
---  ^ HTTP status code
-    data = "response"
-}
-
    -

    Authentication handler definition

    -
    {
-    get_auth = func(name),
---  ^ Get authentication data for existing player `name` (`nil` if player
-      doesn't exist).
---  ^ returns following structure:
---  ^ `{password=<string>, privileges=<table>, last_login=<number or nil>}`
-    create_auth = func(name, password),
---  ^ Create new auth data for player `name`
---  ^ Note that `password` is not plain-text but an arbitrary
---  ^ representation decided by the engine
-    delete_auth = func(name),
---  ^ Delete auth data of player `name`, returns boolean indicating success
---  ^ (false if player nonexistant).
-    set_password = func(name, password),
---  ^ Set password of player `name` to `password`
-       Auth data should be created if not present
-    set_privileges = func(name, privileges),
---  ^ Set privileges of player `name`
---  ^ `privileges` is in table form, auth data should be created if not
---  ^ present.
-    reload = func(),
---  ^ Reload authentication data from the storage location
---  ^ Returns boolean indicating success
-    record_login = func(name),
---  ^ Called when player joins, used for keeping track of last_login
-    iterate = func(),
---  ^ Returns an iterator (use with `for` loops) for all player names
---  ^ currently in the auth database.
-}
-
    diff --git a/sitemap.json b/sitemap.json index 43c99be..b7945dc 100644 --- a/sitemap.json +++ b/sitemap.json @@ -22,14 +22,6 @@ {% assign num = num | plus:1 %} {% endfor %} - - { - "title": "Lua Modding API Reference", - "loc": "https://rubenwardy.com/minetest_modding_book/lua_api.html", - "description": "lua_api.html is an HTML version of lua_api.txt", - "priority": 0.75 - }, - { "title": "Download Examples", "loc": "https://github.com/rubenwardy/minetest_modding_book/archive/examples.zip", diff --git a/utils/requirements.txt b/utils/requirements.txt deleted file mode 100644 index f223c09..0000000 --- a/utils/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -markdown==2.6.8 -bs4==0.0.1 diff --git a/utils/update_lua_api.py b/utils/update_lua_api.py deleted file mode 100644 index 7144f69..0000000 --- a/utils/update_lua_api.py +++ /dev/null @@ -1,112 +0,0 @@ -import markdown, urllib2, datetime, re, string -from bs4 import BeautifulSoup - -def get_key(index, li, title): - title = title.replace(" ", "-") - title = title.replace(" ", "-") - title = title.replace(" ", "-") - #title = re.sub(r'\([^)]*\)', '', title) - title = pattern.sub('', title) - - if title == "": - return None - - i = 0 - while True: - key = title - if i > 0: - key = key + "_" + str(i) - i = i + 1 - try: - existing = index[key] - except KeyError: - return key - -# -# Downloading lua_api.txt -# -print("Downloading lua_api.txt...") - -url = "https://raw.githubusercontent.com/minetest/minetest/master/doc/lua_api.txt" -text = urllib2.urlopen(url).read() -text = unicode(text, "utf-8") - - -print("Pre-generation replacements...") - -header = """Minetest Lua Modding API Reference -==================================""" -text = text.replace(header, "") - -# -# Generating HTML -# -print("Generating HTML...") -md = markdown.Markdown(extensions=['markdown.extensions.toc']) -html = md.convert(text) - -print("Post-generation replacements...") -links = """""" - -html = html.replace("{{", "{ {") -html = html.replace(links, "") - - -credit = "This page was last updated " -credit += datetime.date.today().strftime("%d/%B/%Y") -credit += ".
    See doc/lua_api.txt for the latest version (in plaintext)." -credit += "
    Generated using a Python script." -links += credit -html = html.replace("

    ", links + "

    ") - -print("Parsing HTML...") -soup = BeautifulSoup(html, 'html.parser') - -pattern = re.compile('[\W]+') -lis = soup.find_all("li") -index = {} - -# Build index of anchors -headings = soup.find_all({"h1", "h2", "h3", "h4", "h5", "h6"}) -for tag in headings: - if tag.has_attr("id"): - index[tag["id"]] = True - if tag.has_attr("name"): - index[tag["name"]] = True - -# Add anchors to
  • s containing -for li in lis: - code = li.find_all('code') - if len(code) > 0: - key = get_key(index, li, code[0].string) - if key is not None: - index[key] = True - #print("Created " + key) - new_tag = soup.new_tag('a', href="#" + key) - new_tag['class'] = "anchor" - new_tag['name'] = key - new_tag.string = "#" - li.insert(0, new_tag) - - -html = str(soup) - -# -# Writing to file -# -print("Writing to file...") -file = open("lua_api.html", "w") -file.write("---\ntitle: Lua Modding API Reference\nlayout: default\n---\n") -file.write("
    \n") -file.write("

    This is lua_api.txt nicely formated: I did not write this

    \n") -file.write(credit) -file.write("
    \n") -file.write("

    Table of Contents

    \n") -file.write(md.toc) -file.write(html) -file.close() - -print("Done")