@zakkster/lite-camera-pro 1.0.0

package/llms.txt

@@ -0,0 +1,115 @@
+# @zakkster/lite-camera-pro
+
+> Cinematic Canvas2D camera system for games. Zero-GC in the update/render hot
+> path. Extends @zakkster/lite-camera's CinematicCamera. Adds smooth/eased zoom,
+> 5 follow modes, multi-target auto-framing, an 8-slot noise-based shake engine
+> with presets, fluent timeline sequences, a 16-layer parallax manager, per-edge
+> bounds, a debug HUD, and zero-alloc coordinate conversion.
+
+ESM only. `import` from `@zakkster/lite-camera-pro`. Default export is the
+CinematicCameraPro class. All hot-path APIs avoid allocation; setup-time calls
+(constructor, createSequence, trackMultiple) may allocate.
+
+## Install
+npm install @zakkster/lite-camera-pro
+
+## Core class
+new CinematicCameraPro(viewW, viewH, worldW, worldH, seed = 42)
+
+Game loop (once per frame):
+  cam.update(dt, playerX, playerY, playerVX = 0, playerVY = 0)
+Render:
+  ctx.save(); cam.apply(ctx); drawWorld(ctx); cam.debug(ctx); ctx.restore();
+  cam.debugHUD(ctx);
+- apply(ctx): translates/scales/rotates the canvas to the camera transform (includes shake).
+- debug(ctx): WORLD-space overlay (deadzone, lookahead, world bounds). Call inside the apply transform.
+- debugHUD(ctx): SCREEN-space overlay (position, zoom, mode, per-slot trauma bars, sequence %). Call after restore.
+update() dispatches by priority: active sequence > multi-target > single-target follow mode.
+
+## Follow modes
+cam.setMode(FollowMode.SMOOTH | LOCK | PREDICTIVE | CUT | HYBRID)  // returns this
+- SMOOTH: deadzone + lookahead + lerp (default).
+- LOCK: instant snap, no interpolation.
+- PREDICTIVE: velocity extrapolation; tune cam.predictTime (seconds).
+- CUT: hard jump, zero lerp (cutscene transitions).
+- HYBRID: smooth horizontal, locked vertical; cam.hybridVerticalSnap = true|false.
+
+## Zoom
+cam.setZoom(level, duration = 0, ease = null)            // smooth eased zoom; duration 0 = instant
+cam.zoomAt(x, y, level, duration = 0, ease = null)        // zoom toward a static world point
+cam.zoomAt(targetObj, level, duration = 0, ease = null)   // zoom toward a moving {x,y}; anchor re-read each frame
+cam.minZoom, cam.maxZoom                                  // clamp limits
+cam.visibleW, cam.visibleH                                // cached visible area (viewW/zoom, viewH/zoom); use for culling
+
+## Coordinate conversion (zero-alloc, caller-owned out)
+const pt = { x: 0, y: 0 };          // allocate once
+cam.screenToWorld(sx, sy, pt);      // mutates pt, returns pt
+cam.worldToScreen(wx, wy, pt);      // mutates pt, returns pt
+
+## Multi-target framing
+cam.trackMultiple(targets, { padding, minZoom, maxZoom, zoomSpeed, followSpeed })  // auto-zoom + center on bbox
+cam.trackSingle()                                                                   // back to single-target follow
+cam.setTargetCount(n)                                                               // resize without reallocating
+targets: array of objects with numeric x, y.
+
+## Shake (8 simultaneous slots, summed; simplex-noise driven)
+cam.addTrauma(amount)                       // simple omnidirectional trauma (backward compatible)
+cam.shake(profile, intensity = 1)           // custom: { trauma, freq, decay, maxOffset, maxAngle, dirX, dirY }
+cam.shakePreset(name, intensity = 1)        // named preset
+cam.clearShakes()
+Preset names: 'explosion','earthquake','recoil','impact','landing','damage','rumble','heavy_impact'.
+Registry (named exports): registerPreset(name, profile), listPresets(), getPreset(name).
+Preset constants exported: EXPLOSION, EARTHQUAKE, RECOIL, IMPACT, LANDING, DAMAGE, RUMBLE, HEAVY_IMPACT.
+
+## Sequences (fluent timeline; takes over position + zoom, blends back to follow on completion)
+const seq = cam.createSequence({ onComplete })
+  .moveTo(x, y, durationMs)
+  .zoomTo(level, durationMs)
+  .moveAndZoom(x, y, level, durationMs, { ease })
+  .shake(presetName)
+  .wait(ms)
+  .call(fn);
+cam.playSequence(seq);
+cam.stopSequence();                 // cancel + smooth return to follow
+seq.pause(); seq.resume(); seq.seek(ms);
+Sequence preset helpers (named exports, return a sequence): panTo(cam, x, y, ms),
+dramaticZoom(cam, x, y, level, ms), bossReveal(cam, x, y, ms), timedShake(cam, presetName, ms).
+Read cam.sequencePlaying (boolean).
+
+## Parallax (up to 16 layers)
+cam.addParallaxLayer(id, speedX, speedY = speedX, opts)   // re-adding same id updates it
+cam.removeParallaxLayer(id)
+cam.applyParallax(id, ctx)                                 // per-layer transform; wrap in ctx.save()/restore()
+WrapMode exported for layer wrapping behavior.
+
+## Bounds (per-edge: HARD | SOFT | ELASTIC | NONE)
+import { BoundsType } from '@zakkster/lite-camera-pro';
+cam.setBoundsType(BoundsType.SOFT)                          // returns this
+cam.setBoundsEdges({ left, right, top, bottom })            // each a BoundsType
+cam.setBoundsRect(x, y, w, h)                               // constrain to a rectangle (rooms/arenas)
+cam.clearBoundsRect()                                       // revert to full world
+Tuning: cam._bounds.softZone, cam._bounds.elasticMax, cam._bounds.elasticStrength.
+
+## Save / load
+const snap = cam.getState();   // { posX, posY, targetX, targetY, zoom, mode }
+cam.setState(snap);            // restores and recomputes visible dims
+cam.destroy();                 // releases internal state
+
+## Debug HUD
+cam.debugConfig.show.shake | parallax | bounds | ... = true|false   // toggle panels
+createDebugHUDConfig() exported to build a config; drawDebugWorld(cam, ctx, config) and drawDebugHUD(cam, ctx, config) are the underlying draws (cam.debug / cam.debugHUD wrap them).
+
+## Standalone functional API (tree-shakeable; the class composes these)
+Shake:    createShakeState, addShake, addTraumaSimple, updateShake, computeShake, clearShakes
+Parallax: createParallaxState, addParallaxLayer, removeParallaxLayer, updateParallax, getLayerScroll, applyParallaxLayer
+Bounds:   createBoundsState, setBoundsAll, setBoundsEdges, setBoundsRect, clearBoundsRect, applyBounds
+Multi:    createMultiTargetState, updateMultiTarget
+Sequence: createCameraSequence, panTo, dramaticZoom, bossReveal, timedShake
+Enums:    FollowMode, FOLLOW_STRATEGIES, BoundsType, WrapMode
+
+## Dependencies (all @zakkster, first-party)
+@zakkster/lite-camera (base CinematicCamera), lite-ease, lite-lerp, lite-noise, lite-timeline.
+
+## Notes
+- Migration: CinematicCameraPro is a drop-in superset of lite-camera's CinematicCamera.
+- Zero-GC: coordinate conversion uses caller-owned out objects; visible dims are cached properties (no getVisibleArea()); shake (8) and parallax (16) slots are pre-allocated and reused.

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@zakkster/lite-camera-pro",
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "version": "1.0.0",
+  "description": "Cinematic camera system for Canvas2D games. Zero-GC, multi-target framing, noise-based shake, and timeline sequences.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "node": "./src/index.js",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "llms.txt",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/PeshoVurtoleta/lite-camera-pro#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-camera-pro.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-camera-pro/issues",
+    "email": "shinikchiev@yahoo.com"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@zakkster/lite-camera": "^1.0.0",
+    "@zakkster/lite-ease": "^1.0.0",
+    "@zakkster/lite-lerp": "^1.0.0",
+    "@zakkster/lite-noise": "^1.0.0",
+    "@zakkster/lite-timeline": "^1.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bundle-check": "esbuild ./src/index.js --bundle --format=esm --outfile=test-bundle.js",
+    "prepublishOnly": "npm run test && npm run bundle-check"
+  },
+  "keywords": [
+    "camera",
+    "cinematic",
+    "canvas2d",
+    "zero-gc",
+    "gamedev",
+    "html5",
+    "performance",
+    "screen-shake",
+    "parallax"
+  ]
+}

