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
* 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
* 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)
* `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].
* Show an image
+### `animated_image[<X>,<Y>;<W>,<H>;<texture name>:<frame count>,<frame duration>]`
+
+* 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
+* `<texture name>` is the image to use
+* `<frame count>` is the number of frames animating the image
+* `<frame duration>` is in milliseconds
+
### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
* Show an inventory image of registered item/node
an inventory slot.
### `hypertext[<X>,<Y>;<W>,<H>;<name>;<text>]`
-* 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.
### 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
-----------
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
`[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`.
+
-----------
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
#### 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)`
projects / minetest.git / blobdiff