- Select ref document -

Collision object physics API documentation

version 1.2.159

Functions and messages for collision object physics interaction with other objects (collisions and ray-casting) and control of physical behaviors.

Functions

physics.create_joint

physics.create_joint(joint_type, collisionobject_a, joint_id, position_a, collisionobject_b, position_b, [properties])

Create a physics joint between two collision object components.

Note: Currently only supported in 2D physics.

Parameters

joint_type

number the joint type

collisionobject_a

string | hash | url first collision object

joint_id

string | hash id of the joint

position_a

vector3 local position where to attach the joint on the first collision object

collisionobject_b

string | hash | url second collision object

position_b

vector3 local position where to attach the joint on the second collision object

[properties]

table optional joint specific properties table

See each joint type for possible properties field. The one field that is accepted for all joint types is: - boolean collide_connected: Set this flag to true if the attached bodies should collide.

joint_type

number the joint type

collisionobject_a

string | hash | url first collision object

joint_id

string | hash id of the joint

position_a

vector3 local position where to attach the joint on the first collision object

collisionobject_b

string | hash | url second collision object

position_b

vector3 local position where to attach the joint on the second collision object

[properties]

table optional joint specific properties table

See each joint type for possible properties field. The one field that is accepted for all joint types is: - boolean collide_connected: Set this flag to true if the attached bodies should collide.

physics.destroy_joint

physics.destroy_joint(collisionobject, joint_id)

Destroy an already physics joint. The joint has to be created before a destroy can be issued.

Note: Currently only supported in 2D physics.

Parameters

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

physics.get_gravity

physics.get_gravity()

Get the gravity in runtime. The gravity returned is not global, it will return the gravity for the collection that the function is called from.

Note: For 2D physics the z component will always be zero.

Returns

[type:vector3]

gravity vector of collection

[type:vector3]

gravity vector of collection

Examples

function init(self)
    local gravity = physics.get_gravity()
    -- Inverse gravity!
    gravity = -gravity
    physics.set_gravity(gravity)
end

physics.get_joint_properties

physics.get_joint_properties(collisionobject, joint_id)

Get a table for properties for a connected joint. The joint has to be created before properties can be retrieved.

Note: Currently only supported in 2D physics.

Parameters

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

Returns

[type:table]

properties table. See the joint types for what fields are available, the only field available for all types is:

  • boolean collide_connected: Set this flag to true if the attached bodies should collide.
[type:table]

properties table. See the joint types for what fields are available, the only field available for all types is:

  • boolean collide_connected: Set this flag to true if the attached bodies should collide.

physics.get_joint_reaction_force

physics.get_joint_reaction_force(collisionobject, joint_id)

Get the reaction force for a joint. The joint has to be created before the reaction force can be calculated.

Note: Currently only supported in 2D physics.

Parameters

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

Returns

force

vector3 reaction force for the joint

force

vector3 reaction force for the joint

physics.get_joint_reaction_torque

physics.get_joint_reaction_torque(collisionobject, joint_id)

Get the reaction torque for a joint. The joint has to be created before the reaction torque can be calculated.

Note: Currently only supported in 2D physics.

Parameters

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

Returns

torque

float the reaction torque on bodyB in N*m.

torque

float the reaction torque on bodyB in N*m.

physics.raycast

physics.raycast(from, to, groups)

Ray casts are used to test for intersections against collision objects in the physics world. Collision objects of types kinematic, dynamic and static are tested against. Trigger objects do not intersect with ray casts. Which collision objects to hit is filtered by their collision groups and can be configured through groups.

Parameters

from

vector3 the world position of the start of the ray

to

vector3 the world position of the end of the ray

groups

table a lua table containing the hashed groups for which to test collisions against

from

vector3 the world position of the start of the ray

to

vector3 the world position of the end of the ray

groups

table a lua table containing the hashed groups for which to test collisions against

Returns

result

table It returns a table. If missed it returns nil. See ray_cast_response for details on the returned values.

result

table It returns a table. If missed it returns nil. See ray_cast_response for details on the returned values.

Examples

How to perform a ray cast synchronously:

function init(self)
    self.my_groups = {hash("my_group1"), hash("my_group2")}
end

function update(self, dt)
    -- request ray cast
    local result = physics.raycast(my_start, my_end, self.my_groups)
    if result ~= nil then
        -- act on the hit (see 'ray_cast_response')
    end
