LuaScript/entity

A reference to a Principia object.

entity:get_id()

Added in 1.3

Returns the unique ID of the current entity.

entity:get_id()

entity:get_g_id()

Added in 1.3

Returns the type ID of the current entity.

entity:get_g_id()

entity:get_position()

Added in 1.3

Returns the position of the current entity.

local x, y = entity:get_position()

entity:get_angle()

Added in 1.3

Returns the angle of the current entity, in radians.

local angle = entity:get_angle()

entity:set_angle()

Added in 2023.12.26 (2023-04-21)

Sets the angle of the entity, in radians. Only works on entities that are either completely free or attached to a hinge.

entity:set_angle(angle)

entity:set_fixed_rotation(bool)

Added in 2024.06.28 (2024-05-10)

Set whether the object should have its rotation fixed. When true the object will keep its angle no matter what other objects around it do.

entity:set_fixed_rotation(bool)

entity:is_fixed_rotation(bool)

Added in 2024.06.28 (2024-05-10)

Set whether the object should have its rotation fixed. When true the object will keep its angle no matter what other objects around it do.

local fixed_rotation = entity:is_fixed_rotation()

entity:get_velocity()

Added in 1.3

Returns the linear velocity of the current entity.

local xvel, yvel = entity:get_velocity()

entity:get_angular_velocity()

Added in 1.3

Returns the angular velocity of the current entity.

local avel = entity:get_angular_velocity()

entity:get_bbox()

Added in 1.3

Returns the approximate width and height of the object.

local width, height = entity:get_bbox()

entity:get_layer()

Added in 1.4

Returns the layer of the current entity.

local layer = entity:get_layer()

entity:local_to_world()

Added in 1.4

Returns the world coordinates converted from the given local coordinates from the current entity.

local wx, wy = entity:local_to_world(lx, ly)

entity:world_to_local()

Added in 1.4

Returns the local coordinates converted from the given world coordinates in relation to the current entity.

local lx, ly = entity:world_to_local(wx, wy)

entity:highlight()

Added in 1.4

Highlight the entity.

entity:highlight()

entity:damage()

Added in 1.5

Only works on creatures or destructible objects (if Interactive Destruction is enabled).

NOTE: Entering a negative amount will heal the object or creature.

entity:damage(amount)

entity:is_static()

Added in 1.5

Returns true if the entity is a static object (unable to move), otherwise false.

if entity:is_static() then
    game:message('This entity is static!')
end

entity:absorb()

Added in 1.5

Absorbs the entity if possible. The value returns indicates whether the absorb was completed successfully.

local success = entity:absorb(follow_connections)

entity:apply_torque()

Added in 1.5

Apply torque to the entity.

entity:apply_torque(torque)

entity:apply_force(x, y)

Added in 2024.06.28 (2024-05-10)

Apply force to the entity. The force will be applied in the center of mass.

entity:apply_force(x, y)

entity:set_velocity()

Added in 1.5

Sets the linear velocity of the given entity.

entity:set_velocity(x, y)

entity:warp()

Added in 1.5

Warps the entity to the given x/y world coordinates and layer. If the third argument is unset(layer), the layer will not be changed.

entity:warp(wx, wy, layer = -1)

entity:show()

Added in 1.5

Shows the entity if it was previously hidden.

entity:show()

entity:hide()

Added in 1.5

Hides the entity if it was previously visible. It will still interact with the world even though it's hidden.

entity:hide()

entity:is_hidden()

Added in 2023.12.26 (2023-04-19)

Returns whether the entity is currently hidden or not.

local is_hidden = entity:is_hidden()

entity:get_name()

Added in 1.5

Returns the name of the given entity.

local name = entity:get_name()

entity:is_creature()

Added in 1.5

Returns true if the given entity is a creature.

if entity:is_creature() then
    game:message(entity:get_name() .. ' is a creature!')
end

entity:is_robot()

Added in 1.5

Returns true if the given entity is any kind of robot.

if entity:is_robot() then
    game:message(entity:get_name() .. ' is a robot!')
end

entity:is_player()

Added in 1.5

Returns true if the given entity is the current player.

if entity:is_player() then
    game:message(entity:get_name() .. ' is the current player!')
end

entity:get_mass()

Added in 1.5

Returns the mass of the entity.

local mass = entity:get_mass()

entity:get_density()

Added in 1.5

Returns the average density of all fixtures of the given entity.

local density = entity:get_density()

entity:get_friction()

Added in 1.5

Returns the average friction of all fixtures of the given entity.

local friction = entity:get_friction()

entity:get_restitution()

Added in 1.5

Returns the average restitution of all fixtures of the given entity.

local restitution = entity:get_restitution()

entity:set_color()

Added in 1.5

Sets the color of the given entity, if possible. Does not work with all entities.

NOTE: This function should be used sparingly due to its performance cost, especially when used on pixels.

entity:set_color(r, g, b)

entity:get_color()

Added in 1.5

Gets the color of the given entity, if possible. Does not work with all entities.

local r, g, b, a = entity:get_color()

entity:disconnect_all()

Added in 1.5

Detach all connections from the entity.

entity:disconnect_all()

entity:set_target_id()

Added in 1.5

Sets the target ID of the given entity. Currently only usable with the robot manager.

entity:set_target_id(target_id)

entity:call()

Added in 1.5

If the entity is a LuaScript object, call the specified function.

local x, y = entity:call("my_ultracool_function", a, b, c)