View source

final class Physics

package defold

@:native("_G.physics")
  • Functions and messages for collision object physics interaction with other objects (collisions and ray-casting) and control of physical behaviors.

See PhysicsProperties for related properties. See PhysicsMessages for related messages.

Static methods

@:native("create_joint")staticcreateJoint(joint_type:PhysicsJointType, collisionobjectA:HashOrStringOrUrl, jointId:HashOrString, position_A:Vector3, collisionobjectB:HashOrStringOrUrl, position_B:Vector3, ?properties:Null<PhysicsFixedJoint>):Void

@:native("create_joint")staticcreate_joint(joint_type:PhysicsJointType, collisionobjectA:HashOrStringOrUrl, jointId:HashOrString, position_A:Vector3, collisionobjectB:HashOrStringOrUrl, position_B:Vector3, ?properties:Null<PhysicsHingeJoint>):Void

@:native("create_joint")staticcreate_joint(joint_type:PhysicsJointType, collisionobjectA:HashOrStringOrUrl, jointId:HashOrString, position_A:Vector3, collisionobjectB:HashOrStringOrUrl, position_B:Vector3, ?properties:Null<PhysicsSliderJoint>):Void

@:native("create_joint")staticcreate_joint(joint_type:PhysicsJointType, collisionobjectA:HashOrStringOrUrl, jointId:HashOrString, position_A:Vector3, collisionobjectB:HashOrStringOrUrl, position_B:Vector3, ?properties:Null<PhysicsSpringJoint>):Void

  • Create a physics joint between two collision object components.

Note: Currently only supported in 2D physics.

Parameters:

joint_type

the joint type

collisionobjectA

first collision object

jointId

id of the joint

positionA

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

collisionobjectB

second collision object

positionB

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.

@:native("destroy_joint")staticdestroyJoint(collisionobject:HashOrStringOrUrl, jointId:HashOrString):Void

  • 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

collision object where the joint exist

jointId

id of the joint

@:native("get_gravity")staticgetGravity():Vector3

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

@:native("get_group")staticgetGroup(url:HashOrStringOrUrl):Hash

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

Parameters:

url

the collision object to return the group of

Returns:

hash value of the group

@:native("get_joint_properties")staticgetJointProperties(collisionobject:HashOrStringOrUrl, jointId:HashOrString):EitherType<PhysicsFixedJoint, EitherType<PhysicsHingeJoint, EitherType<PhysicsSliderJoint, PhysicsSpringJoint>>>

  • 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

collision object where the joint exist

jointId

id of the joint

Returns:

properties table. See the joint types for what fields are available

@:native("get_joint_reaction_force")staticgetJointReactionForce(collisionobject:HashOrStringOrUrl, jointId:HashOrString):Vector3

  • 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

collision object where the joint exist

jointId

id of the joint

Returns:

reaction force for the joint

@:native("get_joint_reaction_torque")staticgetJointReactionTorque(collisionobject:HashOrStringOrUrl, jointId:HashOrString):Float

  • 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

collision object where the joint exist

jointId

id of the joint

Returns:

the reaction torque on bodyB in N*m.

@:native("get_maskbit")staticgetMaskbit(url:HashOrString, group:String):Bool

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

Parameters:

url

the collision object to check the mask of

group

the name of the group to check for

Returns:

boolean value of the maskbit. true if present, false otherwise

staticinlinegetShape(url:HashOrString, shapeName:HashOrString):PhysicsShape

  • Gets collision shape data from a collision object

Parameters:

url

the collision object

shapeName

the name of the shape to get data for

Returns:

the physics shape

staticraycast(from:Vector3, to:Vector3, groups:LuaArray<Hash>, ?options:Null<PhysicsRaycastOptions>):LuaArray<PhysicsMessageRayCastResponse>

  • Requests a ray cast to be performed.

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.

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

@:native("raycast_async")staticraycastAsync(from:Vector3, to:Vector3, groups:LuaArray<Hash>, ?request_id:Int):Void

  • Requests a ray cast to be performed.

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

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

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

@:native("set_gravity")staticsetGravity(gravity:Vector3):Void

  • 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

the new gravity vector

@:native("set_group")staticsetGroup(url:HashOrStringOrUrl, group:String):Void

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

url

the collision object affected

group

the new group name to be assigned

@:native("set_hflip")staticsetHflip(url:HashOrStringOrUrl, flip:Bool):Void

  • Flips the collision shapes horizontally for a collision object

Parameters:

url

the collision object that should flip its shapes

flip

true if the collision object should flip its shapes, false if not

@:native("set_joint_properties")staticsetJointProperties(collisionobject:HashOrStringOrUrl, jointId:HashOrString, properties:PhysicsFixedJoint):Void

@:native("set_joint_properties")staticset_joint_properties(collisionobject:HashOrStringOrUrl, jointId:HashOrString, properties:PhysicsHingeJoint):Void

@:native("set_joint_properties")staticset_joint_properties(collisionobject:HashOrStringOrUrl, jointId:HashOrString, properties:PhysicsSliderJoint):Void

@:native("set_joint_properties")staticset_joint_properties(collisionobject:HashOrStringOrUrl, jointId:HashOrString, properties:PhysicsSpringJoint):Void

  • 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

collision object where the joint exist

jointId

id of the joint

properties

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

@:native("set_maskbit")staticsetMaskbit(url:HashOrStringOrUrl, group:String, maskbit:Bool):Void

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

Parameters:

url

the collision object to change the mask of

group

the name of the group (maskbit) to modify in the mask

maskbit

boolean value of the new maskbit. true to enable, false to disable

staticinlinesetShape(url:HashOrString, shapeName:HashOrString, shape:PhysicsShape):Void

  • Gets collision shape data from a collision object

Parameters:

url

the collision object

shapeName

the name of the shape to get data for

shape

the physics shape

@:native("set_vflip")staticsetVflip(url:HashOrStringOrUrl, flip:Bool):Void

  • Flips the collision shapes vertically for a collision object

Parameters:

url

the collision object that should flip its shapes

flip

true if the collision object should flip its shapes, false if not

@:native("update_mass")staticupdateMass(collisionobject:HashOrStringOrUrl, mass:Float):Void

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

collisionobject

the collision object whose mass needs to be updated

mass

the new mass value to set for the collision object

staticwakeup(url:HashOrStringOrUrl):Void

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

Parameters:

url

the collision object that should wake up