Document node definitions

doc/register.adoc

@@ -0,0 +1,35 @@
+= Registering Content
+include::../include/config.adoc[]
+include::../include/types.adoc[]
+:description: Adding Content to Minetest
+:keywords: node, register, definition
+
+Minetest's Lua API can be used to add new content to Minetest. This includes nodes (blocks), items, entities, ABMs and LBMs.
+
+IMPORTANT: You may only call registering functions at load time. Content cannot be registered dynamically while the world is running.
+
+== Functions
+
+=== `minetest.register_node(nodename, definition)
+
+Registers (adds) a new Node into the game. Each node has a unique identifier.
+
+NOTE: Minetest enforces IDs in the form of `modname:nodeid`. For example, if your mod is called "mymod", use an id of `mymod:myblock`. To circumvent this enforcement, use `:somemod:somenodename`
+
+==== Usage
+
+[source, lua]
+----
+-- this registers a simple node with a Description and a texture. There are a lot of possibilities to customize this node.
+minetest.register_node("mymod:mynode", {
+    description = "My Block",
+    tiles = {"mymod_mynode.png"}
+}
+----
+
+==== Params
+[%autowidth, frame=none]
+|===
+| `nodename` | `{type-string}` | The id that will be assigned to the node.
+| `definition` | `{type-nodedefinition}` | The properties and behaviour that will be applied to the node
+|===

doc/types/NodeDefinition.adoc

@@ -0,0 +1,208 @@
+= Node Definition
+include::../../include/config.adoc[]
+include::../../include/types.adoc[]
+:description: Definition for register_node
+:keywords: node, register, definition
+
+
+== Properties
+[%autowidth, frame=none]
+|===
+| Property | Type | Description | Default
+
+| `drawtype` | `{type-string}` | The way the node should be rendered. | `"normal"`
+
+| `visual_scale` | `{type-number}` | Affects the size at which the node will be rendered. Acts as a multiplier. This is supported for the following drawtypes: `"plantlike"`, `"signlike"`, `"torchlike"`, `"firelike"`, `"mesh"`, `"nodebox"`, `"allfaces"`. For `"plantlike"` and `"firelike"`, the `tiles` images will start at the bottom of the node. For `"torchlike"`, the image will start at the surface to which the node "attaches". For the other drawtypes, the `tiles` images will be centered on the node. | `1.0`
+
+| `tiles` | `{type-table}` | A table (list) of {type-string} (file names) or {type-tilespec} that will be assigned to the node. The tiles are assigned in the following order: +Y (up), -Y (down), +X (right), -X (left), +Z (front), -Z (back). The list can be shortened to the needed length. If the list is shortened, the last element of the table will be used for the remaining tiles. | `nil`
+
+| `overlay_tiles` | `{type-table}` | 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. | `nil`
+
+| `special_tiles` | `{type-table}` a| Special textures of node; used rarely. The list can be shortened in the same way as `tiles`. 
+
+NOTE: Depending on `paramtype2`, `special_tiles` fulfill specific purposes. See link:../paramtype.adoc[paramtypes] | `nil`
+
+| `color` | `{type-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. | `"#ffffff"`
+
+| `use_texture_alpha` | `{type-string}` a| 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.
+
+NOTE: 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. | `"opaque"`\|`"clip"`
+
+| `palette` | `{type-string}` a| Assign a palette by a filename to the node. A palette is a texture which can contain up to 256 pixels. Each pixel is one possible color for the node/item. The nodes `param2` is used to select a pixel from the image. Pixels are arranged from left to right and from top to bottom. The nodes color will be multiplied with the selected pixels color. Tiles can override this behavior. For nodes and items which can have many colors, a palette is more suitable.
+
+WARNING: 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.
+
+NOTE: Only when `paramtype2` supports palettes. | `""`
+
+| `post_effect_color` | `{type-colorspec}` | Tint the screen if the player is inside the node. | `"#00000000"`
+
+| `paramtype` | `{type-string}` | See link:../nodes.adoc[Nodes] | `"none"`
+| `paramtype2` | `{type-string}` | See link:../nodes.adoc[Nodes] | `"none"`
+| `place_param2` | `{type-number}` | Value for param2 that is set when player places the node. | `0`
+
+| `is_ground_content` | `{type-bool}` | If `false`, the cave generator and dungeon generator will not carve through this node. Specifically, this stops mod-added nodes being removed by caves and dungeons when those generate in a neighbor mapchunk and extend out beyond the edge of that mapchunk. | `true`
+
+| `sunlight_propagates` | `{type-bool}` | If `true`, sunlight will go infinitely through this node. | `false`
+
+| `walkable` | `{type-bool}` | If `true`, objects collide with the node. | `true`
+| `pointable` | `{type-bool}`| If `true`, the node can be pointed at. | `true`
+| `diggable` | `{type-bool}` | If `false`, the node can never be dug. | `true`
+| `climbable` | `{type-bool}` | If `true`, the node can be climbed on like a ladder. | `false`
+| `buildable_to` | `{type-bool}` | If `true`, placed nodes can replace this node. | `false`
+| `floodable` | `{type-bool}` a| If `true`, liquids flow into and replace this node.
+
+WARNING: making a liquid node 'floodable' will cause problems. | `false`
+
+| `move_resistance` | `{type-number}` | Slows down movement of players through this node (max. 7). If this is `nil`, it will be equal to `liquid_viscosity`.
+
+NOTE: If liquid movement physics apply to the node (see `liquid_move_physics`), the movement speed will also be affected by the `movement_liquid_*` settings. | `0`
+
+
+| `liquidtype` | `{type-string}` a| Specifies liquid flowing physics
+
+* `"none"`:    no liquid flowing physics
+* `"source"`:  spawns flowing liquid nodes at all 4 sides and below; recommended drawtype: `"liquid"`.
+* `"flowing"`: spawned from source, spawns more flowing liquid nodes around it until `liquid_range` is reached; will drain out without a source; recommended drawtype: `"flowingliquid"`.
+
+NOTE: If it's "source" or "flowing", then the `liquid_alternative_*` fields *must* be specified | `"none"`
+
+| `liquid_alternative_flowing` | `{type-string}` a| This field and `liquid_alternative_source` may contain node names that represent the flowing version (`liquid_alternative_flowing`) and source version (`liquid_alternative_source`) of a liquid.
+
+Specifically, this field and `liquid_alternative_source` are required if any of these is true:
+
+* `liquidtype ~= "none"`
+* `drawtype == "liquid"`
+* `drawtype == "flowingliquid"`
+
+Liquids consist of up to two nodes: Source and flowing. There are two ways to define a liquid:
+1. Source node and flowing node. This requires both fields to be specified for both nodes.
+2. Standalone source node (cannot flow). `liquid_alternative_source` must be specified and `liquid_range` must be set to 0.
+
+Example:
+[source,lua]
+----
+-- ... other properties ...
+liquid_alternative_flowing = "example:water_flowing",
+liquid_alternative_source = "example:water_source",
+-- ... other properties ...
+---- | `""`
+
+| `liquid_alternative_source` | `{type-string}` | See `liquid_alternative_flowing` | `""`
+
+| `liquid_viscosity` | `{type-number}` | Liquid viscosity controls the speed at which the liquid spreads/flows (max. 7). 0 is the fastest, 7 the slowest. By default, this also slows down movement of players inside the node (can be overridden using `move_resistance`). | `0`
+
+| `liquid_renewable` | `{type-bool}` | If `true`, a new liquid source can be created by placing two or more sources nearby. | `true`
+| `liquid_move_physics` | `{type-bool} or {type-nil}` a| Specifies movement physics if the player is inside the node.
+
+* `false`: No liquid movement physics apply.
+* `true`: Enables liquid movement physics. Enables things like ability to "swim" up/down, sinking slowly if not moving, smoother speed change when falling into, etc. The `movement_liquid_*` settings apply.
+* `nil`: Will be treated as true if `liquidtype ~= "none"` and as false otherwise. | `nil`
+
+| `liquid_range` | `{type-number}` | Maximum distance that flowing liquid nodes can spread around source on flat land (max. 8). If this is set to 0, liquid flow will be disabled. | `8`
+
+| `leveled` | `{type-number}` | This only applies to nodes that have the "nodebox" drawtype set to `"leveled"`. This allows defining the nodebox height without using `param2`. The nodebox height is `leveled` / 64 nodes. The maximum value of `leveled` is `leveled_max`. | `0`
+| `leveled_max` | `{type-number}` | Maximum value for `leveled` (0-127), enforced in `minetest.set_node_level` and `minetest.add_node_level`. Values above 124 might causes collision detection issues. | `127`
+
+| `drowning` | `{type-number}` a| Player will take this amount of damage per second if no bubbles are left.
+
+NOTE: If `drowning` is set to 0, the player will not lose air bubbles while inside the node. | `0`
+| `damage_per_second` | `{type-number}` | If player is inside this node, this damage is caused each second. | `0`
+
+| `node_box` | `{type-table}` | See link:../nodeboxes.adoc[Node Boxes] | `{type = "regular"}`
+| `connects_to` | `{type-table}` | Used for nodebox nodes with the `type == "connected"`. This specifies to what neighboring nodes connections will be drawn.
+Example: `{"group:fence", "default:wood"}` or `"default:stone"` | `{}`
+| `connect_sides` | `{type-table}` | Tells connected nodebox nodes to connect only to these sides of this node. Possible: `"top"`, `"bottom"`, `"front"`, `"left"`, `"back"`, `"right"`. | `{}`
+
+| `mesh` | `{type-string}` | File name of mesh when using the `"mesh"` drawtype. | `""`
+
+| `selection_box` | `{type-table}` | Custom selection box definition. Multiple boxes can be defined. If `"nodebox"` drawtype is used and `selection_box` is `nil`, then `node_box` definition is used for the selection box. See link:../nodeboxes.adoc[Node Boxes] for possibilities. | `nil`
+
+| `collision_box` | `{type-table}` | Custom collision box definition. Multiple boxes can be defined. If `"nodebox"` drawtype is used and `collision_box` is `nil`, then `node_box definition` is used for the collision box. See link:../nodeboxes.adoc[Node Boxes] for possibilities. | `nil`
+
+| `waving` | `{type-number}` a| This is valid for drawtypes: `"mesh"`, `"nodebox"`, `"plantlike"`, `"allfaces_optional"`, `"liquid"` and `"flowingliquid"`. The following values can be set:
+* 0 - don't wave
+* 1 - wave node like plants (node top moves side-to-side, bottom is fixed)
+* 2 - wave node like leaves (whole node moves side-to-side)
+* 3 - wave node like liquids (whole node moves up and down)
+
+Not all models will properly wave.
+
+* `"plantlike"` drawtype can only wave like plants.
+* `"allfaces_optional"` drawtype can only wave like leaves.
+* `"liquid"`, `"flowingliquid"` drawtypes can only wave like liquids. | `0`
+
+| `sounds` | `{type-nodesoundspec}` | Definition of node sounds to be played at various events. See {type-nodesoundspec}. | `nil`
+
+| `drop` | `{type-string} or {type-nodedropspec}` | By default, the dropped item is the node itself. If a {type-string} is given, `drop` will be dropped (for example: `"default:stone"`). Using a table allows multiple items, drop chances and item filtering, see {type-nodedropspec}. | `""`
+
+| `mod_origin` | `{type-string}` | stores which mod actually registered a node. If the source could not be determined, it contains `"??"`. This is useful for getting which mod truly registered something.
+
+Example: If a node is registered as `":othermodname:nodename"`, nodename will show `"othermodname"`, but `mod_origin` will say `"modname"`. | `minetest.get_current_modname()`
+
+| `on_construct` | `{type-function}(pos:{class-vector})` a| The node constructor function called after adding the node to the world. This can, for example, be used to add metadata to the node.
+
+NOTE: This function is not called for bulk node placement (i.e. schematics and VoxelManip).
+
+WARNING: Within an `on_construct` callback, `minetest.set_node` can cause an infinite loop if it invokes the same callback. Consider using `minetest.swap_node` instead. | `nil`
+
+| `on_destruct` | `{type-function}(pos:{class-vector})` a| The node destructor function called before removing the node from the world.
+
+NOTE: Like in `on_construct`, this function is not called for bulk node placement. | `nil`
+
+| `after_destruct` | `{type-function}(pos:{class-vector}, oldnode:{class-noderef})` a| The node destructor function called after removing the node from the world.
+
+NOTE: Like in `on_construct`, this function is not called for bulk node placement. | `nil`
+
+| `after_place_node` | `{type-function}(pos:{class-vector}, placer:{class-playerref}, itemstack:{class-itemstack}, pointed_thing:{type-pointedthing})` | Called after constructing the node when the node was placed using `minetest.item_place_node` or `minetest.place_node`. If the function returns `true`, no item is taken from the {class-itemstack}. `placer` may be any valid {class-objectref} or {type-nil}. | `nil`
+
+| `on_dig` | `{type-function}(pos:{class-vector}, node:{class-noderef}, pointed_thing:{type-pointedthing})` | Called when the node was dug. By default, this checks privileges (if the node can be dug). If the item used to dig this node is a tool, the tools durability will be deducted. Return `true` if the node was dug successfully, `false` otherwise. | `minetest.node_dig`
+
+| `after_dig_node` | `{type-function}(pos:{class-vector}, oldnode:{class-noderef}, oldmetadata:{type-table}, digger:{class-playerref})` | Called after destructing the node when the node was dug using `minetest.node_dig` or `minetest.dig_node`. | `nil`
+
+| `can_dig` | `{type-function}(pos:{class-vector}, player:{class-playerref}\|{type-nil})` | If the node shall be diggable, this function should return `true`, `false` otherwise. | `nil`
+
+| `on_flood` | `{type-function}(pos:{class-vector}, oldnode:{class-noderef}, newnode:{class-noderef})` | Called when a liquid (`newnode`) is about to flood `oldnode`, if it has `floodable = true` in the `{type-nodedefinition}`. This function is not called for bulk node placement (i.e. schematics and VoxelManip) or air nodes. If this function returns `true`, the node is not flooded, but `on_flood` will most likely be called over and over again every liquid update interval.
+
+WARNING: Making a liquid node `floodable` will cause problems. | `nil`
+
+| `on_punch` | `{type-function}(pos:{class-vector}, node:{class-noderef}, puncher:{class-objectref}, pointed_thing:{type-pointedthing})` | Called when `puncher` punches the `node` at `pos`. By default, `minetest.register_on_punchnode` callbacks are called. | `minetest.node_punch`
+
+| `on_receive_fields` | `{type-function}(pos:{type-vector}, formname:{type-string}, fields:{type-table}, sender:{class-playerref})` a| Called when the link:../formspec.adoc[formspec] associated with the node (e.g. a sign text input) through the `formspec` field in the nodes {type-nodemetadata} returns data. See `minetest.register_on_player_receive_fields` for more info.
+NOTE: The `fields` are supplied in a key-value format: `fields = {name1 = value1, name2 = value2, ...}` | `nil`
+
+| `on_rightclick` | `{type-function}(pos:{class-vector}, node:{class-noderef}, clicker:{class-objectref}, itemstack:{class-itemstack}, pointed_thing:{type-pointedthing})` a| Called when `clicker` used the 'place/build' key (not necessarily an actual rightclick) while pointing at the `node` at `pos`. `itemstack` will hold the wielded item of the `clicker`. This function shall return the leftover itemstack.
+
+NOTE: `pointed_thing` can be `nil`, if a mod calls this function. | `nil`
+
+| `on_timer` | `{type-function}(pos:{class-vector}, elapsed:{type-number})` | Called by NodeTimers, `get_node_timer` and {class-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. | `nil`
+
+| `preserve_metadata` | `{type-function}(pos:{class-vector}, oldnode:{class-noderef}, oldmeta:{type-table}, drops:{type-table})` | 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.
+`oldmeta` contains the metadata fields (table) of the node before deletion. `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 `{class-nodemetadata}`. | `nil`
+
+| `allow_metadata_inventory_move` | `{type-function}(pos:{class-vector}, from_list:{type-string}, from_index:{type-number}, to_list:{type-string}, to_index:{type-number}, count:{type-number}, player:{class-playerref})` | Called when a player wants to move items inside the inventory. This function should return the number of items allowed to move. | `nil`
+
+| `allow_metadata_inventory_put` | `{type-function}(pos:{class-vector}, listname:{type-string}, index:{type-number}, stack:{class-itemstack}, player:{class-playerref})` a| Called when a player wants to put something into the inventory. This function should return the number of items allowed to put.
+
+NOTE: If `-1` is returned, the item count in `player`s inventory won't be modified and the put will be allowed. | `nil`
+
+| `allow_metadata_inventory_take` | `{type-function}(pos:{class-vector}, listname:{type-string}, index:{type-number}, stack:{class-itemstack}, player:{class-playerref})` a| Called when a player wants to take something out of the inventory. This function should return the number of items `player` is allowed to take.
+
+NOTE: If `-1` is returned, the item count in `player`s inventory won't be modified and the put will be allowed. Use this for creative inventories. | `nil`
+
+| `on_metadata_inventory_move` | `{type-function}(pos:{class-vector}, from_list:{type-string}, from_index:{type-number}, to_list:{type-string}, to_index:{type-number}, count:{type-number}, player:{class-playerref})` | Called after the actual action has happened, according to what was allowed. This function should return nothing. | `nil`
+
+| `on_metadata_inventory_put` | `{type-function}(pos:{class-vector}, listname:{type-string}, index:{type-number}, stack:{class-itemstack}, player:{class-playerref})` | Called after the actual action has happened, according to what was allowed. This function should return nothing. | `nil`
+
+| `on_metadata_inventory_take` | `{type-function}(pos:{class-vector}, listname:{type-string}, index:{type-number}, stack:{class-itemstack}, player:{class-playerref})` | Called after the actual action has happened, according to what was allowed. This function should return nothing. | `nil`
+
+| `on_blast` | `{type-function}(pos:{class-vector}, intensity:{type-number})` a| If this function is defined, it is called when an explosion touches the node. If this function is called, the node won't be removed.
+
+NOTE: an `intensity` of 1.0 is equivalent to the mid range of a regular TNT explosion.  | `nil`
+|===

include/types.adoc

@@ -8,5 +8,19 @@
 :type-function: {url-pil}/2.6.html[function]
 :type-userdata: {url-pil}/2.7.html[userdata]
 
+// minetest-specific types
+:type-nodedefinition: link:../doc/types/NodeDefinition.adoc[NodeDefinition]
+:type-nodesoundspec: link:../doc/types/NodeSoundSpec.adoc[NodeSoundSpec]
+:type-nodedropspec: link:../doc/types/NodeDropSpec.adoc[NodeDropSpec]
+:type-colorspec: link:../doc/types/ColorSpec.adoc[ColorSpec]
+:type-tilespec: link:../doc/types/TileSpec.adoc[TileSpec]
+:type-pointedthing: link:../doc/classes/Raycast.adoc#pointed-thingdoc/classes/Raycast.adoc#pointed-thing[PointedThing]
+
 // This should probably be macro'd or something
 :class-vector: link:../doc/classes/vector.adoc[vector]
+:class-itemstack: link:../doc/classes/ItemStack.adoc[ItemStack]
+:class-nodemetadata: link:../doc/classes/NodeMetaData.adoc[NodeMetaData]
+:class-playerref: link:../doc/classes/PlayerRef.adoc[PlayerRef]
+:class-objectref: link:../doc/classes/ObjectRef.adoc[ObjectRef]
+:class-noderef: link:../doc/classes/NodeRef.adoc[NodeRef]
+:class-nodetimerref: link:../doc/classes/NodeTimerRef.adoc[NodeTimerRef]