end

physics.raycast_async

physics.raycast_async(from, to, groups, [request_id])

Ray casts are used to test for intersections against collision objects in the physics world. Collision objects of types kinematic, dynamic and static are tested against. Trigger objects do not intersect with ray casts. Which collision objects to hit is filtered by their collision groups and can be configured through groups. The actual ray cast will be performed during the physics-update.

  • If an object is hit, the result will be reported via a ray_cast_response message.
  • If there is no object hit, the result will be reported via a ray_cast_missed message.

Parameters

from

vector3 the world position of the start of the ray

to

vector3 the world position of the end of the ray

groups

table a lua table containing the hashed groups for which to test collisions against

[request_id]

number a number between [0,-255]. It will be sent back in the response for identification, 0 by default

from

vector3 the world position of the start of the ray

to

vector3 the world position of the end of the ray

groups

table a lua table containing the hashed groups for which to test collisions against

[request_id]

number a number between [0,-255]. It will be sent back in the response for identification, 0 by default

Examples

How to perform a ray cast asynchronously:

function init(self)
    self.my_groups = {hash("my_group1"), hash("my_group2")}
end

function update(self, dt)
    -- request ray cast
    physics.raycast_async(my_start, my_end, self.my_groups)
end

function on_message(self, message_id, message, sender)
    -- check for the response
    if message_id == hash("ray_cast_response") then
        -- act on the hit
    elseif message_id == hash("ray_cast_missed") then
        -- act on the miss
    end
end

physics.set_gravity

physics.set_gravity(gravity)

Set the gravity in runtime. The gravity change is not global, it will only affect the collection that the function is called from.

Note: For 2D physics the z component of the gravity vector will be ignored.

Parameters

gravity

vector3 the new gravity vector

gravity

vector3 the new gravity vector

Examples

function init(self)
    -- Set "upside down" gravity for this collection.
    physics.set_gravity(vmath.vector3(0, 10.0, 0))
end

physics.set_joint_properties

physics.set_joint_properties(collisionobject, joint_id, properties)

Updates the properties for an already connected joint. The joint has to be created before properties can be changed.

Note: Currently only supported in 2D physics.

Parameters

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

properties

table joint specific properties table

Note: The collide_connected field cannot be updated/changed after a connection has been made.

collisionobject

string | hash | url collision object where the joint exist

joint_id

string | hash id of the joint

properties

table joint specific properties table

Note: The collide_connected field cannot be updated/changed after a connection has been made.

Messages

apply_force

"apply_force", { force=…, position=… }

Post this message to a collision-object-component to apply the specified force on the collision object. The collision object must be dynamic.

Fields

force

vector3 the force to be applied on the collision object, measured in Newton

position

vector3 the position where the force should be applied

force

vector3 the force to be applied on the collision object, measured in Newton

position

vector3 the position where the force should be applied

Examples

Assuming the instance of the script has a collision-object-component with id "co":

-- apply a force of 1 Newton towards world-x at the center of the game object instance
msg.post("#co", "apply_force", {force = vmath.vector3(1, 0, 0), position = go.get_world_position()})

collision_response

"collision_response", { other_id=…, other_position=…, other_group=…, own_group=… }

This message is broadcasted to every component of an instance that has a collision object, when the collision object collides with another collision object. For a script to take action when such a collision happens, it should check for this message in its on_message callback function.

This message only reports that a collision actually happened and will only be sent once per colliding pair and frame. To retrieve more detailed information, check for the contact_point_response instead.

Fields

other_id

hash the id of the instance the collision object collided with

other_position

vector3 the world position of the instance the collision object collided with

other_group

hash the collision group of the other collision object (hash)

own_group

hash the collision group of the own collision object (hash)

other_id

hash the id of the instance the collision object collided with

other_position

vector3 the world position of the instance the collision object collided with

other_group

hash the collision group of the other collision object (hash)

own_group

hash the collision group of the own collision object (hash)

Examples

How to take action when a collision occurs:

function on_message(self, message_id, message, sender)
    -- check for the message
    if message_id == hash("collision_response") then
        -- take action
    end
end

contact_point_response

"contact_point_response", { position=…, normal=…, relative_velocity=…, distance=…, applied_impulse=…, life_time=…, mass=…, other_mass=…, other_id=…, other_position=…, other_group=…, own_group=… }

