@zakkster/lite-camera

🎥 What is lite-camera?

@zakkster/lite-camera is the camera system every 2D game needs but no engine ships standalone.

It gives you:

• 📦 Deadzone (camera only moves when player pushes outside the box)
• 👀 Smoothed lookahead (camera leads in the direction of movement)
• 📳 Deterministic screenshake (trauma-squared, seeded RNG)
• 🎯 World boundary clamping (never shows outside the map)
• 🖼️ Canvas ctx.translate/rotate integration
• 🐛 Debug overlay (deadzone rectangle + crosshair)
• 🪶 < 1 KB minified

Engine-agnostic. Works with Canvas2D, PixiJS, or any transform-based renderer.

Part of the @zakkster/lite-* ecosystem — micro-libraries built for deterministic, cache-friendly game development.

🚀 Install

npm i @zakkster/lite-camera

🕹️ Quick Start

import { CinematicCamera } from '@zakkster/lite-camera';

const cam = new CinematicCamera(800, 600, 2000, 2000);
//                               viewW viewH worldW worldH

function gameLoop(dt) {
    cam.update(dt, player.x, player.y, player.vx, player.vy);

    ctx.save();
    cam.apply(ctx);
    drawWorld();
    cam.debug(ctx); // optional: shows deadzone
    ctx.restore();
}

// Screenshake on explosion
cam.addTrauma(0.6);

🧠 Why This Exists

No standalone 2D camera packages exist on npm. They're always baked into engines (Phaser, PixiJS). lite-camera is the first engine-agnostic cinematic camera with deterministic shake (seeded RNG) and smoothed lookahead.

📊 Comparison

| Library | Size | Standalone | Deadzone | Lookahead | Shake | Install | |---------|------|-----------|----------|-----------|-------|---------| | Phaser Camera | N/A | No (coupled) | Yes | No | Yes | — | | PixiJS Viewport | N/A | No (coupled) | Basic | No | No | — | | lite-camera | < 1 KB | Yes | Yes | Smoothed | Deterministic | npm i @zakkster/lite-camera |

⚙️ API

new CinematicCamera(viewW, viewH, worldW, worldH, seed?)

update(dt, px, py, pvx?, pvy?) — Call every frame with player position/velocity

apply(ctx) — Applies camera transform. Caller must ctx.save() before and ctx.restore() after.

addTrauma(amount) — Adds screenshake intensity (0–1, clamped)

debug(ctx) — Draws deadzone rectangle and target crosshair

🧪 Benchmark

No standalone 2D camera packages exist on npm for comparison.
lite-camera uses Float32Array for all vectors — zero allocation per frame.
Precomputed boundary clamps — no Math.max/Math.min per frame.

📦 TypeScript

Full TypeScript declarations included in CinematicCamera.d.ts.

📚 LLM-Friendly Documentation

See llms.txt for AI-optimized metadata and usage examples.

License

MIT