doc/builtin_entities.txt

   1 # Builtin Entities
   2 Minetest registers two entities by default: Falling nodes and dropped items.
   3 This document describes how they behave and what you can do with them.
   4
   5 ## Falling node (`__builtin:falling_node`)
   6
   7 This entity is created by `minetest.check_for_falling` in place of a node
   8 with the special group `falling_node=1`. Falling nodes can also be created
   9 artificially with `minetest.spawn_falling_node`.
  10
  11 Needs manual initialization when spawned using `/spawnentity`.
  12
  13 Default behaviour:
  14
  15 * Falls down in a straight line (gravity = `movement_gravity` setting)
  16 * Collides with `walkable` node
  17 * Collides with all physical objects except players
  18 * If the node group `float=1` is set, it also collides with liquid nodes
  19 * When it hits a solid (=`walkable`) node, it will try to place itself as a
  20   node, replacing the node above.
  21     * If the falling node cannot replace the destination node, it is dropped.
  22     * If the destination node is a leveled node (`paramtype2="leveled"`) of the
  23       same node name, the levels of both are summed.
  24
  25 ### Entity fields
  26
  27 * `set_node(self, node[, meta])`
  28     * Function to initialize the falling node
  29     * `node` and `meta` are explained below.
  30     * The `meta` argument is optional.
  31 * `node`: Node table of the node (`name`, `param1`, `param2`) that this
  32   entity represents. Read-only.
  33 * `meta`: Node metadata of the falling node. Will be used when the falling
  34   nodes tries to place itself as a node. Read-only.
  35
  36 ### Rendering / supported nodes
  37
  38 Falling nodes have visuals to look as close as possible to the original node.
  39 This works for most drawtypes, but there are limitations.
  40
  41 Supported drawtypes:
  42
  43 * `normal`
  44 * `signlike`
  45 * `torchlike`
  46 * `nodebox`
  47 * `raillike`
  48 * `glasslike`
  49 * `glasslike_framed`
  50 * `glasslike_framed_optional`
  51 * `allfaces`
  52 * `allfaces_optional`
  53 * `firelike`
  54 * `mesh`
  55 * `fencelike`
  56 * `liquid`
  57 * `airlike` (not pointable)
  58
  59 Other drawtypes still kinda work, but they might look weird.
  60
  61 Supported `paramtype2` values:
  62
  63 * `wallmounted`
  64 * `facedir`
  65 * `colorwallmounted`
  66 * `colorfacedir`
  67 * `color`
  68
  69 ## Dropped item stack (`__builtin:item`)
  70
  71 This is an item stack in a collectable form.
  72
  73 Common cases that spawn a dropped item:
  74
  75 * Item dropped by player
  76 * The root node of a node with the group `attached_node=1` is removed
  77 * `minetest.add_item` is called
  78
  79 Needs manual initialization when spawned using `/spawnentity`.
  80
  81 ### Behavior
  82
  83 * Players can collect it by punching
  84 * Lifespan is defined by the setting `item_entity_ttl`
  85 * Slides on `slippery` nodes
  86 * Subject to gravity (uses `movement_gravity` setting)
  87 * Collides with `walkable` nodes
  88 * Does not collide physical objects
  89 * When it's inside a solid (`walkable=true`) node, it tries to escape to a
  90   neighboring non-solid (`walkable=false`) node
  91
  92 ### Entity fields
  93
  94 * `set_item(self, item)`:
  95     * Function to initialize the dropped item
  96     * `item` (type `ItemStack`) specifies the item to represent
  97 * `age`: Age in seconds. Behaviour according to the setting `item_entity_ttl`
  98 * `itemstring`: Itemstring of the item that this item entity represents.
  99   Read-only.
 100
 101 Other fields are for internal use only.