Display Entities
Display entities are impermanent, non-physical, non-interactable objects that only exist to display something to players. These entities are never saved in the map, and are a mostly set-and-forget feature that requires very little (if any) thought to use.
Display entity creation functions do actually return a handle to the object, however it isn't recommended to use them as adding additional functionality to display entities is almost always worse than simply defining a new entity type, and it is ESPECIALLY NOT recommended to hold on to these handles anywhere as the entity can cease to exist without warning (e.g. if the mapblock is unloaded).
ITEM DISPLAY ENTITIES
Item display entities are for showing items and nodes in-world in the style of a wielditem (held item) without using an actual item entity. Common usecases include item frames, and showing the item(s) inside a functional node (such as the anvil or mortar and pestle).
The following functions can be used to create and manipulate item displays:
etc.add_item_display
Usage:etc.add_item_display(pos, item[, scale, rotation])
Creates a new item display at
pos
with the visual of item
(must be an ItemStack). scale
is a number, if nil it will be set to 0.2, else it will be multiplied by the default value. rotation
may either be a unit vector (sphere coordinates, standard for entity rotation) or the specific string 'random_flat'
which will cause the entity to lay flat as if on a surface, with a random rotation about the Y axis.
etc.update_item_display
Usage:etc.update_item_display(pos, item[, scale, rotation])
Updates any item display entities within 0.5 nodes of
pos
with a new item visual, and optionally a new scale and rotation. 'random_flat'
rotation is still supported; if used the Y rotation will be randomized again but the ZX rotations will be unchanged. Returns true if at least one entity was updated.
etc.remove_item_display
Usage:etc.remove_item_display(pos)
Deletes any item display entities within 0.5 nodes of
pos
.
NODE DISPLAY ENTITIES
Node display entities are cubic axis-aligned objects capable of imitating the appearance of a six-faced node. They can also have a 'level' specified, which allows them to imitate the appearance of a fluid or similar filling a container. Their textures will be sliced in attempt to preserve the aspect ratio of a pixel along each side.
The following functions can be used to create and manipulate node displays:
etc.add_node_display
Usage:etc.add_node_display(pos, tiles, scale[, level])
Creates a new node display at
pos
. tiles
can either be an array of six textures, or a single texture to apply to all sides. A scale
of 1 is equivalent to a full node. level
determines how much height to remove from the top of the node; a level of 0.5 yields a half-height node, and 0.1 a 1/10 height node. To absolutely preserve texture quality, limit your use of levels to increments of 1/texture size, for example 0.0625 when working with 16px tiles. A level of 1 will skip the somewhat expensive texture modification step.Notes: The entity will move down in absolute position when changing level from anything other than 1 in order to preserve the apparent height of the lower face. The entity will also never be truly 0 nodes tall, its' minimum height is 0.0001.
etc.update_node_display
Usage:etc.update_node_display(pos, level[, tiles])
Updates any node display entities within 0.5 nodes of
pos
with a new level and optionally new tiles. Returns true if at least one entity was updated.
etc.remove_node_display
Usage:etc.remove_node_display(pos)
Deletes any node display entities within 0.5 nodes of
pos
.
BEAM DISPLAY ENTITIES
Beam display entities are rectangular prisms that connect two points in space. They have six tiles just like node displays, but the side, bottom, and top textures of a beam display entity will be repeated along its' length, allowing for easy creation of linear 'beam', or 'pole' objects between points.
The following functions can be used to create and manipulate beam displays:
etc.add_beam_display
Usage:etc.add_beam_display(pos1, pos2, tiles, tile_size, width[, identifier])
Creates a new beam display at the halfway point between
pos1
and pos2
, with a length equal to the distance between them and a rotation such that one end of the entity sits at each point. tiles
is the same as with a node display: a list of six textures, or one string that will be applied to all faces. However, these tiles must be square; tile_size
must indicate the length of a side of a tile, e.g. 16
for 16px textures. If tile_size
is 0, the textures of the entity will not tile along its' length and will instead stretch. If using six textures, the first two textures are the top and bottom and will tile vertically, the middle two are the sides and will tile horizontally, and the last two are the textures of the ends of the beam. width
is the scale of the other two dimensions of the entity's visual, where 1 is equivalent to the size of a full node.identifier
is an optional arbitrary value that can be used to select particular beams in case they intersect unfavorably.
etc.update_beam_display
Usage:etc.update_beam_display(pos1, pos2[, pos1_new, pos2_new, width_new, identifier])
Locates any beam displays currently within 0.5 nodes of the halfway point between
pos1
and pos2
, and updates them accordingly. If identifier
is set, only beams with matching identifiers will be affected. Returns true if at least one entity was updated.
etc.remove_beam_display
Usage:etc.remove_beam_display(pos1, pos2[, identifier])
Locates any beam displays currently within 0.5 nodes of the halfway point between
pos1
and pos2
, and deletes them. If identifier
is set, only beams with matching identifiers will be affected.