@hoard-engine/camera

Renderer-independent camera follow smoothing and 2D viewport coordinate transforms. A dependency-free leaf of the HOARD engine — no game policy, projection, renderer or browser lifecycle.

Pluggable, interoperable, standalone

HOARD engine packages share the same design goals:

• Pluggable. Adopt a package on its own, or swap it out, without touching the rest of the engine — there is no central engine object to install and no package that owns the others.
• Interoperable. Packages compose with each other and with consumer code through data: minimal shapes, callback seams and plain values — never through shared state or a common framework.
• As standalone as possible. Each package is usable as-is in any project, HOARD-based or not; the leaf packages carry no dependencies and import no siblings.

This package meets all three by construction.

Install

npm install @hoard-engine/camera

Requires Node 18+ (ESM only).

Usage

import {
  screenToWorld,
  updateCamera,
  worldToScreen,
} from '@hoard-engine/camera';

const target = { x: 100, y: 50 }; // supplied by the consumer's world state
const dtMs = 16; // supplied by the consumer's frame driver
const camera = updateCamera({ x: 0, y: 0 }, target.x, target.y, 8, dtMs);
const view = {
  width: 800,
  height: 600,
  centerX: camera.x,
  centerY: camera.y,
  panX: 0,
  panY: 0,
};
const screen = worldToScreen({ x: 120, y: 80 }, view);
const world = screenToWorld(screen, view);

The package never asks for world state, a framework or asset paths. Consumers inject the follow target, elapsed time, viewport dimensions, camera center and pan offset; projection, zoom, bounds, rendering and resize policy stay with the consumer.

API

| Export | Description | | --------------- | ----------------------------------------------------------------- | | createCamera | Creates a plain camera position | | updateCamera | Smoothly follows a target using elapsed milliseconds | | worldToScreen | Maps a world point through a centered, optionally panned viewport | | screenToWorld | Maps a screen point back through the same viewport | | Camera | Plain x/y camera position | | CameraPoint | Plain x/y coordinate | | CameraView | Viewport size, world center and pan offset |

Design notes

• Smoothing is exponential and frame-rate independent; time is in milliseconds and lag is expressed per second.
• View transforms are inverse pairs, with optional pan expressed in screen coordinate units.
• The package does not define scaling, zoom, rotation, dead zones, projection, bounds or a render loop; consumers retain those policies.
• All APIs use plain values and have no browser or renderer dependency.

Development

npm test          # vitest
npm run check     # tsc --noEmit
npm run lint      # eslint over src
npm run prettier  # prettier --check (fix via prettier:format)
npm run build     # tsc declarations + esbuild ESM bundle to dist/
npm publish       # prepublishOnly runs check + build + test first