Collision object physics API documentation

Version: alpha

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

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

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.

PARAMETERS

None

RETURNS

EXAMPLES

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

physics.get_group()

physics.get_group(url)

Returns the group name of a collision object as a hash.

PARAMETERS

RETURNS

local function check_is_enemy()
    local group = physics.get_group("#collisionobject")
    return group == hash("enemy")
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

RETURNS

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

RETURNS

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

RETURNS

physics.get_maskbit()

physics.get_maskbit(url,group)

Returns true if the specified group is set in the mask of a collision object, false otherwise.

PARAMETERS

RETURNS

local function is_invincible()
    -- check if the collisionobject would collide with the "bullet" group
    local invincible = physics.get_maskbit("#collisionobject", "bullet")
    return invincible
end

physics.get_shape()

physics.get_shape(url,shape)

Gets collision shape data from a collision object

PARAMETERS

RETURNS

local function get_shape_meta()
    local sphere = physics.get_shape("#collisionobject", "my_sphere_shape")
    -- returns a table with sphere.diameter
    return sphere
end

physics.raycast()

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

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

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

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

EXAMPLES

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

physics.set_group()

physics.set_group(url,group)

Updates the group property of a collision object to the specified string value. The group name should exist i.e. have been used in a collision object in the editor.

PARAMETERS

local function change_collision_group()
     physics.set_group("#collisionobject", "enemy")
end

physics.set_hflip()

physics.set_hflip(url,flip)

Flips the collision shapes horizontally for a collision object

PARAMETERS

EXAMPLES

function init(self)
    self.fliph = true -- set on some condition
    physics.set_hflip("#collisionobject", self.fliph)
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

physics.set_listener()

physics.set_listener(callback)

sets a physics world event listener. If a function is set, physics messages will no longer be sent.

PARAMETERS

EXAMPLES

local function physics_world_listener(self, event, data)
  if event == hash("contact_point_event") then
    pprint(data)
    -- {
    --  distance = 2.1490633487701,
    --  applied_impulse = 0
    --  a = { --[[0x113f7c6c0]]
    --    group = hash: [box],
    --    id = hash: [/box]
    --    mass = 0,
    --    normal = vmath.vector3(0.379, 0.925, -0),
    --    position = vmath.vector3(517.337, 235.068, 0),
    --    instance_position = vmath.vector3(480, 144, 0),
    --    relative_velocity = vmath.vector3(-0, -0, -0),
    --  },
    --  b = { --[[0x113f7c840]]
    --    group = hash: [circle],
    --    id = hash: [/circle]
    --    mass = 0,
    --    normal = vmath.vector3(-0.379, -0.925, 0),
    --    position = vmath.vector3(517.337, 235.068, 0),
    --    instance_position = vmath.vector3(-0.0021, 0, -0.0022),
    --    relative_velocity = vmath.vector3(0, 0, 0),
    --  },
    -- }
  elseif event == hash("collision_event") then
    pprint(data)
    -- {
    --  a = {
    --          group = hash: [default],
    --          position = vmath.vector3(183, 666, 0),
    --          id = hash: [/go1]
    --      },
    --  b = {
    --          group = hash: [default],
    --          position = vmath.vector3(185, 704.05865478516, 0),
    --          id = hash: [/go2]
    --      }
    -- }
  elseif event ==  hash("trigger_event") then
    pprint(data)
    -- {
    --  enter = true,
    --  b = {
    --      group = hash: [default],
    --      id = hash: [/go2]
    --  },
    --  a = {
    --      group = hash: [default],
    --      id = hash: [/go1]
    --  }
    -- },
  elseif event ==  hash("ray_cast_response") then
    pprint(data)
    --{
    --  group = hash: [default],
    --  request_id = 0,
    --  position = vmath.vector3(249.92222595215, 249.92222595215, 0),
    --  fraction = 0.68759721517563,
    --  normal = vmath.vector3(0, 1, 0),
    --  id = hash: [/go]
    -- }
  elseif event ==  hash("ray_cast_missed") then
    pprint(data)
    -- {
    --  request_id = 0
    --},
  end
end

function init(self)
    physics.set_listener(physics_world_listener)
end

physics.set_maskbit()

physics.set_maskbit(url,group,maskbit)

Sets or clears the masking of a group (maskbit) in a collision object.

PARAMETERS

local function make_invincible()
    -- no longer collide with the "bullet" group
    physics.set_maskbit("#collisionobject", "bullet", false)
end

physics.set_shape()

physics.set_shape(url,shape,table)

Sets collision shape data for a collision object. Please note that updating data in 3D can be quite costly for box and capsules. Because of the physics engine, the cost comes from having to recreate the shape objects when certain shapes needs to be updated.

PARAMETERS

