Skip to content

PhysicsShape

Extends EngineObject.

A collision shape: an immutable thing a body (or another shape) is made of, in the body's local space. Made with the static functions, given to BodyDesc.Shape, and shared freely: many bodies can use one. Jolt counts references, so a shape that a script lets go of lives on in the bodies that use it.

Properties

  • kind: string What it is: box, sphere, capsule, cylinder, convex_hull, mesh, height_field, compound, offset or scaled. Read-only.
  • volume: number The volume in cubic meters, which with the density gives a dynamic body its mass. Read-only.
  • center_of_mass: Vector3 The shape's center of mass, in its local space. Read-only.

Methods

is_valid_scale

function is_valid_scale(self, scale: Vector3): boolean

Whether the shape can be scaled by this much (a sphere only evenly, a mesh by anything).

Functions

box

PhysicsShape.box: (halfExtents: Vector3, convexRadius: number?) -> PhysicsShape

A box of these half extents, centered on the origin. The edges are rounded by convexRadius (Jolt's default, 5 cm, is shrunk for small boxes).

sphere

PhysicsShape.sphere: (radius: number) -> PhysicsShape

capsule

PhysicsShape.capsule: (halfHeight: number, radius: number) -> PhysicsShape

A capsule along Y: a cylinder of halfHeight (without the caps) with a hemisphere of radius on each end.

cylinder

PhysicsShape.cylinder: (halfHeight: number, radius: number) -> PhysicsShape

A cylinder along Y (wheels, barrels, posts).

convex_hull

PhysicsShape.convex_hull: (points: { Vector3 }) -> PhysicsShape

The convex hull of these points (at least four, not in one plane).

mesh

PhysicsShape.mesh: (vertices: { Vector3 }, indices: { number }) -> PhysicsShape

A static triangle mesh (terrain, buildings): indices are three per triangle. Meshes are only for static and kinematic bodies.

height_field

PhysicsShape.height_field: (heights: { number }, size: number, offset: Vector3, scale: Vector3) -> PhysicsShape

A grid of heights (terrain): heights is size by size samples row by row (a power of two plus one works best, at least 2), at offset from the origin with the grid spaced by scale in x and z and heights multiplied by its y. A height of at least 1e30 is a hole.

compound

PhysicsShape.compound: (children: { PhysicsShape }, positions: { Vector3 }, rotations: { Quat }) -> PhysicsShape

Several shapes at fixed places in one: the child i at positions[i] turned by rotations[i] (identity when the list is shorter).

offset

PhysicsShape.offset: (shape: PhysicsShape, position: Vector3, rotation: Quat) -> PhysicsShape

The shape moved and turned inside its own space, which moves the body's origin relative to it (a box standing on the origin instead of centered on it).

scaled

PhysicsShape.scaled: (shape: PhysicsShape, scale: Vector3) -> PhysicsShape

The shape stretched by scale; fails when the shape cannot be scaled so (IsValidScale).