Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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.
- Loading branch information
Showing
1 changed file
with
101 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |