Version: stable
FUNCTION | |
---|---|
physics.raycast_async() | requests a ray cast to be performed |
physics.raycast() | requests a ray cast to be performed |
physics.create_joint() | create a physics joint |
physics.destroy_joint() | destroy a physics joint |
physics.get_joint_properties() | get properties for a joint |
physics.set_joint_properties() | set properties for a joint |
physics.get_joint_reaction_force() | get the reaction force for a joint |
physics.get_joint_reaction_torque() | get the reaction torque for a joint |
physics.set_gravity() | set the gravity for collection |
physics.get_gravity() | get the gravity for collection |
physics.set_hflip() | flip the geometry horizontally for a collision object |
physics.set_vflip() | flip the geometry vertically for a collision object |
CONSTANT | |
---|---|
physics.JOINT_TYPE_SPRING | spring joint type |
physics.JOINT_TYPE_FIXED | fixed joint type |
physics.JOINT_TYPE_HINGE | hinge joint type |
physics.JOINT_TYPE_SLIDER | slider joint type |
MESSAGE | |
---|---|
apply_force | applies a force on a collision object |
collision_response | reports a collision between two collision objects |
contact_point_response | reports a contact point between two collision objects |
trigger_response | reports interaction (enter/exit) between a trigger collision object and another collision object |
ray_cast_response | reports a ray cast hit |
ray_cast_missed | reports a ray cast miss |
PROPERTIES | |
---|---|
mass | number collision object mass |
linear_velocity | vector3 collision object linear velocity |
angular_velocity | vector3 collision object angular velocity |
linear_damping | number collision object linear damping |
angular_damping | number collision object angular damping |
physics.raycast_async(from,to,groups,[request_id])
groups
.
The actual ray cast will be performed during the physics-update.
ray_cast_response
message.ray_cast_missed
message.PARAMETERS
from |
the world position of the start of the ray |
to |
the world position of the end of the ray |
groups |
a lua table containing the hashed groups for which to test collisions against |
[request_id] |
. 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.raycast(from,to,groups,options)
groups
.
PARAMETERS
from |
the world position of the start of the ray |
to |
the world position of the end of the ray |
groups |
a lua table containing the hashed groups for which to test collisions against |
options |
a lua table containing options for the raycast.
|
RETURNS
result |
It returns a list. 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.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(joint_type,collisionobject_a,joint_id,position_a,collisionobject_b,position_b,[properties])
PARAMETERS
joint_type |
the joint type |
collisionobject_a |
first collision object |
joint_id |
id of the joint |
position_a |
local position where to attach the joint on the first collision object |
collisionobject_b |
second collision object |
position_b |
local position where to attach the joint on the second collision object |
[properties] |
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(collisionobject,joint_id)
PARAMETERS
collisionobject |
collision object where the joint exist |
joint_id |
id of the joint |
physics.get_joint_properties(collisionobject,joint_id)
PARAMETERS
collisionobject |
collision object where the joint exist |
joint_id |
id of the joint |
RETURNS
|
properties table. See the joint types for what fields are available, the only field available for all types is:
|
physics.set_joint_properties(collisionobject,joint_id,properties)
PARAMETERS
collisionobject |
collision object where the joint exist |
joint_id |
id of the joint |
properties |
joint specific properties table
Note: The collide_connected field cannot be updated/changed after a connection has been made. |
physics.get_joint_reaction_force(collisionobject,joint_id)
PARAMETERS
collisionobject |
collision object where the joint exist |
joint_id |
id of the joint |
RETURNS
force |
reaction force for the joint |
physics.get_joint_reaction_torque(collisionobject,joint_id)
PARAMETERS
collisionobject |
collision object where the joint exist |
joint_id |
id of the joint |
RETURNS
torque |
the reaction torque on bodyB in N*m. |
physics.set_gravity(gravity)
PARAMETERS
gravity |
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.get_gravity()
PARAMETERS
RETURNS
|
gravity vector of collection |
EXAMPLES
function init(self) local gravity = physics.get_gravity() -- Inverse gravity! gravity = -gravity physics.set_gravity(gravity) end
physics.set_hflip(url,flip)
PARAMETERS
url |
the collision object that should flip its shapes |
flip |
true if the collision object should flip its shapes, false if not |
EXAMPLES
function init(self) self.fliph = true -- set on some condition physics.set_hflip("#collisionobject", self.fliph) end
physics.set_vflip(url,flip)
PARAMETERS
url |
the collision object that should flip its shapes |
flip |
true if the collision object should flip its shapes, false if not |
EXAMPLES
function init(self) self.flipv = true -- set on some condition physics.set_vflip("#collisionobject", self.flipv) end
spring joint type
The following properties are available when connecting a joint of JOINT_TYPE_SPRING
type:
length |
The natural length between the anchor points. |
frequency |
The mass-spring-damper frequency in Hertz. A value of 0 disables softness. |
damping |
The damping ratio. 0 = no damping, 1 = critical damping. |
fixed joint type
The following properties are available when connecting a joint of JOINT_TYPE_FIXED
type:
max_length |
The maximum length of the rope. |
hinge joint type
The following properties are available when connecting a joint of JOINT_TYPE_HINGE
type:
reference_angle |
The bodyB angle minus bodyA angle in the reference state (radians). |
lower_angle |
The lower angle for the joint limit (radians). |
upper_angle |
The upper angle for the joint limit (radians). |
max_motor_torque |
The maximum motor torque used to achieve the desired motor speed. Usually in N-m. |
motor_speed |
The desired motor speed. Usually in radians per second. |
enable_limit |
A flag to enable joint limits. |
enable_motor |
A flag to enable the joint motor. |
joint_angle |
Current joint angle in radians.
(Read only field, available from physics.get_joint_properties() ) |
joint_speed |
Current joint angle speed in radians per second.
(Read only field, available from physics.get_joint_properties() ) |
slider joint type
The following properties are available when connecting a joint of JOINT_TYPE_SLIDER
type:
local_axis_a |
The local translation unit axis in bodyA. |
reference_angle |
The constrained angle between the bodies: bodyB_angle - bodyA_angle. |
enable_limit |
Enable/disable the joint limit. |
lower_translation |
The lower translation limit, usually in meters. |
upper_translation |
The upper translation limit, usually in meters. |
enable_motor |
Enable/disable the joint motor. |
max_motor_force |
The maximum motor torque, usually in N-m. |
motor_speed |
The desired motor speed in radians per second. |
joint_translation |
Current joint translation, usually in meters.
(Read only field, available from physics.get_joint_properties() ) |
joint_speed |
Current joint translation speed, usually in meters per second.
(Read only field, available from physics.get_joint_properties() ) |
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.
force |
the force to be applied on the collision object, measured in Newton |
position |
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()})
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.
other_id |
the id of the instance the collision object collided with |
other_position |
the world position of the instance the collision object collided with |
other_group |
the collision group of the other collision object (hash) |
own_group |
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
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.
position |
world position of the contact point |
normal |
normal in world space of the contact point, which points from the other object towards the current object |
relative_velocity |
the relative velocity of the collision object as observed from the other object |
distance |
the penetration distance between the objects, which is always positive |
applied_impulse |
the impulse the contact resulted in |
life_time |
life time of the contact, not currently used |
mass |
the mass of the current collision object in kg |
other_mass |
the mass of the other collision object in kg |
other_id |
the id of the instance the collision object is in contact with |
other_position |
the world position of the other collision object |
other_group |
the collision group of the other collision object (hash) |
own_group |
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
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.
other_id |
the id of the instance the collision object collided with (hash) |
enter |
if the interaction was an entry or not |
other_group |
the collision group of the triggering collision object (hash) |
own_group |
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
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.
fraction |
the fraction of the hit measured along the ray, where 0 is the start of the ray and 1 is the end |
position |
the world position of the hit |
normal |
the normal of the surface of the collision object where it was hit |
id |
the instance id of the hit collision object |
group |
the collision group of the hit collision object as a hashed name |
request_id |
id supplied when the ray cast was requested |
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.
request_id |
id supplied when the ray cast was requested |
READ ONLY Returns the defined physical mass of the collision object component as a number.
number collision object mass
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)
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
How to query and modify 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") -- 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 })
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
How to query and modify a collision object component's angular velocity:-- 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)
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
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
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
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)