Skip to content

@pawnjs/physics ​

Not on npm yet

This package comes with a later release of Pawn.

Rapier rigid bodies and colliders as traits, stepped in the fixedUpdate phase with the engine's fixed time step: primitive, mesh and terrain colliders, a character controller, collision events, raycasts and shape casts.

TypeScript

Rapier's types use Symbol.dispose. Unless skipLibCheck is on (the starter turns it on), add "ESNext" (or "ESNext.Disposable") to lib in tsconfig.json.

ts
import { 
Position
,
Rotation
,
Visual
} from "@pawnjs/core";
import {
Collider
,
createPhysics
,
RigidBody
} from "@pawnjs/physics";
// Rapier loads its WASM module asynchronously (once per page). const
physics
= await
createPhysics
({
gravity
: {
x
: 0,
y
: -9.81,
z
: 0 } });
engine
.
use
(
physics
);
// A fixed floor.
engine
.
world
.
spawn
(
Position
,
RigidBody
({
type
: "fixed" }),
Collider
({
shape
: {
type
: "cuboid",
halfExtents
: {
x
: 5,
y
: 0.2,
z
: 5 } } }),
Visual
(
floorMesh
),
); // A bouncing ball. const
ball
=
engine
.
world
.
spawn
(
Position
({
x
: 0,
y
: 5,
z
: 0 }),
Rotation
,
RigidBody
,
Collider
({
shape
: {
type
: "ball",
radius
: 0.5 },
restitution
: 0.6 }),
Visual
(
ballMesh
),
);

RigidBody ​

Fields left out keep their defaults (RigidBody({ type: "fixed" })):

FieldDefaultMeaning
type"dynamic""dynamic", "fixed", "kinematicPosition" or "kinematicVelocity".
linearDamping0
angularDamping0
gravityScale1
ccdfalseContinuous collision detection, for fast and small bodies.
linearVelocity{ x: 0, y: 0, z: 0 }Initial linear velocity.
  • The body starts at the entity's Position and Rotation.
  • Dynamic and kinematic velocity bodies write their pose back to Position and Rotation every fixed step.
  • Kinematic position bodies follow Position and Rotation; move them by writing those traits.
  • Setting Position or Rotation of any other body, by hand, with a tween, another system or engine.restore(), moves the body there at the start of the next fixed step, or sooner when you call getBody() or raycast().
  • Setting RigidBody (e.g. entity.set(RigidBody, { type: "fixed" })) applies it to the existing body; linearVelocity then sets the body's velocity.
  • Bodies work in world space: put them on root entities, not on ChildOf children.

Collider ​

A collider has a shape (default: a ball of radius 0.5) and material fields, e.g. Collider({ shape: { type: "ball", radius: 1 }, restitution: 0.6 }):

ShapeFields
ballradius
cuboidhalfExtents: { x, y, z }
capsulehalfHeight, radius
cylinderhalfHeight, radius
trimeshvertices, indices: a triangle mesh (see Level geometry)
heightfieldrows, columns, heights, size: { x, z }: a grid of heights (see Level geometry)
Material fieldDefaultMeaning
density1
friction0.5
restitution0Bounciness.
sensorfalseSensors detect overlaps without producing contact forces.

A Collider attaches to the entity's RigidBody. On an entity without one, it is a fixed collider at the entity's Position and Rotation, and moves when they change, the same way as a body. Setting Collider rebuilds the collider with the new shape and material.

Level geometry ​

A level modelled in three.js or a 3D tool (a skatepark, a building) collides as a trimesh, and terrain as a heightfield. Both are meant for fixed colliders (an entity without a RigidBody, or a fixed one) and kinematic bodies: they are hollow surfaces, so dynamic bodies collide with them but not with each other's meshes.

trimeshFromObject(object) makes a trimesh shape from the meshes of a three.js object, such as a Visual or a loaded glTF scene. It keeps the transforms between each mesh and object, in object's own space, so give the collider entity the pose the object has (here both sit on the same entity):

ts
import { 
Position
,
Visual
} from "@pawnjs/core";
import {
Collider
,
trimeshFromObject
} from "@pawnjs/physics";
engine
.
world
.
spawn
(
Position
,
Collider
({
shape
:
trimeshFromObject
(
park
) }),
Visual
(
park
),
);

Hidden objects, instanced and batched meshes, points and lines are left out; a geometry's drawRange is kept. A trimesh can also be written by hand, three numbers per vertex and three indices per triangle: { type: "trimesh", vertices: [x0, y0, z0, x1, ...], indices: [0, 1, 2, ...] }.

