miaoda-game-camera2d-core

Use this engine-independent policy for 2D camera follow, dead zones, look-ahead, smoothing, world bounds, axis locks, and serializable camera state. It returns a camera center; your engine owns the camera object, zoom, rendering, and temporary shake.

Install

pnpm add miaoda-game-camera2d-core

Follow a target

import { Camera2D } from 'miaoda-game-camera2d-core';

const camera = new Camera2D({
  viewport: { x: 800, y: 450 }, // visible world units
  deadZone: { x: 80, y: 30 },
  lookAhead: { x: 120, y: 0 },
  followSpeed: 900, // 0 snaps; larger values smooth faster
  bounds: { minX: 0, minY: 0, maxX: 3200, maxY: 900 },
});

const frame = camera.step(1 / 60, { x: player.x, y: player.y }, player.velocity);
engineCamera.setCenter(frame.position.x, frame.position.y);

viewport is the visible size in world units, and position is its center. Bounds constrain viewport edges, so the allowed center range is inset by half the viewport. If the viewport is larger than a bound on one axis, that axis is centered inside the bound.

deadZone keeps the target inside a rectangle before the camera moves. lookAhead adds a signed offset based on target velocity. lockX and lockY keep an axis at its current camera position.

Saving and composition

const saved = camera.snapshot;
camera.restore(saved);

Snapshots contain camera position and target only. Restore with the same camera policy and current viewport/bounds. Keep camera shake and cinematic offsets outside authoritative follow state; compose juice effects at the engine layer.

Public API

Camera2D, Camera2DConfig, Camera2DFrame, Camera2DSnapshot, CameraBounds, and Vec2 are exported. The core does not read input, move a player, render, or own an engine camera node.