This message is broadcasted to every component of an instance that has a collision object, when the collision object has contact points with respect to another collision object. For a script to take action when such contact points occur, it should check for this message in its on_message callback function.

Since multiple contact points can occur for two colliding objects, this message can be sent multiple times in the same frame for the same two colliding objects. To only be notified once when the collision occurs, check for the collision_response message instead.

Fields

position

vector3 world position of the contact point

normal

vector3 normal in world space of the contact point, which points from the other object towards the current object

relative_velocity

vector3 the relative velocity of the collision object as observed from the other object

distance

number the penetration distance between the objects, which is always positive

applied_impulse

number the impulse the contact resulted in

life_time

number life time of the contact, not currently used

mass

number the mass of the current collision object in kg

other_mass

number the mass of the other collision object in kg

other_id

hash the id of the instance the collision object is in contact with

other_position

vector3 the world position of the other collision object

other_group

hash the collision group of the other collision object (hash)

own_group

hash the collision group of the own collision object (hash)

position

vector3 world position of the contact point

normal

vector3 normal in world space of the contact point, which points from the other object towards the current object

relative_velocity

vector3 the relative velocity of the collision object as observed from the other object

distance

number the penetration distance between the objects, which is always positive

applied_impulse

number the impulse the contact resulted in

life_time

number life time of the contact, not currently used

mass

number the mass of the current collision object in kg

other_mass

number the mass of the other collision object in kg

other_id

hash the id of the instance the collision object is in contact with

other_position

vector3 the world position of the other collision object

other_group

hash the collision group of the other collision object (hash)

own_group

hash the collision group of the own collision object (hash)

Examples

How to take action when a contact point occurs:

function on_message(self, message_id, message, sender)
    -- check for the message
    if message_id == hash("contact_point_response") then
        -- take action
    end
end

ray_cast_missed

"ray_cast_missed", { request_id=… }

This message is sent back to the sender of a ray_cast_request, if the ray didn't hit any collision object. See physics.raycast_async for examples of how to use it.

Fields

request_id

number id supplied when the ray cast was requested

request_id

number id supplied when the ray cast was requested

ray_cast_response

"ray_cast_response", { fraction=…, position=…, normal=…, id=…, group=…, request_id=… }

This message is sent back to the sender of a ray_cast_request, if the ray hit a collision object. See physics.raycast_async for examples of how to use it.

Fields

fraction

number the fraction of the hit measured along the ray, where 0 is the start of the ray and 1 is the end

position

vector3 the world position of the hit

normal

vector3 the normal of the surface of the collision object where it was hit

id

hash the instance id of the hit collision object

group

hash the collision group of the hit collision object as a hashed name

request_id

number id supplied when the ray cast was requested

fraction

number the fraction of the hit measured along the ray, where 0 is the start of the ray and 1 is the end

position

vector3 the world position of the hit

normal

vector3 the normal of the surface of the collision object where it was hit

id

hash the instance id of the hit collision object

group

hash the collision group of the hit collision object as a hashed name

request_id

number id supplied when the ray cast was requested

trigger_response

"trigger_response", { other_id=…, enter=…, other_group=…, own_group=… }

This message is broadcasted to every component of an instance that has a collision object, when the collision object interacts with another collision object and one of them is a trigger. For a script to take action when such an interaction happens, it should check for this message in its on_message callback function.

This message only reports that an interaction actually happened and will only be sent once per colliding pair and frame. To retrieve more detailed information, check for the contact_point_response instead.

Fields

other_id

hash the id of the instance the collision object collided with (hash)

enter

boolean if the interaction was an entry or not

other_group

hash the collision group of the triggering collision object (hash)

own_group

hash the collision group of the own collision object (hash)

other_id

hash the id of the instance the collision object collided with (hash)

enter

boolean if the interaction was an entry or not

other_group

hash the collision group of the triggering collision object (hash)

own_group

hash the collision group of the own collision object (hash)

Examples

How to take action when a trigger interaction occurs:

function on_message(self, message_id, message, sender)
    -- check for the message
    if message_id == hash("trigger_response") then
        if message.enter then
            -- take action for entry
        else
            -- take action for exit
        end
    end
end

Constants

physics.JOINT_TYPE_FIXED