A heightfield is a grid of rows by columns heights (at least 2 each), centered on the entity and spanning size.x by size.z meters. Rows run from -z to +z and columns from -x to +x: the height at row, column is heights[row * columns + column], in meters. It matches the vertices of a three.js PlaneGeometry(size.x, size.z, columns - 1, rows - 1) rotated flat with rotateX(-Math.PI / 2):

ts
import { 
Position
,
Visual
} from "@pawnjs/core";
import {
Collider
} from "@pawnjs/physics";
import {
Mesh
,
MeshStandardMaterial
,
PlaneGeometry
} from "three";
const
rows
= 33;
const
columns
= 33;
const
heights
: number[] = [];
for (let
row
= 0;
row
<
rows
;
row
++) {
for (let
column
= 0;
column
<
columns
;
column
++) {
heights
.
push
(
Math
.
sin
(
column
* 0.4) *
Math
.
cos
(
row
* 0.3));
} } const
plane
= new
PlaneGeometry
(40, 40,
columns
- 1,
rows
- 1);
plane
.
rotateX
(-
Math
.
PI
/ 2);
heights
.
forEach
((
h
,
i
) => {
plane
.
attributes
.
position
?.
setY
(
i
,
h
);
});
plane
.
computeVertexNormals
();
engine
.
world
.
spawn
(
Position
,
Collider
({
shape
: {
type
: "heightfield",
rows
,
columns
,
heights
,
size
: {
x
: 40,
z
: 40 } },
}),
Visual
(new
Mesh
(
plane
, new
MeshStandardMaterial
())),
);

Both shapes smooth contacts across the edges between their triangles, so balls roll and characters walk over them without catching. Their numbers are trait data, so snapshots save every vertex and height. A trimesh without triangles or with an index that is not one of its vertices, or a heightfield whose heights is not rows * columns long, makes no collider: the entity keeps its Collider and a warning names the problem.

Character controller ​

A character walked by a player (or by a game's AI) is moved by code, not by forces, but still has to stop at walls and stand on the ground. CharacterController makes an entity's collider one that physics.moveCharacter(entity, translation) moves by a wanted translation: it slides along walls, climbs steps, follows the ground down steps and slopes, and reports whether the character stands on the ground.

WASD or arrow keys to walk

Give the character a kinematicPosition RigidBody (or no body) and a collider, usually a capsule, and move it from a fixedUpdate system that runs before the physics step:

ts
const 
hero
=
engine
.
world
.
spawn
(
Position
({
y
: 1 }),
RigidBody
({
type
: "kinematicPosition" }),
Collider
({
shape
: {
type
: "capsule",
halfHeight
: 0.5,
radius
: 0.4 } }),
CharacterController
({
maxStepHeight
: 0.3 }),
); let
fall
= 0; // vertical speed, m/s
let
grounded
= false;
engine
.
addSystem
(
({
delta
}) => {
const
x
= +
keys
.
isDown
("KeyD") - +
keys
.
isDown
("KeyA");
const
z
= +
keys
.
isDown
("KeyS") - +
keys
.
isDown
("KeyW");
fall
-= 9.81 *
delta
;
if (
keys
.
isDown
("Space") &&
grounded
)
fall
= 5;
const
move
=
physics
.
moveCharacter
(
hero
, {
x
:
x
* 4 *
delta
,
y
:
fall
*
delta
,
z
:
z
* 4 *
delta
,
});
grounded
=
move
.
grounded
;
// Standing: stop falling, or gravity keeps pressing into the ground. if (
move
.
grounded
&&
fall
< 0)
fall
= 0;
}, {
phase
: "fixedUpdate",
order
:
Physics
.
ORDER
- 1 },
);

moveCharacter() adds what the character could move to its Position; its kinematic body glides there in the physics step. Other bodies, dynamic ones too, block it like walls. It returns { translation, grounded, groundNormal }:

FieldMeaning
translationWhat it moved, a three.js Vector3: the wanted translation after walls and steps.
groundedWhether it stands on ground no steeper than maxSlopeClimbAngle.
groundNormalUp normal of that ground, e.g. to tilt a board along a ramp; zero when not grounded. A character that touched no ground while moving (standing still) probes below itself for it.

CharacterController fields (set them like any trait; the controller follows):

