components Module

All components and tags share a common API provided through the components module.

Component Submodules 

Each component collection that is accessible through the scripting engine may be accessed through a submodule of the global components module. The following table lists the component submodules, their associated component collection, and the corresponding value type.

Submodule	Component Collection	Value Type
`components.admin`	`AdminTagCollection`	`boolean`
`components.animated_sprite`	`AnimatedSpriteComponentCollection`	`integer`
`components.block_position`	`BlockPositionComponentCollection`	`GridPosition`
`components.cast_block_shadows`	`CastBlockShadowsTagCollection`	`boolean`
`components.drawable`	`DrawableTagCollection`	`boolean`
`components.kinematics`	`KinematicsComponentCollection`	`Kinematics`
`components.material`	`MaterialComponentCollection`	`integer`
`components.material_modifier`	`MaterialModifierComponentCollection`	`integer`
`components.name`	`NameComponentCollection`	`string`
`components.orientation`	`OrientationComponentCollection`	`integer`
`components.parent`	`ParentComponentCollection`	`integer`
`components.player_character`	`PlayerCharacterTagCollection`	`boolean`
`components.point_light`	`PointLightSourceComponentCollection`	`PointLight`

General Component Functions 

The following functions are common to multiple component types.

Exists(entityId)

Definition

components.<component>.Exists(entityId)

Gets whether the given entity has this component.

Parameters:: entityId (integer) – Entity ID.
Returns:: true if the entity has this component, or false otherwise.
Return type:: boolean

Example

Using Exists(entityId) to check for the presence of a tag.

if (components.player_character.Exists(entityId)) then
  -- This entity is a player character.
  util.log_info(string.format("%x is a player.", entityId))
end

Get(entityId)

Definition

components.<component>.Get(entityId)

Gets the component value for the given entity.

Parameters:: entityId (integer) – Entity ID.
Returns:: Component value, or nil if no the entity does not have this component. For tags, returns false instead of nil.
Return type:: Component value type

Example

Using Get(entityId) to get the name of an entity.

local name = components.name.Get(entityId)
if (name) then
  util.log_info(string.format("%x is named %s.", entityId, name))
end

Remove(entityId)

Definition

components.<component>.Remove(entityId)

Removes the component value for the given entity if it exists.

Parameters:: entityId (integer) – EntityID

Example

Using Remove(entityId) to remove a component from an entity.

-- Remove the point light source from an entity.
components.point_light.Remove(entityId)

Set(entityId, value)

Definition

components.<component>.Set(entityId, value)

Enqueues an update to the component value for the given entity with the next tick. Note that the effects of this operation will not be visible until the next tick.

For tag components, a value of true applies the flag to the entity, while a value of false removes the flag from the entity.

Parameters:

entityId (integer) – Entity ID.
value (Component value type, or boolean for tags) – New component value.

Example

