Skip to content

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.

GestureMouseTouch
Rotatedragone finger
Panright-drag, middle-drag, Shift/Ctrl/Cmd-dragtwo fingers
Zoomwheelpinch

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:

Drag, zoom, click a tower
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 started

focus() 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 ​

OptionDefaultMeaning
viewfirst viewView whose camera the rig moves.
inputengine.plugin(Input)Input to read pointers from.
targetoriginPoint to orbit.
paddingnoneArea covered by UI, in CSS pixels per side.
enableRotate, enablePan, enableZoomtrueWhich gestures move the camera.
minDistance, maxDistance0, InfinityDistance limits (perspective).
minZoom, maxZoom0, Infinitycamera.zoom limits (orthographic).
minPolarAngle, maxPolarAngle0, πAngle from straight above, in radians.
halfLife0.06Half-life of moves, in seconds.
rotateSpeed, panSpeed, zoomSpeed1Gesture 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 spot

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

Tap to shake
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
;
}
OptionDefaultMeaning
viewfirst viewView whose camera it moves.
targetnoneEntity 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.
halfLife0.06Seconds to cover half the way to its spot; 0 keeps it there.
lean0.5How 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.
fovcamera'sField of view in degrees to ease toward.
fovHalfLife0.25Seconds 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.