FieldDefaultMeaning
offset0.02Gap in meters kept between the character and what it touches.
maxStepHeight0.3Highest step in meters it climbs (0 climbs none).
minStepWidth0.2Narrowest step top it climbs onto, so it does not climb thin edges.
snapToGround0.3Drop in meters it follows down to the ground instead of leaving it, down steps and slopes (0 for none).
maxSlopeClimbAngleMath.PI / 4Steepest slope it walks up, in radians.
minSlopeSlideAngleMath.PI / 4Slopes at least this steep slide it down.
  • The world's up is +y. Sensors do not block the character.
  • While it rises (y above 0) it does not snap to the ground, so a jump keeps its height.
  • The horizontal part of the translation moves first, climbing steps, then the vertical part (a fall or a jump) from where that ended.
  • Like raycast(), it sees colliders as of the last physics step.
  • It throws for an entity without a CharacterController, a Collider or a Position, for a body that is not kinematicPosition, and for a translation that is not finite.

Snapshots ​

Physics registers RigidBody, Collider and CharacterController in engine.traits when it is installed, as rigid-body, collider and character-controller, so snapshots save them. Restore into an engine with a Physics installed: the bodies and colliders are made as the traits are added. Restoring into the same engine puts existing bodies back at their saved pose, with the saved RigidBody and Collider. Fields are checked like other traits (type must be one of the four body types, damping and material at least 0); linearVelocity and the collider shape are only checked for being set.

Collision events ​

After each physics step, collisionstart and collisionend are emitted on both entities of a pair through engine.events, and bubble up ChildOf like other entity events:

ts
engine
.
events
.
on
(
ball
, "collisionstart", (
e
) => {
if (
e
.
other
===
goal
)
score
+= 1;
});
FieldMeaning
otherThe other entity. On collisionend it may already be destroyed.
sensorWhether either collider is a sensor: an overlap, not a contact.
  • Listeners run in fixedUpdate, after the bodies' poses are written back, so Position and Rotation are current.
  • Destroying an entity or removing its Collider ends its collisions; the other entity gets collisionend on the next step.
  • A sensor is a Collider with sensor: true: a trigger zone that reports what enters and leaves it without pushing back.
  • Solid colliders report pairs where at least one body is dynamic; two fixed or kinematic colliders never collide. Sensors also report kinematic and fixed bodies, so a kinematic character can walk into a trigger zone.
  • A collider that is re-created in place (a RigidBody added to an entity that already has a Collider) keeps its contacts without an end and a new start.

Raycast ​

physics.raycast(origin, direction, options?) returns the first collider a ray hits, or null:

ts
const 
hit
=
physics
.
raycast
(
player
.
get
(
Position
)!, {
x
: 0,
y
: -1,
z
: 0 }, {
maxDistance
: 1.2,
exclude
:
player
,
}); const
grounded
=
hit
!== null;
OptionDefaultMeaning
maxDistancePhysics.DEFAULT_MAX_DISTANCE (1000)Longest distance in meters.
includeSensorsfalseWhether sensors can be hit.
excludeAn entity whose body and collider the ray ignores.
solidtrueWhether a ray starting inside a collider hits it at distance 0 (with a zero normal).

A hit is { entity, point, normal, distance }, with point and normal as three.js Vector3 in world space. direction need not be normalized. Raycasts see colliders as of the last physics step: a collider added since is hit after the next step. For picking under the pointer, use the engine's picking (Views and picking); it works on what is drawn, not on colliders.

Shape cast ​

physics.castShape(shape, origin, direction, options?) moves a shape, as a Collider takes it, along a direction and returns the first collider it touches, or null. It is a raycast with thickness: a probe as wide as a character's feet finds a ledge a ray down its middle misses.

ts
const 
below
=
physics
.
castShape
(
{
type
: "ball",
radius
: 0.3 },
feet
,
{
x
: 0,
y
: -1,
z
: 0 },
{
maxDistance
: 1,
exclude
:
player
},
);

The options are rotation (a quaternion, of the shape), maxDistance, includeSensors and exclude, as for raycast(). The hit has the same fields, with point and normal on the collider hit, and distance how far the shape moved before touching it.

Rapier access ​

For queries, joints, forces and anything else Rapier offers, use the underlying objects:

ts
physics
.
rapierWorld
; // RAPIER.World
physics
.
getBody
(
ball
); // RAPIER.RigidBody | undefined
physics
.
getCollider
(
ball
); // RAPIER.Collider | undefined
physics
.
getBody
(
ball
)?.
applyImpulse
({
x
: 0,
y
: 5,
z
: 0 }, true);

A physics plugin can be installed on one engine; engine.dispose() frees its Rapier world. Create a new one with createPhysics() for another engine.