package/src/BoundsSystem.js

@@ -0,0 +1,220 @@
+/**
+ * @zakkster/lite-camera-pro — Smart Bounds System
+ *
+ * Replaces hard edge clamping with configurable per-edge behavior.
+ *
+ * Boundary types:
+ *   HARD    — stops at edge (default, same as lite-camera base)
+ *   SOFT    — decelerates smoothly near edge using smoothstep
+ *   ELASTIC — allows slight overshoot, springs back
+ *   NONE    — no boundary enforcement
+ *
+ * Zero allocations. All state is pre-allocated on the camera.
+ *
+ * Depends on: @zakkster/lite-lerp (clamp, smoothstep)
+ */
+
+/** @enum {number} */
+export const BoundsType = {
+    HARD:    0,
+    SOFT:    1,
+    ELASTIC: 2,
+    NONE:    3,
+};
+
+/**
+ * Create the bounds system state. Allocated once per camera.
+ * @returns {Object}
+ */
+export function createBoundsState() {
+    return {
+        // Per-edge boundary type
+        left:   BoundsType.HARD,
+        right:  BoundsType.HARD,
+        top:    BoundsType.HARD,
+        bottom: BoundsType.HARD,
+
+        // Soft zone width: how far from edge deceleration starts (pixels)
+        softZone: 80,
+
+        // Elastic overshoot: max pixels past the boundary
+        elasticMax: 30,
+
+        // Elastic spring-back strength (higher = snappier return)
+        elasticStrength: 8.0,
+
+        // Custom world bounds (null = use camera worldW/worldH)
+        boundsX: 0,
+        boundsY: 0,
+        boundsW: 0,
+        boundsH: 0,
+        customBounds: false,
+    };
+}
+
+/**
+ * Set the boundary type for all edges at once.
+ *
+ * @param {Object} state  BoundsState (cam._bounds)
+ * @param {number} type   BoundsType enum
+ */
+export function setBoundsAll(state, type) {
+    state.left = state.right = state.top = state.bottom = type;
+}
+
+/**
+ * Set boundary types per edge.
+ *
+ * @param {Object} state   BoundsState
+ * @param {Object} config
+ * @param {number} [config.left]
+ * @param {number} [config.right]
+ * @param {number} [config.top]
+ * @param {number} [config.bottom]
+ */
+export function setBoundsEdges(state, config) {
+    if (config.left   !== undefined) state.left   = config.left;
+    if (config.right  !== undefined) state.right  = config.right;
+    if (config.top    !== undefined) state.top    = config.top;
+    if (config.bottom !== undefined) state.bottom = config.bottom;
+}
+
+/**
+ * Set a custom bounds rectangle (for dynamic bounds during gameplay).
+ *
+ * @param {Object} state  BoundsState
+ * @param {number} x
+ * @param {number} y
+ * @param {number} w
+ * @param {number} h
+ */
+export function setBoundsRect(state, x, y, w, h) {
+    state.boundsX = x;
+    state.boundsY = y;
+    state.boundsW = w;
+    state.boundsH = h;
+    state.customBounds = true;
+}
+
+/**
+ * Clear custom bounds, reverting to full world size.
+ * @param {Object} state  BoundsState
+ */
+export function clearBoundsRect(state) {
+    state.customBounds = false;
+}
+
+// ── Smoothstep (inlined to avoid import for single use) ──
+function smoothstep(edge0, edge1, x) {
+    const t = x < edge0 ? 0 : (x > edge1 ? 1 : (x - edge0) / (edge1 - edge0));
+    return t * t * (3 - 2 * t);
+}
+
+/**
+ * Apply boundary enforcement to camera target position.
+ * Replaces the simple clamp in camera.update().
+ *
+ * @param {Object} state    BoundsState
+ * @param {Float32Array} target  cam.target (mutated)
+ * @param {Float32Array} pos     cam.pos (mutated for elastic)
+ * @param {number} maxX     Default maximum X (worldW - visibleW)
+ * @param {number} maxY     Default maximum Y (worldH - visibleH)
+ * @param {number} visW     Visible width (viewW / zoom)
+ * @param {number} visH     Visible height (viewH / zoom)
+ * @param {number} dt       Delta time
+ */
+export function applyBounds(state, target, pos, maxX, maxY, visW, visH, dt) {
+    let minBX = 0, maxBX = maxX;
+    let minBY = 0, maxBY = maxY;
+
+    if (state.customBounds) {
+        // Custom bounds define a world-space rectangle.
+        // Camera target is the top-left of the visible area.
+        // Min = bounds origin. Max = bounds origin + bounds size - visible size.
+        minBX = state.boundsX;
+        minBY = state.boundsY;
+        maxBX = state.boundsX + state.boundsW - visW;
+        maxBY = state.boundsY + state.boundsH - visH;
+
+        // If visible area exceeds bounds, center the camera within the bounds
+        if (maxBX < minBX) { const mid = (minBX + maxBX) * 0.5; minBX = maxBX = mid; }
+        if (maxBY < minBY) { const mid = (minBY + maxBY) * 0.5; minBY = maxBY = mid; }
+    }
+
+    const sz = state.softZone;
+    const eMax = state.elasticMax;
+    const eStr = state.elasticStrength;
+
+    _applyEdge(state.left,   target, pos, 0, minBX, true,  sz, eMax, eStr, dt);
+    _applyEdge(state.right,  target, pos, 0, maxBX, false, sz, eMax, eStr, dt);
+    _applyEdge(state.top,    target, pos, 1, minBY, true,  sz, eMax, eStr, dt);
+    _applyEdge(state.bottom, target, pos, 1, maxBY, false, sz, eMax, eStr, dt);
+}
+
+/**
+ * Apply a single edge constraint.
+ *
+ * @param {number} type     BoundsType
+ * @param {Float32Array} target
+ * @param {Float32Array} pos
+ * @param {number} axis     0=X, 1=Y
+ * @param {number} edge     The boundary value
+ * @param {boolean} isMin   true = left/top (target must be >= edge), false = right/bottom (<=)
+ * @param {number} sz       Soft zone width
+ * @param {number} eMax     Elastic max overshoot
+ * @param {number} eStr     Elastic spring strength
+ * @param {number} dt
+ */
+function _applyEdge(type, target, pos, axis, edge, isMin, sz, eMax, eStr, dt) {
+    const val = target[axis];
+
+    switch (type) {
+        case BoundsType.HARD:
+            if (isMin && val < edge) target[axis] = edge;
+            if (!isMin && val > edge) target[axis] = edge;
+            break;
+
+        case BoundsType.SOFT: {
+            // Decelerate smoothly as we approach the edge
+            if (isMin && val < edge + sz) {
+                // How deep into the soft zone (0 = at edge, 1 = at zone boundary)
+                const t = smoothstep(edge, edge + sz, val);
+                // Blend target toward the edge
+                target[axis] = edge + (val - edge) * t;
+                if (target[axis] < edge) target[axis] = edge;
+            }
+            if (!isMin && val > edge - sz) {
+                const t = smoothstep(edge, edge - sz, val);
+                target[axis] = edge + (val - edge) * t;
+                if (target[axis] > edge) target[axis] = edge;
+            }
+            break;
+        }
+
+        case BoundsType.ELASTIC: {
+            // Allow overshoot up to eMax, then spring back
+            if (isMin && val < edge) {
+                const overshoot = edge - val;
+                if (overshoot > eMax) {
+                    target[axis] = edge - eMax;
+                }
+                // Safe, frame-rate independent spring back
+                const springLerp = 1 - Math.exp(-eStr * dt);
+                pos[axis] += (edge - pos[axis]) * springLerp;
+            }
+            if (!isMin && val > edge) {
+                const overshoot = val - edge;
+                if (overshoot > eMax) {
+                    target[axis] = edge + eMax;
+                }
+                const springLerp = 1 - Math.exp(-eStr * dt);
+                pos[axis] += (edge - pos[axis]) * springLerp;
+            }
+            break;
+        }
+
+        case BoundsType.NONE:
+            // No enforcement
+            break;
+    }
+}