Using `Set(entityId, value) to update a component.

-- Apply the drawable tag to the entity.
components.drawable.Set(entityId, true)

-- Component values are updated at the boundary between ticks, so the
-- earlier call to Set only enqueued an update. The result will not
-- be visible until the next tick, as demonstrated here:
if (components.drawable.Get(entityId)) then
    -- This path never executes (assuming the entity did not already
    -- have the tag applied) as component updates do not take effect
    -- until the following tick.
    -- ...
end

Add(entityId, value)

Definition

components.<component>.Add(entityId, value)

Enqueues an update to the component value which adds the given value to the current component value. This operation takes effect on the next tick and is cumulative with any other component changes.

This function is only supported for component types which define an addition operation. Attempting to use this function with other component types will result in no effect with an error being logged.

Parameters:

entityId (integer) – Entity ID.
value (Component value type) – Amount to be added to the current component value.

Example

Using Add(entityId, value) to update a component.

-- Decrease the entity's health by a fixed amount.
local currentHealth = components.health.Get(entityId)
components.health.Add(entityId, -10)

-- Component values are updated at the boundary between ticks, so the
-- earlier call to Add only enqueued an update. The result will not
-- be visible until the next tick, as demonstrated here:
if (components.health.Get(entityId) == currentHealth) then
    -- Entity health has not been changed yet - this branch executes.
    util.LogInfo("Entity health has not changed yet.")
end

Multiply(entityId, value)

Definition

components.<component>.Multiply(entityId, value)

Enqueues an update to the component value which multiplies the current component value by the given value. This operation takes effect on the next tick and is cumulative with any other component changes.

This function is only supported for component types which define a multiplication operation. Attempting to use this function with other component types will result in no effect with an error being logged.

Parameters:

entityId (integer) – Entity ID.
value (Component value type) – Amount by which to multiply the current component value.

Example

Using Multiply(entityId, value) to update a component.

-- Deal poison damage for 5% of the entity's current health.
local currentHealth = components.health.Get(entityId)
components.health.Multiply(entityId, 0.95)

-- Component values are updated at the boundary between ticks, so the
-- earlier call to Multiply only enqueued an update. The result will not
-- be visible until the next tick, as demonstrated here:
if (components.health.Get(entityId) == currentHealth) then
    -- Entity health has not been changed yet - this branch executes.
    util.LogInfo("Entity health has not changed yet.")
end

Divide(entityId, value)

Definition

components.<component>.Divide(entityId, value)

Enqueues an update to the component value which divides the current component value by the given value. This operation takes effect on the next tick and is cumulative with any other component changes.

This function is only supported for component types which define a division operation. Attempting to use this function with other component types will result in no effect with an error being logged.

Parameters:

entityId (integer) – Entity ID.
value (Component value type) – Amount by which to divide the current component value.

Example

Using Divide(entityId, value) to update a component.

-- Sacrifice half of entity's health to fully restore own mana.
local currentHealth = components.health.Get(entityId)
local maxMana = components.max_mana.Get(entityId)
components.mana.Set(entityId, maxMana)
components.health.Divide(entityId, 2.0)

-- Component values are updated at the boundary between ticks, so the
-- earlier call to Divide only enqueued an update. The result will not
-- be visible until the next tick, as demonstrated here:
if (components.health.Get(entityId) == currentHealth) then
    -- Entity health has not been changed yet - this branch executes.
    util.LogInfo("Entity health has not changed yet.")
end

Kinematics Functions 

SetVelocity(entityId, value)

Definition

components.kinematics.SetVelocity(entityId, value)

Enqueues an update to a kinematics component value which changes the velocity value only, leaving the position value unchanged. The new value is provided as a full Kinematics object where the position is ignored. This option takes effect on the next tick.

Parameters:

entityId (integer) – Entity ID.
value (Kinematics) – Kinematics object with velocity to use.

Example

Using SetVelocity(entityId, value) to update a component.

-- Stop any entity motion.
components.kinematics.SetVelocity(entityId, {
  Position = { X = 0.0, Y = 0.0, Z = 0.0 }, -- ignored
  Velocity = { X = 0.0, Y = 0.0, Z = 0.0 }  -- new velocity
})

AddPosition(entityId, value)

Definition

components.kinematics.AddPosition(entityId, value)

Enqueues an update to a kinematics component value which adds to the position only, leaving the velocity value unchanged. The new value is provided as a full Kinematics object where the velocity is ignored. This option takes effect on the next tick.

Parameters:

entityId (integer) – Entity ID.
value (Kinematics) – Kinematics object with position increment to use.

Example

Using AddPosition(entityId, value) to update a component.

-- Shift the entity by one block upward (+z direction).
components.kinematics.AddPosition(entityId, {
  Position = { X = 0.0, Y = 0.0, Z = 1.0 }, -- position step
  Velocity = { X = 0.0, Y = 0.0, Z = 0.0 }  -- ignored
})