The following properties are available when connecting a joint of JOINT_TYPE_FIXED type: - number max_length: The maximum length of the rope.

physics.JOINT_TYPE_HINGE

The following properties are available when connecting a joint of JOINT_TYPE_HINGE type: - number reference_angle: The bodyB angle minus bodyA angle in the reference state (radians). - number lower_angle: The lower angle for the joint limit (radians). - number upper_angle: The upper angle for the joint limit (radians). - number max_motor_torque: The maximum motor torque used to achieve the desired motor speed. Usually in N-m. - number motor_speed: The desired motor speed. Usually in radians per second. - boolean enable_limit: A flag to enable joint limits. - boolean enable_motor: A flag to enable the joint motor.

Read only fields, available from physics.get_joint_properties(): - number joint_angle: Current joint angle in radians. - number joint_speed: Current joint angle speed in radians per second.

physics.JOINT_TYPE_SLIDER

The following properties are available when connecting a joint of JOINT_TYPE_SLIDER type: - vector3 local_axis_a: The local translation unit axis in bodyA. - number reference_angle: The constrained angle between the bodies: bodyB_angle - bodyA_angle. - boolean enable_limit: Enable/disable the joint limit. - number lower_translation: The lower translation limit, usually in meters. - number upper_translation: The upper translation limit, usually in meters. - boolean enable_motor: Enable/disable the joint motor. - number max_motor_force: The maximum motor torque, usually in N-m. - number motor_speed: The desired motor speed in radians per second.

Read only fields, available from physics.get_joint_properties(): - number joint_translation: Current joint translation, usually in meters. - number joint_speed: Current joint translation speed, usually in meters per second.

physics.JOINT_TYPE_SPRING

The following properties are available when connecting a joint of JOINT_TYPE_SPRING type: - number length: The natural length between the anchor points. - number frequency: The mass-spring-damper frequency in Hertz. A value of 0 disables softness. - number damping: The damping ratio. 0 = no damping, 1 = critical damping.

Properties

angular_damping

The angular damping value for the collision object. Setting this value alters the damping of angular motion of the object (rotation). Valid values are between 0 (no damping) and 1 (full damping).

Examples

How to decrease a collision object component's angular damping:

-- get angular damping from collision object "collisionobject" in gameobject "floater"
local target = "floater#collisionobject"
local damping = go.get(target, "angular_damping")
-- decrease it by 10%
go.set(target, "angular_damping", damping * 0.9)

angular_velocity

READ ONLY Returns the current angular velocity of the collision object component as a vector3. The velocity is measured as a rotation around the vector with a speed equivalent to the vector length in radians/s.

Examples

How to query a collision object component's angular velocity:

-- get angular velocity from collision object "collisionobject" in gameobject "boulder"
-- this is a 2d game so rotation around z is the only one available.
local velocity = go.get("boulder#collisionobject", "angular_velocity.z")
-- do something interesting
if velocity < 0 then
    -- clockwise rotation
    ...
else
    -- counter clockwise rotation
    ...
end

linear_damping

The linear damping value for the collision object. Setting this value alters the damping of linear motion of the object. Valid values are between 0 (no damping) and 1 (full damping).

Examples

How to increase a collision object component's linear damping:

-- get linear damping from collision object "collisionobject" in gameobject "floater"
local target = "floater#collisionobject"
local damping = go.get(target, "linear_damping")
-- increase it by 10% if it's below 0.9
if damping <= 0.9 then
    go.set(target, "linear_damping", damping * 1.1)
end

linear_velocity

READ ONLY Returns the current linear velocity of the collision object component as a vector3. The velocity is measured in units/s (pixels/s).

Examples

How to query a collision object component's linear velocity:

-- get linear velocity from collision object "collisionobject" in gameobject "ship"
local source = "ship#collisionobject"
local velocity = go.get(source, "linear_velocity")
-- apply the velocity on target game object "boulder"'s collision object as a force
local target = "boulder#collisionobject"
local pos = go.get_position(target)
msg.post(target, "apply_force", { force = velocity, position = pos })

mass

READ ONLY Returns the defined physical mass of the collision object component as a number.

Examples

How to query a collision object component's mass:

-- get mass from collision object component "boulder"
local mass = go.get("#boulder", "mass")
-- do something useful
assert(mass > 1)