local function set_shape_data()
    -- set capsule shape data
    local data = {}
    data.type = physics.SHAPE_TYPE_CAPSULE
    data.diameter = 10
    data.height = 20
    physics.set_shape("#collisionobject", "my_capsule_shape", data)

    -- set sphere shape data
    data = {}
    data.type = physics.SHAPE_TYPE_SPHERE
    data.diameter = 10
    physics.set_shape("#collisionobject", "my_sphere_shape", data)

    -- set box shape data
    data = {}
    data.type = physics.SHAPE_TYPE_BOX
    data.dimensions = vmath.vector3(10, 10, 5)
    physics.set_shape("#collisionobject", "my_box_shape", data)
end

physics.set_vflip()

physics.set_vflip(url,flip)

Flips the collision shapes vertically for a collision object

PARAMETERS

EXAMPLES

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

physics.update_mass()

physics.update_mass(collisionobject,mass)

The function recalculates the density of each shape based on the total area of all shapes and the specified mass, then updates the mass of the body accordingly. Note: Currently only supported in 2D physics.

PARAMETERS

EXAMPLES

 physics.update_mass("#collisionobject", 14)

physics.wakeup()

physics.wakeup(url)

Collision objects tend to fall asleep when inactive for a small period of time for efficiency reasons. This function wakes them up.

PARAMETERS

function on_input(self, action_id, action)
    if action_id == hash("test") and action.pressed then
        physics.wakeup("#collisionobject")
    end
end

Constants

physics.JOINT_TYPE_FIXED

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

physics.JOINT_TYPE_HINGE

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

physics.JOINT_TYPE_SLIDER

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

physics.JOINT_TYPE_SPRING

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

physics.JOINT_TYPE_WELD

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

physics.JOINT_TYPE_WHEEL

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

physics.SHAPE_TYPE_BOX

physics.SHAPE_TYPE_CAPSULE

physics.SHAPE_TYPE_HULL

physics.SHAPE_TYPE_SPHERE

Messages

apply_force

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_event

See physics.set_listener. This message is sent to a function specified in physics.set_listener when two collision objects collide. This message only reports that a collision has occurred and will be sent once per frame and per colliding pair. For more detailed information, check for the contact_point_event.

EXAMPLES

physics.set_listener(function(self, event, data)
  if event == hash("collision_event") then
      pprint(data)
      -- {
      --  a = {
      --          group = hash: [default],
      --          position = vmath.vector3(183, 666, 0),
      --          id = hash: [/go1]
      --      },
      --  b = {
      --          group = hash: [default],
      --          position = vmath.vector3(185, 704.05865478516, 0),
      --          id = hash: [/go2]
      --      }
      -- }
  end
end)

collision_response

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_event

See physics.set_listener. This message is sent to a function specified in physics.set_listener when a collision object has contact points with another collision object. Since multiple contact points can occur for two colliding objects, this event 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_event event instead.

EXAMPLES

physics.set_listener(function(self, event, data)
 if event == hash("contact_point_event") then
     pprint(data)
     -- {
     --  applied_impulse = 310.00769042969,
     --  distance = 0.0714111328125,
     --  a = {
     --      position = vmath.vector3(446, 371, 0),
     --      relative_velocity = vmath.vector3(1.1722083854693e-06, -20.667181015015, -0),
     --      mass = 0,
     --      group = hash: [default],
     --      id = hash: [/flat],
     --      normal = vmath.vector3(-0, -1, -0)
     --  },
     --  b = {
     --      position = vmath.vector3(185, 657.92858886719, 0),
     --      relative_velocity = vmath.vector3(-1.1722083854693e-06, 20.667181015015, 0),
     --      mass = 10,
     --      group = hash: [default],
     --      id = hash: [/go2],
     --      normal = vmath.vector3(0, 1, 0)
     --  },
     -- }
  end
end)

contact_point_response

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

ray_cast_missed

This message is sent back to the sender of a ray_cast_request, or to the physics world listener if it is set (see physics.set_listener), if the ray didn't hit any collision object. See physics.raycast_async for examples of how to use it.

ray_cast_response

This message is sent back to the sender of a ray_cast_request, or to the physics world listener if it is set (see physics.set_listener), if the ray hits a collision object. See physics.raycast_async for examples of how to use it.

trigger_event

See physics.set_listener. This message is sent to a function specified in physics.set_listener when a collision object interacts with another collision object and one of them is a trigger. This message only reports that an interaction actually happened and will be sent once per colliding pair and frame. For more detailed information, check for the contact_point_event.

EXAMPLES

physics.set_listener(function(self, event, data)
 if event ==  hash("trigger_event") then
     if data.enter then
        -- take action for entry
     else
        -- take action for exit
     end
     pprint(data)
     -- {
     --  enter = true,
     --  b = {
     --      group = hash: [default],
     --      id = hash: [/go2]
     --  },
     --  a = {
     --      group = hash: [default],
     --      id = hash: [/go1]
     --  }
     -- },
  end
end)

trigger_response

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

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

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

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

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

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

linear_velocity

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

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

mass

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

EXAMPLES

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