Appearance
Camera rig
CameraRig is a plugin that lets people move the camera: drag to rotate around a target, right-drag or Shift-drag to pan, wheel or pinch to zoom. It reads pointers through Input and works with perspective and orthographic cameras.
ts
import { CameraRig } from "@pawnjs/core";
const rig = new CameraRig({
target: { y: 1 },
maxPolarAngle: 1.4, // stay above the ground
});
engine.use(rig);The rig takes the camera's position at the first frame and orbits the target from there. It moves the camera of the engine's first view, or of view when given.
| Gesture | Mouse | Touch |
|---|---|---|
| Rotate | drag | one finger |
| Pan | right-drag, middle-drag, Shift/Ctrl/Cmd-drag | two fingers |
| Zoom | wheel | pinch |
A perspective camera zooms by moving closer to the target; an orthographic camera by changing camera.zoom. Moves are damped (halfLife is the half-life in seconds, 0 turns it off) and keep going while the engine's timeScale is 0.
On touch screens the canvas needs a touch-action that leaves the gestures to the page: none gives the rig every gesture, pan-y keeps vertical scrolling of the page and gives the rig horizontal drags and pinching.
Drag to orbit, wheel or pinch to zoom, and click a tower to focus it:
ts
import {
CameraRig,
Clickable,
Engine,
Hoverable,
Position,
Scale,
Shape,
View,
} from "@pawnjs/core";
import { AmbientLight, DirectionalLight, PerspectiveCamera } from "three";
export default function camera(canvas: HTMLCanvasElement): Engine {
// `pan-y` keeps the page scrolling on touch and gives the rig the rest.
canvas.style.cssText =
"display:block;width:100%;height:100%;touch-action:pan-y";
const engine = new Engine({ canvas, seed: 3 });
const { world, random } = engine;
engine.scene.add(new AmbientLight(0xffffff, 0.6));
const sun = new DirectionalLight(0xffffff, 2);
sun.position.set(6, 10, 4);
engine.scene.add(sun);
const view = new PerspectiveCamera(45, 1, 0.1, 200);
view.position.set(8, 8, 10);
engine.views.add(new View({ camera: view, background: 0x09090b }));
const rig = new CameraRig({ maxPolarAngle: 1.35, maxDistance: 30 });
engine.use(rig);
world.spawn(
Shape({ kind: "plane", color: "#27272a" }),
Scale({ x: 12, y: 1, z: 12 }),
);
// A small town of towers; click one to fly to it.
for (let i = 0; i < 25; i++) {
const height = random.range(0.5, 3);
const tower = world.spawn(
Shape({ kind: "box", color: "#e2e8f0" }),
Position({
x: (i % 5) * 2 - 4,
y: height / 2,
z: Math.floor(i / 5) * 2 - 4,
}),
Scale({ x: 1, y: height, z: 1 }),
Hoverable({ tint: "#6366f1", amount: 0.7 }),
Clickable,
);
engine.events.on(tower, "click", () => rig.focus(tower, { distance: 6 }));
}
engine.fitToElement(canvas);
engine.start();
return engine;
}Moving the camera from code
ts
rig.focus(entity); // target the entity's position
rig.focus({ x: 0, y: 0, z: 0 }, { zoom: 2, immediate: true });
rig.follow(player, { y: 1 }); // keep the target on a moving entity
rig.fit(new Box3(min, max), { margin: 16 }); // frame the bounds
rig.reset(); // back to where the rig startedfocus() and fit() ease in with the rig's halfLife unless immediate: true. fit() keeps the current direction and changes the target and the zoom (orthographic) or distance (perspective). Panning stops follow(); rotating and zooming keep it.
Panels over the scene
When UI covers part of the canvas, tell the rig how much, in CSS pixels:
ts
rig.padding = { right: 320, top: 80 };
rig.fit(bounds);The target is then centered in the uncovered area (the projection is shifted with setViewOffset), and fit() fits the bounds into that area.
Clicks after a drag
The browser sends click when a drag ends, including one that rotates the camera. Pointer clicks only when the gesture was no drag, so selecting on its clicks never fights the rig:
ts
engine.plugin(Pointer).on("click", ({ entity }) => select(entity));A gesture that a Pointer press listener captured, such as dragging an entity with the Draggable behavior, does not move the camera.
Options
| Option | Default | Meaning |
|---|---|---|
view | first view | View whose camera the rig moves. |
input | engine.plugin(Input) | Input to read pointers from. |
target | origin | Point to orbit. |
padding | none | Area covered by UI, in CSS pixels per side. |
enableRotate, enablePan, enableZoom | true | Which gestures move the camera. |
minDistance, maxDistance | 0, Infinity | Distance limits (perspective). |
minZoom, maxZoom | 0, Infinity | camera.zoom limits (orthographic). |
minPolarAngle, maxPolarAngle | 0, π | Angle from straight above, in radians. |
halfLife | 0.06 | Half-life of moves, in seconds. |
rotateSpeed, panSpeed, zoomSpeed | 1 | Gesture multipliers. |
All options except view, input and target are also properties that can be changed later; rig.enabled = false ignores input but keeps focus(), follow() and fit() working.
The Energy flow and CMS Health examples use the rig with an orthographic camera and panels over the scene.
Chase camera
ChaseCamera is a plugin for games: it sits behind an entity, in the entity's own space, so it swings round with it in turns, and looks at a point ahead of it. It trails the entity by a half-life, rolls part of the way with it, eases its field of view and shakes on demand.
ts
const chase = new ChaseCamera({
target: ship,
offset: { y: 3, z: 10 }, // behind and above a model whose nose is -z
lookAt: { z: -9 }, // ahead of it
lean: 0.5, // roll half as far as the ship
});
engine.use(chase);
chase.fov = boosting ? 76 : 64; // eases there
chase.shake({ strength: 0.4 }); // on a hit
chase.follow(null); // hand the camera to another one
chase.follow(ship); // and take it back: cuts to the spotIt moves the camera of the engine's first view, or of view, after the game's systems have moved the target each frame. It runs on game time, so a paused engine holds the camera and its shake still. shake() takes a strength in meters (default 0.3) and a duration in seconds (default 0.4); a weaker shake during a stronger one changes nothing. cut() jumps to the spot on the next frame instead of easing there, as after a teleport. When the target is destroyed, the camera stays where it was.
Tap to shake the camera:
ts
import {
ChaseCamera,
Engine,
Position,
Rotation,
Scale,
Shape,
View,
} from "@pawnjs/core";
import {
AmbientLight,
DirectionalLight,
Matrix4,
PerspectiveCamera,
Quaternion,
Vector3,
} from "three";
export default function chase(canvas: HTMLCanvasElement): Engine {
canvas.style.cssText = "display:block;width:100%;height:100%";
const engine = new Engine({ canvas, seed: 5 });
const { world, random } = engine;
engine.scene.add(new AmbientLight(0xffffff, 0.6));
const sun = new DirectionalLight(0xffffff, 2);
sun.position.set(6, 10, 4);
engine.scene.add(sun);
const camera = new PerspectiveCamera(60, 1, 0.1, 300);
engine.views.add(new View({ camera, background: 0x09090b }));
world.spawn(
Shape({ kind: "plane", color: "#27272a" }),
Scale({ x: 80, y: 1, z: 80 }),
);
// Towers inside and outside the ring the dart flies.
for (let i = 0; i < 60; i++) {
const angle = random.range(0, Math.PI * 2);
const radius = i % 2 ? random.range(4, 10) : random.range(18, 30);
const height = random.range(1, 6);
world.spawn(
Shape({ kind: "box", color: "#e2e8f0" }),
Position({
x: Math.cos(angle) * radius,
y: height / 2,
z: Math.sin(angle) * radius,
}),
Scale({ x: 1.5, y: height, z: 1.5 }),
);
}
const dart = world.spawn(
Shape({ kind: "box", color: "#6366f1" }),
Position,
Rotation,
Scale({ x: 0.8, y: 0.3, z: 2 }),
);
// Behind and above the dart, looking ahead of it, rolling with it.
const chase = new ChaseCamera({
target: dart,
offset: { y: 1.5, z: 5 },
lookAt: { y: 0.5, z: -4 },
lean: 0.6,
});
engine.use(chase);
canvas.addEventListener("pointerdown", () => chase.shake({ strength: 0.5 }));
// A wavy right-hand circle, nose first and banked into the turn.
const at = new Vector3();
const ahead = new Vector3();
const up = new Vector3(0, 1, 0);
const back = new Vector3(0, 0, 1);
const basis = new Matrix4();
const turn = new Quaternion();
const bank = new Quaternion().setFromAxisAngle(back, -0.5);
const place = (t: number, out: Vector3) =>
out.set(Math.cos(t) * 14, 2 + Math.sin(t * 3), Math.sin(t) * 14);
engine.addSystem(({ elapsed }) => {
place(elapsed * 0.5, at);
place(elapsed * 0.5 + 0.01, ahead);
turn.setFromRotationMatrix(basis.lookAt(at, ahead, up)).multiply(bank);
dart.set(Position, { x: at.x, y: at.y, z: at.z });
dart.set(Rotation, { x: turn.x, y: turn.y, z: turn.z, w: turn.w });
});
engine.fitToElement(canvas);
engine.start();
return engine;
}| Option | Default | Meaning |
|---|---|---|
view | first view | View whose camera it moves. |
target | none | Entity to chase; or follow(entity) later. |
offset | { x: 0, y: 3, z: 8 } | Where the camera sits, in the target's own space. |
lookAt | { x: 0, y: 1, z: -8 } | Point it looks at, in the target's own space. |
halfLife | 0.06 | Seconds to cover half the way to its spot; 0 keeps it there. |
lean | 0.5 | How far it rolls with the target, 0 (level) to 1. Where a level horizon points nowhere it rolls further: from nothing extra with the target on its side to all of it a third of the way on to upside down, as through a loop, and all the way while it looks almost straight up or down at a target whose up still reaches across the view. |
fov | camera's | Field of view in degrees to ease toward. |
fovHalfLife | 0.25 | Seconds for fov to cover half the way. |
All options except view and target are also properties; offset and lookAt are Vector3s to change in place.