X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=6ff7f802a2f3265c327f226c9683c9e6e0df50c5;hb=8ddb6718e3e0b4713fce13a7d7324327b2e56d20;hp=96554cf518bc323e5ad8b763b255d68398460a63;hpb=b14aa1c84714a4800d214768ff7868a7bb76f7ae;p=minetest.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 96554cf51..6ff7f802a 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -948,7 +948,8 @@ Node paramtypes The functions of `param1` and `param2` are determined by certain fields in the node definition. -`param1` is reserved for the engine when `paramtype != "none"`: +The function of `param1` is determined by `paramtype` in 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 @@ -965,19 +966,27 @@ node definition. * mesh * plantlike * plantlike_rooted - -`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"` +* `paramtype = "none"` + * `param1` will not be used by the engine and can be used to store + an arbitrary value + +The function of `param2` is determined by `paramtype2` in node definition. +`param2` is reserved for the engine when `paramtype2 != "none"`. + +* `paramtype2 = "flowingliquid"` + * Used by `drawtype = "flowingliquid"` and `liquidtype = "flowing"` + * The liquid level and a flag of the liquid are stored in `param2` + * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node + * Bit 3: If set, liquid is flowing downwards (no graphical effect) * `paramtype2 = "wallmounted"` - * The rotation of the node is stored in `param2`. You can make this value - by using `minetest.dir_to_wallmounted()`. + * Supported drawtypes: "torchlike", "signlike", "normal", "nodebox", "mesh" + * The rotation of the node is stored in `param2` + * You can make this value by using `minetest.dir_to_wallmounted()` + * Values range 0 - 5 + * The value denotes at which direction the node is "mounted": + 0 = y+, 1 = y-, 2 = x+, 3 = x-, 4 = z+, 5 = z- * `paramtype2 = "facedir"` + * Supported drawtypes: "normal", "nodebox", "mesh" * 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 @@ -996,13 +1005,13 @@ node definition. * 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 + * Only valid for "plantlike" drawtype. 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. + * Only valid for "plantlike" drawtype. 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) @@ -1034,6 +1043,9 @@ node definition. * `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"}` +* `paramtype2 = "none"` + * `param2` will not be used by the engine and can be used to store + an arbitrary value Nodes can also contain extra data. See [Node Metadata]. @@ -2121,6 +2133,15 @@ Elements * Show an image +### `animated_image[,;,;:,]` + +* Show an animated image. The image is drawn like a "vertical_frames" tile + animation (See Tile animation definition), but uses a frame count/duration + for simplicity +* `` is the image to use +* `` is the number of frames animating the image +* `` is in milliseconds + ### `item_image[,;,;]` * Show an inventory image of registered item/node @@ -2231,7 +2252,7 @@ Elements an inventory slot. ### `hypertext[,;,;;]` -* Displays a static formated text with hyperlinks. +* Displays a static formatted text with hyperlinks. * `x`, `y`, `w` and `h` work as per field * `name` is the name of the field as returned in fields to `on_receive_fields` in case of action in text. * `text` is the formatted text using `markup language` described below. @@ -2568,6 +2589,8 @@ Some types may inherit styles from parent types. ### Valid Properties +* animated_image + * noclip - boolean, set to true to allow the element to exceed formspec bounds. * box * noclip - boolean, set to true to allow the element to exceed formspec bounds. * Default to false in formspec_version version 3 or higher @@ -3723,7 +3746,7 @@ Methods ----------- A helper class for voxel areas. -It can be created via `VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}`. +It can be created via `VoxelArea:new{MinEdge = pmin, MaxEdge = pmax}`. The coordinates are *inclusive*, like most other things in Minetest. ### Methods @@ -3754,6 +3777,28 @@ The coordinates are *inclusive*, like most other things in Minetest. `[z [y [x]]]`. * `iterp(minp, maxp)`: same as above, except takes a vector +### Y stride and z stride of a flat array + +For a particular position in a voxel area, whose flat array index is known, +it is often useful to know the index of a neighboring or nearby position. +The table below shows the changes of index required for 1 node movements along +the axes in a voxel area: + + Movement Change of index + +x +1 + -x -1 + +y +ystride + -y -ystride + +z +zstride + -z -zstride + +If, for example: + + local area = VoxelArea:new{MinEdge = emin, MaxEdge = emax} + +The values of `ystride` and `zstride` can be obtained using `area.ystride` and +`area.zstride`. + @@ -5661,8 +5706,21 @@ Can be gotten via `minetest.get_node_timer(pos)`. ----------- Moving things in the game are generally these. +This is basically a reference to a C++ `ServerActiveObject`. + +### Advice on handling `ObjectRefs` + +When you receive an `ObjectRef` as a callback argument or from another API +function, it is possible to store the reference somewhere and keep it around. +It will keep functioning until the object is unloaded or removed. + +However, doing this is **NOT** recommended as there is (intentionally) no method +to test if a previously acquired `ObjectRef` is still valid. +Instead, `ObjectRefs` should be "let go" of as soon as control is returned from +Lua back to the engine. +Doing so is much less error-prone and you will never need to wonder if the +object you are working with still exists. -This is basically a reference to a C++ `ServerActiveObject` ### Methods @@ -5733,7 +5791,10 @@ This is basically a reference to a C++ `ServerActiveObject` #### Lua entity only (no-op for other objects) -* `remove()`: remove object (after returning from Lua) +* `remove()`: remove object + * The object is removed after returning from Lua. However the `ObjectRef` + itself instantly becomes unusable with all further method calls having + no effect and returning `nil`. * `set_velocity(vel)` * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}` * `add_velocity(vel)`