Lua_api.txt: Improve and complete drawtype documentation

Move documentation of mesh and plantlike_rooted drawtypes into main section.

1 files changed, 67 insertions, 27 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 1c8766de8..fe23fbe64 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -971,33 +971,92 @@ There are a bunch of different looking node types.
 Look for examples in `games/minimal` or `games/minetest_game`.
 
 * `normal`
+    * A node-sized cube.
 * `airlike`
+    * Invisible, uses no texture.
 * `liquid`
+    * The cubic source node for a liquid.
 * `flowingliquid`
+    * The flowing version of a liquid, appears with various heights and slopes.
 * `glasslike`
+    * Often used for partially-transparent nodes.
+    * Only external sides of textures are visible.
 * `glasslike_framed`
+    * All face-connected nodes are drawn as one volume within a surrounding
+      frame.
+    * The frame appearence is generated from the edges of the first texture
+      specified in `tiles`. The width of the edges used are 1/16th of texture
+      size: 1 pixel for 16x16, 2 pixels for 32x32 etc.
+    * The glass 'shine' (or other desired detail) on each node face is supplied
+      by the second texture specified in `tiles`.
 * `glasslike_framed_optional`
+    * This switches between the above 2 drawtypes according to the menu setting
+      'Connected Glass'.
 * `allfaces`
+    * Often used for partially-transparent nodes.
+    * External and internal sides of textures are visible.
 * `allfaces_optional`
+    * Often used for leaves nodes.
+    * This switches between `normal`, `glasslike` and `allfaces` according to
+      the menu setting: Opaque Leaves / Simple Leaves / Fancy Leaves.
+    * With 'Simple Leaves' selected, the texture specified in `special_tiles`
+      is used instead, if present. This allows a visually thicker texture to be
+      used to compensate for how `glasslike` reduces visual thickness.
 * `torchlike`
+    * A single vertical texture.
+    * If placed on top of a node, uses the first texture specified in `tiles`.
+    * If placed against the underside of a node, uses the second texture
+      specified in `tiles`.
+    * If placed on the side of a node, uses the third texture specified in
+      `tiles` and is perpendicular to that node.
 * `signlike`
+    * A single texture parallel to, and mounted against, the top, underside or
+      side of a node.
 * `plantlike`
+    * Two vertical and diagonal textures at right-angles to each other.
+    * See `paramtype2 == "meshoptions"` above for other options.
 * `firelike`
+    * When above a flat surface, appears as 6 textures, the central 2 as
+      `plantlike` plus 4 more surrounding those.
+    * If not above a surface the central 2 do not appear, but the texture
+      appears against the faces of surrounding nodes if they are present.
 * `fencelike`
+    * A 3D model suitable for a wooden fence.
+    * One placed node appears as a single vertical post.
+    * Adjacently-placed nodes cause horizontal bars to appear between them.
 * `raillike`
-* `nodebox` -- See below
-* `mesh` -- Use models for nodes, see below
-* `plantlike_rooted` -- See below
+    * Often used for tracks for mining carts.
+    * Requires 4 textures to be specified in `tiles`, in order: Straight,
+      curved, t-junction, crossing.
+    * Each placed node automatically switches to a suitable rotated texture
+      determined by the adjacent `raillike` nodes, in order to create a
+      continuous track network.
+    * Becomes a sloping node if placed against stepped nodes.
+* `nodebox`
+    * Often used for stairs and slabs.
+    * Allows defining nodes consisting of an arbitrary number of boxes.
+    * See 'Node boxes' below for more information.
+* `mesh`
+    * Uses models for nodes.
+    * Tiles should hold model materials textures.
+    * Only static meshes are implemented.
+    * For supported model formats see Irrlicht engine documentation.
+* `plantlike_rooted`
+    * Enables underwater `plantlike` without air bubbles around the nodes.
+    * Consists of a base cube at the co-ordinates of the node plus a
+      `plantlike` extension above with a height of `param2 / 16` nodes.
+    * The `plantlike` extension visually passes through any nodes above the
+      base cube without affecting them.
+    * The base cube texture tiles are defined as normal, the `plantlike`
+      extension uses the defined special tile, for example:
+      `special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},`
 
 `*_optional` drawtypes need less rendering time if deactivated
-(always client side).
+(always client-side).
 
 Node boxes
 ----------
-Node selection boxes are defined using "node boxes"
-
-The `nodebox` node drawtype allows defining nodes consisting of an arbitrary
-number of boxes. It allows defining stuff like stairs and slabs.
+Node selection boxes are defined using "node boxes".
 
 A nodebox is defined as any of:
 
@@ -1059,25 +1118,6 @@ A box of a regular node would look like:
 
     {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
 
-Meshes
-------
-If drawtype `mesh` is used, tiles should hold model materials textures.
-Only static meshes are implemented.
-For supported model formats see Irrlicht engine documentation.
-
-Rooted plantlike drawtype
--------------------------
-The `plantlike_rooted` drawtype was developed to enable underwater plants
-without air bubbles around the plants.
-It consists of a base cube at the co-ordinates of the node (the seabed /
-lakebed / riverbed node) plus a 'plantlike' extension above with a height
-defined by param2 (maximum height 16 nodes). This extension visually passes
-through any nodes above the base cube without affecting them.
-The node is dug by digging the base cube.
-The base cube texture tiles are defined as normal, the plantlike extension
-uses the defined 'special tile', for example:
-`special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},`
-
 Noise Parameters
 ----------------
 Noise Parameters, or commonly called "`NoiseParams`", define the properties of