X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=8156f785a9b6cbb4ddcaba1e99d04d2746cfaa2d;hb=83229921e5f378625d9ef63ede3dffbe778e1798;hp=f5c07fe855f42ee5c2d21703157c7dc92d257403;hpb=3ed940ff13fc2b4ef4b63f2c506ed9e5ab59f54f;p=minetest.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index f5c07fe85..8156f785a 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -2114,6 +2114,22 @@ Examples list[current_player;craft;3,0;3,3;] list[current_player;craftpreview;7,1;1,1;] +Version History +--------------- + +* FORMSPEC VERSION 1: + * (too much) +* FORMSPEC VERSION 2: + * Forced real coordinates + * background9[]: 9-slice scaling parameters +* FORMSPEC VERSION 3: + * Formspec elements are drawn in the order of definition + * bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor) + * box[] and image[] elements enable clipping by default + * new element: scroll_container[] +* FORMSPEC VERSION 4: + * Allow dropdown indexing events + Elements -------- @@ -2125,6 +2141,7 @@ Elements * Clients older than this version can neither show newer elements nor display elements with new arguments correctly. * Available since feature `formspec_version_element`. +* See also: [Version History] ### `size[,,]` @@ -2209,7 +2226,8 @@ Elements * Show an inventory list if it has been sent to the client. Nothing will be shown if the inventory list is of size 0. * **Note**: With the new coordinate system, the spacing between inventory - slots is one-fourth the size of an inventory slot. + slots is one-fourth the size of an inventory slot by default. Also see + [Styling Formspecs] for changing the size of slots and spacing. ### `list[;;,;,;]` @@ -2277,7 +2295,7 @@ Elements * `frame duration`: Milliseconds between each frame. `0` means the frames don't advance. * `frame start` (Optional): The index of the frame to start on. Default `1`. -### `model[,;,;;;;;;]` +### `model[,;,;;;;;;;]` * Show a mesh model. * `name`: Element name that can be used for styling @@ -2288,6 +2306,9 @@ Elements The axes are euler angles in degrees. * `continuous` (Optional): Whether the rotation is continuous. Default `false`. * `mouse control` (Optional): Whether the model can be controlled with the mouse. Default `true`. +* `frame loop range` (Optional): Range of the animation frames. + * Defaults to the full range of all available frames. + * Syntax: `,` ### `item_image[,;,;]` @@ -2789,6 +2810,8 @@ Some types may inherit styles from parent types. * image_button * item_image_button * label +* list +* model * pwdfield, inherits from field * scrollbar * tabheader @@ -2875,6 +2898,10 @@ Some types may inherit styles from parent types. * font - Sets font type. See button `font` property for more information. * font_size - Sets font size. See button `font_size` property for more information. * noclip - boolean, set to true to allow the element to exceed formspec bounds. +* list + * noclip - boolean, set to true to allow the element to exceed formspec bounds. + * size - 2d vector, sets the size of inventory slots in coordinates. + * spacing - 2d vector, sets the space between inventory slots in coordinates. * image_button (additional properties) * fgimg - standard image. Defaults to none. * fgimg_hovered - image when hovered. Defaults to fgimg when not provided. @@ -3248,7 +3275,8 @@ Helper functions * Appends all values in `other_table` to `table` - uses `#table + 1` to find new indices. * `table.key_value_swap(t)`: returns a table with keys and values swapped - * If multiple keys in `t` map to the same value, the result is undefined. + * If multiple keys in `t` map to the same value, it is unspecified which + value maps to that key. * `table.shuffle(table, [from], [to], [random_func])`: * Shuffles elements `from` to `to` in `table` in place * `from` defaults to `1` @@ -4186,6 +4214,8 @@ Callbacks: * Called when the object is instantiated. * `dtime_s` is the time passed since the object was unloaded, which can be used for updating the entity state. +* `on_deactivate(self) + * Called when the object is about to get removed or unloaded. * `on_step(self, dtime)` * Called on every server tick, after movement and collision processing. `dtime` is usually 0.1 seconds, as per the `dedicated_server_step` setting @@ -4306,11 +4336,14 @@ Utilities * `minetest.get_current_modname()`: returns the currently loading mod's name, when loading a mod. -* `minetest.get_modpath(modname)`: returns e.g. - `"/home/user/.minetest/usermods/modname"`. - * Useful for loading additional `.lua` modules or static data from mod -* `minetest.get_modnames()`: returns a list of installed mods - * Return a list of installed mods, sorted alphabetically +* `minetest.get_modpath(modname)`: returns the directory path for a mod, + e.g. `"/home/user/.minetest/usermods/modname"`. + * Returns nil if the mod is not enabled or does not exist (not installed). + * Works regardless of whether the mod has been loaded yet. + * Useful for loading additional `.lua` modules or static data from a mod, + or checking if a mod is enabled. +* `minetest.get_modnames()`: returns a list of enabled mods, sorted alphabetically. + * Does not include disabled mods, even if they are installed. * `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"` * Useful for storing custom data * `minetest.is_singleplayer()` @@ -4353,6 +4386,8 @@ Utilities object_step_has_moveresult = true, -- Whether get_velocity() and add_velocity() can be used on players (5.4.0) direct_velocity_on_players = true, + -- nodedef's use_texture_alpha accepts new string modes (5.4.0) + use_texture_alpha_string_modes = true, } * `minetest.has_feature(arg)`: returns `boolean, missing_features` @@ -4561,6 +4596,10 @@ Call these functions only at load time! the puncher to the punched. * `damage`: Number that represents the damage calculated by the engine * should return `true` to prevent the default damage mechanism +* `minetest.register_on_rightclickplayer(function(player, clicker))` + * Called when a player is right-clicked + * `player`: ObjectRef - Player that was right-clicked + * `clicker`: ObjectRef - Object that right-clicked, may or may not be a player * `minetest.register_on_player_hpchange(function(player, hp_change, reason), modifier)` * Called when the player gets damaged or healed * `player`: ObjectRef of the player @@ -4870,6 +4909,9 @@ Environment access * `minetest.get_objects_inside_radius(pos, radius)`: returns a list of ObjectRefs. * `radius`: using an euclidean metric +* `minetest.get_objects_in_area(pos1, pos2)`: returns a list of + ObjectRefs. + * `pos1` and `pos2` are the min and max positions of the area to search. * `minetest.set_timeofday(val)` * `val` is between `0` and `1`; `0` for midnight, `0.5` for midday * `minetest.get_timeofday()` @@ -6182,8 +6224,8 @@ object you are working with still exists. * `time_from_last_punch` = time since last punch action of the puncher * `direction`: can be `nil` * `right_click(clicker)`; `clicker` is another `ObjectRef` -* `get_hp()`: returns number of hitpoints (2 * number of hearts) -* `set_hp(hp, reason)`: set number of hitpoints (2 * number of hearts). +* `get_hp()`: returns number of health points +* `set_hp(hp, reason)`: set number of health points * See reason in register_on_player_hpchange * Is limited to the range of 0 ... 65535 (2^16 - 1) * For players: HP are also limited by `hp_max` specified in the player's @@ -6206,21 +6248,22 @@ object you are working with still exists. `frame_loop`. * `set_animation_frame_speed(frame_speed)` * `frame_speed`: number, default: `15.0` -* `set_attach(parent, bone, position, rotation, forced_visible)` - * `bone`: string - * `position`: `{x=num, y=num, z=num}` (relative) - * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees +* `set_attach(parent[, bone, position, rotation, forced_visible])` + * `bone`: string. Default is `""`, the root bone + * `position`: `{x=num, y=num, z=num}`, relative, default `{x=0, y=0, z=0}` + * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees. + Default `{x=0, y=0, z=0}` * `forced_visible`: Boolean to control whether the attached entity - should appear in first person. + should appear in first person. Default `false`. * `get_attach()`: returns parent, bone, position, rotation, forced_visible, or nil if it isn't attached. * `get_children()`: returns a list of ObjectRefs that are attached to the object. * `set_detach()` -* `set_bone_position(bone, position, rotation)` - * `bone`: string - * `position`: `{x=num, y=num, z=num}` (relative) - * `rotation`: `{x=num, y=num, z=num}` +* `set_bone_position([bone, position, rotation])` + * `bone`: string. Default is `""`, the root bone + * `position`: `{x=num, y=num, z=num}`, relative, `default {x=0, y=0, z=0}` + * `rotation`: `{x=num, y=num, z=num}`, default `{x=0, y=0, z=0}` * `get_bone_position(bone)`: returns position and rotation of the bone * `set_properties(object property table)` * `get_properties()`: returns object property table @@ -6548,8 +6591,8 @@ object you are working with still exists. * `frame_speed` sets the animations frame speed. Default is 30. * `get_local_animation()`: returns idle, walk, dig, walk_while_dig tables and `frame_speed`. -* `set_eye_offset(firstperson, thirdperson)`: defines offset vectors for camera - per player. +* `set_eye_offset([firstperson, thirdperson])`: defines offset vectors for + camera per player. An argument defaults to `{x=0, y=0, z=0}` if unspecified. * in first person view * in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`) * `get_eye_offset()`: returns first and third person offsets. @@ -6905,7 +6948,11 @@ Player properties need to be saved manually. -- in mods. nametag = "", - -- By default empty, for players their name is shown if empty + -- The name to display on the head of the object. By default empty. + -- If the object is a player, a nil or empty nametag is replaced by the player's name. + -- For all other objects, a nil or empty string removes the nametag. + -- To hide a nametag, set its color alpha to zero. That will disable it entirely. + nametag_color = , -- Sets color of nametag @@ -7295,10 +7342,18 @@ Used by `minetest.register_node`. -- 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 - -- If this is set to false, the node will be rendered fully opaque - -- regardless of any texture transparency. + use_texture_alpha = ..., + -- Specifies how the texture's alpha channel will be used for rendering. + -- possible values: + -- * "opaque": Node is rendered opaque regardless of alpha channel + -- * "clip": A given pixel is either fully see-through or opaque + -- depending on the alpha channel being below/above 50% in value + -- * "blend": The alpha channel specifies how transparent a given pixel + -- of the rendered node is + -- The default is "opaque" for drawtypes normal, liquid and flowingliquid; + -- "clip" otherwise. + -- If set to a boolean value (deprecated): true either sets it to blend + -- or clip, false sets it to clip or opaque mode depending on the drawtype. palette = "palette.png", -- The node's `param2` is used to select a pixel from the image. @@ -7612,12 +7667,12 @@ Used by `minetest.register_node`. -- intensity: 1.0 = mid range of regular TNT. -- If defined, called when an explosion touches the node, instead of -- removing the node. - + mod_origin = "modname", -- stores which mod actually registered a node -- if it can not find a source, returns "??" -- useful for getting what mod truly registered something - -- example: if a node is registered as ":othermodname:nodename", + -- example: if a node is registered as ":othermodname:nodename", -- nodename will show "othermodname", but mod_orgin will say "modname" }