summaryrefslogtreecommitdiff
path: root/doc/builtin_entities.txt
blob: be3f7335725d7528563c0fe55bcd91d3e3d96e39 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
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.