Collision object physics API documentation

Version: stable

Functions

physics.raycast_async()

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

• 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

EXAMPLES

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.raycast()

physics.raycast(from,to,groups,options)

PARAMETERS

RETURNS

EXAMPLES

function init(self)
    self.groups = {hash("world"), hash("enemy")}
end

function update(self, dt)
    -- request ray cast
    local result = physics.raycast(from, to, self.groups, {all=true})
    if result ~= nil then
        -- act on the hit (see 'ray_cast_response')
        for _,result in ipairs(results) do
            handle_result(result)
        end
    end
end

physics.create_joint()

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

PARAMETERS

physics.destroy_joint()

physics.destroy_joint(collisionobject,joint_id)

PARAMETERS

physics.get_joint_properties()

physics.get_joint_properties(collisionobject,joint_id)

PARAMETERS

RETURNS

physics.set_joint_properties()

physics.set_joint_properties(collisionobject,joint_id,properties)

PARAMETERS

physics.get_joint_reaction_force()

physics.get_joint_reaction_force(collisionobject,joint_id)

PARAMETERS

RETURNS

physics.get_joint_reaction_torque()

physics.get_joint_reaction_torque(collisionobject,joint_id)

PARAMETERS

RETURNS

physics.set_gravity()

physics.set_gravity(gravity)

PARAMETERS

EXAMPLES

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

physics.get_gravity()

physics.get_gravity()

PARAMETERS

RETURNS

EXAMPLES

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

physics.set_hflip()

physics.set_hflip(url,flip)

PARAMETERS

EXAMPLES

function init(self)
    self.fliph = true -- set on some condition
    physics.set_hflip("#collisionobject", self.fliph)
end

physics.set_vflip()

physics.set_vflip(url,flip)

PARAMETERS

EXAMPLES

function init(self)
    self.flipv = true -- set on some condition
    physics.set_vflip("#collisionobject", self.flipv)
end

Constants

physics.JOINT_TYPE_SPRING

spring joint type

The following properties are available when connecting a joint of JOINT_TYPE_SPRING type:

physics.JOINT_TYPE_FIXED

fixed joint type

The following properties are available when connecting a joint of JOINT_TYPE_FIXED type:

physics.JOINT_TYPE_HINGE

hinge joint type

The following properties are available when connecting a joint of JOINT_TYPE_HINGE type:

physics.JOINT_TYPE_SLIDER

slider joint type

The following properties are available when connecting a joint of JOINT_TYPE_SLIDER type:

Messages

apply_force

applies a force on a collision object

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

EXAMPLES

-- 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

reports a collision between two collision objects

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.

EXAMPLES

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

reports a contact point between two collision objects

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.

EXAMPLES

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

trigger_response

reports interaction (enter/exit) between a trigger collision object and another collision object

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.

EXAMPLES

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

ray_cast_response

reports a ray cast hit

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.

ray_cast_missed

reports a ray cast miss

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.

Properties

mass

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

number collision object mass

EXAMPLES

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

linear_velocity

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

vector3 collision object linear velocity

EXAMPLES

-- get linear velocity from collision object "collisionobject" in gameobject "ship"
local source = "ship#collisionobject"
local velocity = go.get(source, "linear_velocity")
-- decrease it by 10%
go.set(source, "linear_velocity", velocity * 0.9)
-- 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 })

angular_velocity

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.

vector3 collision object angular velocity

EXAMPLES

-- get angular velocity from collision object "collisionobject" in gameobject "boulder"
local velocity = go.get("boulder#collisionobject", "angular_velocity")
-- do something interesting
if velocity.z < 0 then
    -- clockwise rotation
    ...
else
    -- counter clockwise rotation
    ...
end
-- decrease it by 10%
velocity.z = velocity.z * 0.9
go.set("boulder#collisionobject", "angular_velocity", velocity * 0.9)

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).

number collision object linear damping

EXAMPLES

-- 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

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).

number collision object angular damping

EXAMPLES

-- 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)