entities Module

The entities module provides functions for creating and removing entities.

Entity Management Functions

Create(spec)

Definition

entities.Create(spec)

Creates a new entity according to the provided specification.

Parameters:

spec (table (see below for allowed entries)) – Entity specification describing the entity to create.

Returns:

Entity ID of the newly created entity, or nil on error.

Return type:

integer

The entity specification accepted by Create(spec) is a table containing zero or more of the following entries describing the initial state of the entity. The absence of any entry indicates that no value will be initially set, with the exception of the EntityId entry for which a value will be automatically selected if one is not provided.

Key	Value Type	Meaning
EntityId	integer	Entity ID
Template	integer	Template entity ID
Kinematics	Kinematics	Position and velocity (non-block entities)
BlockPosition	GridPosition	Position (block entities)
Drawable	boolean	Whether entity is visible when rendered
AnimatedSprite	integer	Animated sprite ID
Name	string	Name
Parent	integer	Entity ID of parent entity
Orientation	Orientation	Orientation
CastBlockShadows	boolean	Whether entity casts block shadows when rendered
PointLightSource	PointLight	Point light source

Example

Creating an entity using entities.Create(spec)

local entityId = entities.Create({
    Name = "Test Entity",
    Kinematics = {
        Position = {X = 0.0, Y = 0.0, Z = 0.0},
        Velocity = {X = 0.0, Y = 0.0, Z = 0.0}
    },
    Drawable = true,
    AnimatedSprite = 4
})

if (entityId) then
    util.LogDebug(string.format("Created new entity with ID %x.", entityId))
else
    util.LogError("Error while creating entity.")
end

Remove(entityId)

Definition

entities.Remove(entityId)

Removes the given entity from the game world.

Parameters:

entityId (integer) – Entity to remove.

Example

Removing an entity using entities.Remove(entityId)

entities.Remove(targetEntityId)