Document builtin entities (#9453)

This PR adds a new text file doc/builtin_entities.txt which explains how the two builtin entities __builtin:item and __builtin:falling_node work.

1 files changed, 101 insertions, 0 deletions

diff --git a/doc/builtin_entities.txt b/doc/builtin_entities.txt
new file mode 100644
index 000000000..be3f73357
--- /dev/null
+++ b/doc/builtin_entities.txt
@@ -0,0 +1,101 @@
+# Builtin Entities
+Minetest registers two entities by default: Falling nodes and dropped items.
+This document describes how they behave and what you can do with them.
+
+## Falling node (`__builtin:falling_node`)
+
+This entity is created by `minetest.check_for_falling` in place of a node
+with the special group `falling_node=1`. Falling nodes can also be created
+artificially with `minetest.spawn_falling_node`.
+
+Needs manual initialization when spawned using `/spawnentity`.
+
+Default behaviour:
+
+* Falls down in a straight line (gravity = `movement_gravity` setting)
+* Collides with `walkable` node
+* Collides with all physical objects except players
+* If the node group `float=1` is set, it also collides with liquid nodes
+* When it hits a solid (=`walkable`) node, it will try to place itself as a
+  node, replacing the node above.
+    * If the falling node cannot replace the destination node, it is dropped.
+    * If the destination node is a leveled node (`paramtype2="leveled"`) of the
+      same node name, the levels of both are summed.
+
+### Entity fields
+
+* `set_node(self, node[, meta])`
+    * Function to initialize the falling node
+    * `node` and `meta` are explained below.
+    * The `meta` argument is optional.
+* `node`: Node table of the node (`name`, `param1`, `param2`) that this
+  entity represents. Read-only.
+* `meta`: Node metadata of the falling node. Will be used when the falling
+  nodes tries to place itself as a node. Read-only.
+
+### Rendering / supported nodes
+
+Falling nodes have visuals to look as close as possible to the original node.
+This works for most drawtypes, but there are limitations.
+
+Supported drawtypes:
+
+* `normal`
+* `signlike`
+* `torchlike`
+* `nodebox`
+* `raillike`
+* `glasslike`
+* `glasslike_framed`
+* `glasslike_framed_optional`
+* `allfaces`
+* `allfaces_optional`
+* `firelike`
+* `mesh`
+* `fencelike`
+* `liquid`
+* `airlike` (not pointable)
+
+Other drawtypes still kinda work, but they might look weird.
+
+Supported `paramtype2` values:
+
+* `wallmounted`
+* `facedir`
+* `colorwallmounted`
+* `colorfacedir`
+* `color`
+
+## Dropped item stack (`__builtin:item`)
+
+This is an item stack in a collectable form.
+
+Common cases that spawn a dropped item:
+
+* Item dropped by player
+* The root node of a node with the group `attached_node=1` is removed
+* `minetest.add_item` is called
+
+Needs manual initialization when spawned using `/spawnentity`.
+
+### Behavior
+
+* Players can collect it by punching
+* Lifespan is defined by the setting `item_entity_ttl`
+* Slides on `slippery` nodes
+* Subject to gravity (uses `movement_gravity` setting)
+* Collides with `walkable` nodes
+* Does not collide physical objects
+* When it's inside a solid (`walkable=true`) node, it tries to escape to a
+  neighboring non-solid (`walkable=false`) node
+
+### Entity fields
+
+* `set_item(self, item)`:
+    * Function to initialize the dropped item
+    * `item` (type `ItemStack`) specifies the item to represent
+* `age`: Age in seconds. Behaviour according to the setting `item_entity_ttl`
+* `itemstring`: Itemstring of the item that this item entity represents.
+  Read-only.
+
+Other fields are for internal use only.