physics

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.

NOTE: Ray casts will ignore collision objects that contain the starting point of the ray. This is a limitation in Box2D.

// How to perform a ray cast asynchronously:
export default defineScript({
  init(self) {
    self.my_groups = [hash("my_group1"), hash("my_group2")];
  },

  update(self, dt) {
    // request ray cast
    physics.raycast_async(my_start, my_end, self.my_groups);
  },

  on_message(self, message_id, message, sender) {
    // check for the response
    if (message_id === hash("ray_cast_response")) {
      // act on the hit
    } else if (message_id === hash("ray_cast_missed")) {
      // act on the miss
    }
  },
});

Parameters

• from: Vector3 — the world position of the start of the ray
• to: Vector3 — the world position of the end of the ray
• groups: Record<string | number, unknown> — a lua table containing the hashed groups for which to test collisions against
• request_id?: number — a number in range [0,255]. It will be sent back in the response for identification, 0 by default

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. NOTE: Ray casts will ignore collision objects that contain the starting point of the ray. This is a limitation in Box2D.

// How to perform a ray cast synchronously:
export default defineScript({
  init(self) {
    self.groups = [hash("world"), hash("enemy")];
  },

  update(self, dt) {
    // request ray cast
    const result = physics.raycast(from, to, self.groups, { all: true });
    if (result !== undefined) {
      // act on the hit (see 'ray_cast_response')
      for (const result of results) {
        handle_result(result);
      }
    }
  },
});

Parameters

• from: Vector3 — the world position of the start of the ray
• to: Vector3 — the world position of the end of the ray
• groups: Record<string | number, unknown> — a lua table containing the hashed groups for which to test collisions against
• options?: Record<string | number, unknown> — a lua table containing options for the raycast.

all boolean Set to true to return all ray cast hits. If false, it will only return the closest hit.

Returns

• result: Record<string | number, unknown> | nil — It returns a list. If missed it returns nil. See ray_cast_response for details on the returned values.

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?: Record<string | number, unknown> — 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.

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

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

Returns

• properties: Record<string | number, unknown> — 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.

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: Record<string | number, unknown> — joint specific properties table Note: The collide_connected field cannot be updated/changed after a connection has been made.

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

Returns

• force: Vector3 — reaction force for the joint

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

Returns

• torque: number — the reaction torque on bodyB in N*m.

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.

export default defineScript({
  init(self) {
    // Set "upside down" gravity for this collection.
    physics.set_gravity(vmath.vector3(0, 10.0, 0));
  },
});

Parameters

• gravity: Vector3 — the new gravity vector

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.

export default defineScript({
  init(self) {
    let gravity = physics.get_gravity();
    // Inverse gravity!
    gravity = -gravity;
    physics.set_gravity(gravity);
  },
});

Returns

• gravity: Vector3 — gravity vector of collection

Flips the collision shapes horizontally for a collision object

export default defineScript({
  init(self) {
    self.fliph = true; // set on some condition
    physics.set_hflip("#collisionobject", self.fliph);
  },
});

Parameters

• url: string | Hash | Url — the collision object that should flip its shapes
• flip: boolean — true if the collision object should flip its shapes, false if not

Flips the collision shapes vertically for a collision object

export default defineScript({
  init(self) {
    self.flipv = true; // set on some condition
    physics.set_vflip("#collisionobject", self.flipv);
  },
});

Parameters

• url: string | Hash | Url — the collision object that should flip its shapes
• flip: boolean — true if the collision object should flip its shapes, false if not

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

Parameters

• url: string | Hash | Url — the collision object to wake.

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

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: string | Hash | Url — the collision object affected.
• group: string — the new group name to be assigned.

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

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

Parameters

• url: string | Hash | Url — the collision object to return the group of.

Returns

• group: Hash — hash value of the group.

local function check_is_enemy() local group = physics.get_group("#collisionobject") return group == hash("enemy") end

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

Parameters

• url: string | Hash | Url — the collision object to change the mask of.
• group: string — the name of the group (maskbit) to modify in the mask.
• maskbit: boolean — boolean value of the new maskbit. 'true' to enable, 'false' to disable.

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

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

Parameters

• url: string | Hash | Url — the collision object to check the mask of.
• group: string — the name of the group to check for.

Returns

• maskbit: boolean — boolean value of the maskbit. 'true' if present, 'false' otherwise.

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

Gets collision shape data from a collision object

Parameters

• url: string | Hash | Url — the collision object.
• shape: string | Hash — the name of the shape to get data for.

Returns

• table: Record<string | number, unknown> — A table containing meta data about the physics shape

type number The shape type. Supported values:

• physics.SHAPE_TYPE_SPHERE

• physics.SHAPE_TYPE_BOX

• physics.SHAPE_TYPE_CAPSULE Only supported for 3D physics

• physics.SHAPE_TYPE_HULL

The returned table contains different fields depending on which type the shape is. If the shape is a sphere:

diameter number the diameter of the sphere shape

If the shape is a box:

dimensions vector3 a vmath.vector3 of the box dimensions

If the shape is a capsule:

diameter number the diameter of the capsule poles height number the height of the capsule

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

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

• url: string | Hash | Url — the collision object.
• shape: string | Hash — the name of the shape to get data for.
• table: Record<string | number, unknown> — the shape data to update the shape with. See physics.get_shape for a detailed description of each field in the data table.

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

Only one physics world event listener can be set at a time.

function physics_world_listener(self, events) {
  for (const event of events) {
    const event_type = event["type"];
    if (event_type === hash("contact_point_event")) {
      pprint(event);
      // {
      //  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),
      //  },
      // }
    } else if (event === hash("collision_event")) {
      pprint(event);
      // {
      //  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]
      //      }
      // }
    } else if (event === hash("trigger_event")) {
      pprint(event);
      // {
      //  enter = true,
      //  b = {
      //      group = hash: [default],
      //      id = hash: [/go2]
      //  },
      //  a = {
      //      group = hash: [default],
      //      id = hash: [/go1]
      //  }
      // },
    } else if (event === hash("ray_cast_response")) {
      pprint(event);
      // {
      //  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]
      // }
    } else if (event === hash("ray_cast_missed")) {
      pprint(event);
      // {
      //  request_id = 0
      // },
    }
  }
}

export default defineScript({
  init(self) {
    physics.set_event_listener(physics_world_listener);
  },
});

Parameters

• callback: function(self, events) | nil — A callback that receives an information about all the physics interactions in this physics world.

self object The calling script event constant The type of event. Can be one of these messages:

• contact_point_event

• collision_event

• trigger_event

• ray_cast_response

• ray_cast_missed

data table The callback value data is a table that contains event-related data. See the documentation for details on the messages.

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.

physics.update_mass("#collisionobject", 14);

Parameters

• collisionobject: string | Hash | Url — the collision object whose mass needs to be updated.
• mass: number — the new mass value to set for the collision object.

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

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

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

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

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

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

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

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

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.

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

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