Three.js Blocks

Home
Documentation
Examples
Tools

PlatformerCamera

@three-blocks/proPhysicsCamera2DPlatformerOrthographicWebGPUWebGL
new PlatformerCamera(physics : Object, options : Object)
Extends
OrthographicPhysicsCamera

PlatformerCamera - Flexible 2D camera for platformer games

A highly configurable camera designed for 2D platformer games. Supports multiple follow modes per axis for different game styles.

Follow Modes:

  • FollowMode.FOLLOW - Smooth follow with velocity-based lookahead
  • FollowMode.DEADZONE - Only move when target exits the deadzone
  • FollowMode.LOCKED - Fixed position on that axis

Screen Anchor: Use anchor to position where the target rests on screen (0-1 normalized).

  • (0.5, 0.5) = center (default)
  • (0.25, 0.5) = 25% from left edge (Mario-style)
  • (0.5, 0.75) = 75% from bottom (vertical climber)

Mario-Style Features:

  • anchor: (0.25, 0.5) - Target on left side of screen
  • lockBackward: true - Camera only scrolls right, never backward
  • edgeEvents: { left: true } - Dispatch events when target hits viewport edge

Use Cases:

  • Side-scroller (Mario): followModeX: DEADZONE, anchor: (0.25, 0.5), lockBackward: true
  • Vertical climber: followModeY: FOLLOW, anchor: (0.5, 0.25)
  • Top-down: followModeX: FOLLOW, followModeY: FOLLOW
  • Single-screen: followModeX: LOCKED, followModeY: LOCKED
Constructor Parameters
physicsObject
Physics instance
optionsoptionalObject
Camera options
Default is {}.
  • targetoptionalTHREE.Object3D
    Target object to follow
  • zoomoptionalnumber
    Visible area half-height in world units
    Default is 10.
  • anchoroptionalTHREE.Vector2
    Screen anchor position (0-1). Where target rests on screen. Default: (0.5, 0.5) = center
  • followModeXoptionalstring
    X-axis follow mode: FollowMode.FOLLOW, DEADZONE, or LOCKED
    Default is 'follow'.
  • followModeYoptionalstring
    Y-axis follow mode: FollowMode.FOLLOW, DEADZONE, or LOCKED
    Default is 'deadzone'.
  • offsetoptionalTHREE.Vector3
    Offset from target position in world units
  • deadzoneoptionalTHREE.Vector2
    Deadzone half-sizes in world units (default: 2, 1.5)
  • lookaheadoptionalTHREE.Vector2
    Velocity-based lookahead offsets (default: 3, 0)
  • lookaheadSpeedoptionalnumber
    Lookahead transition speed
    Default is 3.
  • boundsoptionalTHREE.Box2
    Camera bounds (level edges)
  • dampingoptionalnumber
    Camera movement smoothing factor
    Default is 3.
  • distanceoptionalnumber
    Camera Z position (distance from XY plane)
    Default is 50.
  • nearoptionalnumber
    Near clipping plane
    Default is 0.1.
  • faroptionalnumber
    Far clipping plane
    Default is 1000.
  • lockBackwardoptionalboolean
    Camera only scrolls forward (positive X), never backward
    Default is false.
  • edgeEventsoptionalObject
    Emit 'boundaryHit' events when target exceeds viewport edges
  • edgeEvents.leftoptionalboolean
    Emit event when target goes past left edge
    Default is false.
  • edgeEvents.rightoptionalboolean
    Emit event when target goes past right edge
    Default is false.
  • edgeEvents.topoptionalboolean
    Emit event when target goes past top edge
    Default is false.
  • edgeEvents.bottomoptionalboolean
    Emit event when target goes past bottom edge
    Default is false.
Example
import { PlatformerCamera, FollowMode } from '@three-blocks/pro';

// Mario-style side-scroller
const camera = new PlatformerCamera(physics, {
  target: playerMesh,
  zoom: 10,
  anchor: new THREE.Vector2(0.25, 0.5),  // Player on left side
  followModeX: FollowMode.DEADZONE,
  followModeY: FollowMode.DEADZONE,
  deadzone: new THREE.Vector2(1, 2),
  lookahead: new THREE.Vector2(3, 0),
  damping: 5,
  lockBackward: true,
  edgeEvents: { left: true, bottom: true },
});

// Handle player hitting viewport boundary
camera.addEventListener('boundaryHit', (event) => {
  if (event.edge === 'left') {
    playerBody.teleport(new THREE.Vector3(event.bounds.min.x, event.position.y, 0));
  }
});

// In animation loop
camera.update(delta);
renderer.render(scene, camera);

Properties

.anchor : THREE.Vector2

Screen anchor position (0-1 normalized). Defines where the target rests on screen.

  • (0.5, 0.5) = center
  • (0.25, 0.5) = 25% from left (Mario-style)

.followModeX : string

X-axis follow mode.

.followModeY : string

Y-axis follow mode.

.offset : THREE.Vector3

Offset from target position in world units. Use to position camera focus above/below target center.

.deadzone : THREE.Vector2

Deadzone half-sizes in world units. Target can move freely within deadzone without camera movement.

.lookahead : THREE.Vector2

Velocity-based lookahead offsets. Camera looks ahead in the direction of movement.

.lookaheadSpeed : number

Lookahead transition speed. Higher values = faster transition to lookahead position.

.bounds : THREE.Box2|null

Camera bounds (level edges). Camera will not move outside these bounds.

.damping : number

Camera movement smoothing factor. Higher values = faster camera movement.

.distance : number

Camera Z position (distance from XY plane).

.lockBackwardX : boolean

Lock backward scrolling on X axis (Mario-style one-way scrolling). When enabled, camera only scrolls in positive X direction.

.lockBackwardY : boolean

Lock backward scrolling on Y axis. When enabled, camera only scrolls in positive Y direction.

.edgeEvents : Object|null

Edge events configuration. When set, dispatches 'boundaryHit' events when target exceeds viewport edges.

.targetOffset :

.zOffset :

.forwardOnly :

.lockBackward :

.constrainPlayer :

.lookaheadDamping :

Methods

getPlayerBounds#

getPlayerBounds() : THREE.Box2|null

Get the current player-allowed bounds based on camera viewport. Returns the Box2 representing where the player can be without triggering boundary events.

Returns
THREE.Box2 | null — Player bounds in world coordinates, or null if edgeEvents not set

update#

update(delta : number)

Update camera position. Call each frame after physics sync.

Parameters
deltanumber
Time delta in seconds

snapToTarget#

snapToTarget() : this

Immediately snap camera to target position. Use when teleporting the player or resetting the level.

Returns
this — For chaining

setBounds#

setBounds(bounds : THREE.Box2) : this

Set camera bounds.

Parameters
boundsTHREE.Box2
Bounds object
Returns
this — For chaining

clearBounds#

clearBounds() : this

Clear camera bounds.

Returns
this — For chaining