@zakkster/lite-camera-pro 1.0.0

package/src/ParallaxManager.js

@@ -0,0 +1,199 @@
+/**
+ * @zakkster/lite-camera-pro — Parallax Layer Manager
+ *
+ * Manages multiple scroll layers at different speeds.
+ * Each layer has a scroll multiplier relative to the camera.
+ *
+ *   speed 1.0 = scrolls with camera (normal game layer)
+ *   speed 0.5 = scrolls at half speed (distant background)
+ *   speed 1.5 = scrolls faster (foreground)
+ *   speed 0.0 = fixed (UI, sky)
+ *
+ * Zero allocations per frame. All layer state is pre-allocated.
+ *
+ * Depends on: nothing (pure math)
+ */
+
+// ── Maximum layers ──
+const MAX_LAYERS = 16;
+
+/** Wrap modes for layer tiling */
+export const WrapMode = {
+    NONE:       0,  // no wrapping
+    REPEAT_X:   1,  // tile horizontally
+    REPEAT_Y:   2,  // tile vertically
+    REPEAT_BOTH: 3, // tile both axes
+};
+
+/**
+ * Create a single parallax layer (pre-allocated).
+ * @returns {Object}
+ */
+function createLayer() {
+    return {
+        active:  false,
+        id:      '',
+
+        // Scroll speed multipliers (1.0 = normal camera speed)
+        speedX:  1.0,
+        speedY:  1.0,
+
+        // Manual offset (for fine-tuning layer position)
+        offsetX: 0,
+        offsetY: 0,
+
+        // Wrap mode
+        wrap:    WrapMode.NONE,
+
+        // Computed scroll position (updated each frame)
+        scrollX: 0,
+        scrollY: 0,
+    };
+}
+
+/**
+ * Create the parallax manager state. Allocated once per camera.
+ *
+ * @returns {Object} ParallaxState
+ */
+export function createParallaxState() {
+    const layers = new Array(MAX_LAYERS);
+    for (let i = 0; i < MAX_LAYERS; i++) {
+        layers[i] = createLayer();
+    }
+
+    return {
+        layers,
+        layerCount: MAX_LAYERS,
+        activeCount: 0,
+    };
+}
+
+/**
+ * Add or update a parallax layer.
+ *
+ * @param {Object} state     ParallaxState (cam._parallax)
+ * @param {string} id        Unique layer identifier
+ * @param {number} speedX    Horizontal scroll multiplier
+ * @param {number} [speedY]  Vertical scroll multiplier (defaults to speedX)
+ * @param {Object} [opts]
+ * @param {number} [opts.offsetX=0]  Manual X offset
+ * @param {number} [opts.offsetY=0]  Manual Y offset
+ * @param {number} [opts.wrap=0]     WrapMode enum
+ * @returns {Object} The layer object (for direct mutation if needed)
+ */
+export function addParallaxLayer(state, id, speedX, speedY, opts) {
+    if (speedY === undefined) speedY = speedX;
+
+    // Check if layer already exists
+    for (let i = 0; i < state.layerCount; i++) {
+        if (state.layers[i].active && state.layers[i].id === id) {
+            const layer = state.layers[i];
+            layer.speedX = speedX;
+            layer.speedY = speedY;
+            if (opts) {
+                if (opts.offsetX !== undefined) layer.offsetX = opts.offsetX;
+                if (opts.offsetY !== undefined) layer.offsetY = opts.offsetY;
+                if (opts.wrap !== undefined)    layer.wrap    = opts.wrap;
+            }
+            return layer;
+        }
+    }
+
+    // Find first inactive slot
+    for (let i = 0; i < state.layerCount; i++) {
+        if (!state.layers[i].active) {
+            const layer = state.layers[i];
+            layer.active  = true;
+            layer.id      = id;
+            layer.speedX  = speedX;
+            layer.speedY  = speedY;
+            layer.offsetX = (opts && opts.offsetX) || 0;
+            layer.offsetY = (opts && opts.offsetY) || 0;
+            layer.wrap    = (opts && opts.wrap)    || WrapMode.NONE;
+            layer.scrollX = 0;
+            layer.scrollY = 0;
+            state.activeCount++;
+            return layer;
+        }
+    }
+
+    return null; // all slots full
+}
+
+/**
+ * Remove a parallax layer by id.
+ *
+ * @param {Object} state  ParallaxState
+ * @param {string} id     Layer id
+ */
+export function removeParallaxLayer(state, id) {
+    for (let i = 0; i < state.layerCount; i++) {
+        if (state.layers[i].active && state.layers[i].id === id) {
+            state.layers[i].active = false;
+            state.layers[i].id = '';
+            state.activeCount--;
+            return;
+        }
+    }
+}
+
+/**
+ * Update all layer scroll positions based on camera position and zoom.
+ * Called once per frame from camera.update().
+ *
+ * @param {Object} state  ParallaxState
+ * @param {number} camX   Camera top-left X (cam.pos[0])
+ * @param {number} camY   Camera top-left Y (cam.pos[1])
+ * @param {number} zoom   Camera zoom level
+ */
+export function updateParallax(state, camX, camY, zoom) {
+    for (let i = 0; i < state.layerCount; i++) {
+        const layer = state.layers[i];
+        if (!layer.active) continue;
+
+        // Parallax scroll = camera position × speed multiplier
+        // Zoom scaling: faster layers should scale more with zoom
+        layer.scrollX = camX * layer.speedX * zoom + layer.offsetX;
+        layer.scrollY = camY * layer.speedY * zoom + layer.offsetY;
+    }
+}
+
+/**
+ * Get a layer's scroll offset by id. Zero-alloc via out parameter.
+ *
+ * @param {Object} state  ParallaxState
+ * @param {string} id     Layer id
+ * @param {{x:number,y:number}} out  Pre-allocated output
+ * @returns {{x:number,y:number}|null} out or null if not found
+ */
+export function getLayerScroll(state, id, out) {
+    for (let i = 0; i < state.layerCount; i++) {
+        if (state.layers[i].active && state.layers[i].id === id) {
+            out.x = state.layers[i].scrollX;
+            out.y = state.layers[i].scrollY;
+            return out;
+        }
+    }
+    return null;
+}
+
+/**
+ * Apply a parallax layer's transform to a canvas context.
+ * Call between ctx.save() and ctx.restore() per layer.
+ *
+ * @param {Object} state  ParallaxState
+ * @param {string} id     Layer id
+ * @param {CanvasRenderingContext2D} ctx
+ * @returns {boolean} true if layer was found and applied
+ */
+export function applyParallaxLayer(state, id, ctx) {
+    for (let i = 0; i < state.layerCount; i++) {
+        const layer = state.layers[i];
+        if (layer.active && layer.id === id) {
+            ctx.translate(-(layer.scrollX | 0), -(layer.scrollY | 0));
+            return true;
+        }
+    }
+    return false;
+}

package/src/ShakeEngine.js

@@ -0,0 +1,286 @@
+/**
+ * @zakkster/lite-camera-pro — Noise-Based Shake Engine
+ *
+ * Replaces RNG trauma shake with simplex noise for smooth, organic screen shake.
+ * Supports layered shakes: multiple simultaneous shake sources sum together.
+ *
+ * Zero-GC: Pre-allocated shake slot pool. No allocations in update/compute.
+ *
+ * Depends on: @zakkster/lite-noise (simplex2)
+ */
+
+import {simplex2} from '@zakkster/lite-noise';
+
+// ── Maximum simultaneous shake layers ──
+const MAX_SHAKE_SLOTS = 8;
+
+// ── Unique noise offsets so each slot/axis samples different noise ──
+// Slot i, axis j → noise offset = NOISE_SEED_OFFSET * (i * 3 + j)
+const NOISE_SEED_OFFSET = 1000;
+
+/**
+ * A single shake slot. Pre-allocated, reused via pool.
+ * All fields are primitives — zero GC.
+ */
+function createShakeSlot() {
+    return {
+        active: false,
+
+        // True when slot was created by addTraumaSimple (generic omni shake).
+        // addTrauma only stacks onto isDefault slots — preset/profile slots
+        // have their own freq/decay/maxOffset and shouldn't be polluted with
+        // generic trauma added on top.
+        isDefault: false,
+
+        // ── Trauma model ──
+        trauma: 0,      // Current trauma [0, 1] — decays over time
+        decay: 1.0,    // Trauma units lost per second
+
+        // ── Noise parameters ──
+        freq: 15,     // Noise sample frequency (higher = more jittery)
+        time: 0,      // Accumulated time for noise sampling
+
+        // ── Output amplitude ──
+        maxOffset: 15,     // Maximum pixel offset at trauma=1
+        maxAngle: 0.05,   // Maximum rotation (radians) at trauma=1
+
+        // ── Direction constraint ──
+        // If dirX/dirY are non-zero, shake is constrained to that axis.
+        // (0,0) = omnidirectional, (1,0) = horizontal only, (0,1) = vertical only
+        dirX: 0,
+        dirY: 0,
+        isDirectional: false,
+    };
+}
+
+/**
+ * Shake engine state. Allocated once per camera.
+ * Contains a pool of shake slots and the computed output.
+ *
+ * @param {number} [seedOffset=0]  Per-camera offset added to every noise
+ *                                 sample base. Lets two cameras with different
+ *                                 seeds produce distinct, deterministic shake
+ *                                 patterns without touching the global perm table.
+ */
+export function createShakeState(seedOffset = 0) {
+    const slots = new Array(MAX_SHAKE_SLOTS);
+    for (let i = 0; i < MAX_SHAKE_SLOTS; i++) {
+        slots[i] = createShakeSlot();
+    }
+
+    return {
+        slots,
+        slotCount: MAX_SHAKE_SLOTS,
+
+        // Multiply by a prime so adjacent seeds land far apart in noise space.
+        seedOffset: (seedOffset | 0) * 7919,
+
+        // ── Computed output (read by apply()) ──
+        offsetX: 0,
+        offsetY: 0,
+        angle: 0,
+
+        // ── Global shake scale (0 = no shake, 1 = normal) ──
+        globalScale: 1.0,
+
+        // ── Whether any slot is active (quick check in apply) ──
+        active: false,
+    };
+}
+
+/**
+ * Find the first inactive slot, or the slot with lowest trauma to steal.
+ *
+ * @param {Object} state  ShakeState
+ * @returns {Object} A shake slot
+ */
+function acquireSlot(state) {
+    let minTrauma = Infinity;
+    let minIdx = 0;
+
+    for (let i = 0; i < state.slotCount; i++) {
+        if (!state.slots[i].active) return state.slots[i];
+        if (state.slots[i].trauma < minTrauma) {
+            minTrauma = state.slots[i].trauma;
+            minIdx = i;
+        }
+    }
+
+    // All slots full — steal the weakest
+    return state.slots[minIdx];
+}
+
+// ─────────────────────────────────────────────────────
+//  PUBLIC API
+// ─────────────────────────────────────────────────────
+
+/**
+ * Add a shake impulse. Acquires a slot from the pool and configures it.
+ *
+ * @param {Object} state   ShakeState (cam._shake)
+ * @param {Object} profile Shake profile (from presets or custom)
+ * @param {number} profile.trauma     Initial trauma [0, 1]
+ * @param {number} [profile.freq=15]  Noise frequency
+ * @param {number} [profile.decay=1]  Trauma decay per second
+ * @param {number} [profile.maxOffset=15] Max pixel offset
+ * @param {number} [profile.maxAngle=0.05] Max rotation (radians)
+ * @param {number} [profile.dirX=0]   Directional X component
+ * @param {number} [profile.dirY=0]   Directional Y component
+ * @param {number} [profile.intensity=1] Scale multiplier for the profile
+ */
+export function addShake(state, profile, intensity = 1) {
+    const slot = acquireSlot(state);
+
+    slot.active = true;
+    slot.isDefault = false;
+    slot.trauma = Math.min(1, (profile.trauma || 0.5) * intensity);
+    slot.decay = profile.decay !== undefined ? profile.decay : 1.0;
+    slot.freq = profile.freq !== undefined ? profile.freq : 15;
+    slot.maxOffset = profile.maxOffset !== undefined ? profile.maxOffset : 15;
+    slot.maxAngle = profile.maxAngle !== undefined ? profile.maxAngle : 0.05;
+    slot.time = 0; // reset time for fresh noise sampling
+
+    // Directional
+    const dx = profile.dirX || 0;
+    const dy = profile.dirY || 0;
+    slot.isDirectional = (dx !== 0 || dy !== 0);
+
+    if (slot.isDirectional) {
+        // Normalize direction
+        const len = Math.sqrt(dx * dx + dy * dy);
+        slot.dirX = dx / len;
+        slot.dirY = dy / len;
+    } else {
+        slot.dirX = 0;
+        slot.dirY = 0;
+    }
+
+    state.active = true;
+}
+
+/**
+ * Add simple trauma to the first active slot, or create one with defaults.
+ * Backward-compatible with the original camera.addTrauma(amount) API. Zero-GC.
+ *
+ * @param {Object} state  ShakeState
+ * @param {number} amount Trauma to add [0, 1]
+ */
+export function addTraumaSimple(state, amount) {
+    // Try to find an existing default omni slot to stack onto.
+    // Preset/profile slots are NEVER stacked onto — they have parameters
+    // (freq, decay, etc.) that addTrauma's generic shake wouldn't match.
+    for (let i = 0; i < state.slotCount; i++) {
+        const s = state.slots[i];
+        if (s.active && s.isDefault) {
+            s.trauma = Math.min(1, s.trauma + amount);
+            return;
+        }
+    }
+
+    // No active omni slot — populate one inline. No intermediate object literal
+    // (which would otherwise allocate per call and violate the zero-GC contract).
+    const slot = acquireSlot(state);
+    slot.active = true;
+    slot.isDefault = true;   // explicit profile/preset — not a generic trauma slot
+    slot.trauma = Math.min(1, amount);
+    slot.decay = 1.0;
+    slot.freq = 15;
+    slot.time = 0;
+    slot.maxOffset = 15;
+    slot.maxAngle = 0.05;
+    slot.dirX = 0;
+    slot.dirY = 0;
+    slot.isDirectional = false;
+    state.active = true;
+}
+
+/**
+ * Update all active shake slots: advance time, decay trauma.
+ * Called once per frame from camera.update().
+ *
+ * @param {Object} state ShakeState
+ * @param {number} dt    Delta time in seconds
+ */
+export function updateShake(state, dt) {
+    let anyActive = false;
+
+    for (let i = 0; i < state.slotCount; i++) {
+        const s = state.slots[i];
+        if (!s.active) continue;
+
+        s.time += dt;
+        s.trauma -= s.decay * dt;
+
+        if (s.trauma <= 0) {
+            s.trauma = 0;
+            s.active = false;
+            continue;
+        }
+
+        anyActive = true;
+    }
+
+    state.active = anyActive;
+}
+
+/**
+ * Compute the final shake offset and rotation by summing all active layers.
+ * Uses simplex noise for smooth, organic motion. Zero allocation.
+ *
+ * Called once per frame from camera.apply() AFTER updateShake().
+ *
+ * @param {Object} state ShakeState
+ */
+export function computeShake(state) {
+    let totalOX = 0;
+    let totalOY = 0;
+    let totalAngle = 0;
+
+    for (let i = 0; i < state.slotCount; i++) {
+        const s = state.slots[i];
+        if (!s.active) continue;
+
+        // trauma² for perceptual scaling (small trauma = barely visible)
+        const shake = s.trauma * s.trauma;
+        const t = s.time * s.freq;
+
+        // Sample noise at 3 different offsets for X, Y, angle
+        const noiseBase = NOISE_SEED_OFFSET * (i * 3) + state.seedOffset;
+        const nx = simplex2(t, noiseBase);       // [-1, 1]
+        const ny = simplex2(t, noiseBase + 1);
+        const na = simplex2(t, noiseBase + 2);
+
+        if (s.isDirectional) {
+            // Project shake onto the direction vector
+            const mag = s.maxOffset * shake * nx;
+            totalOX += mag * s.dirX;
+            totalOY += mag * s.dirY;
+        } else {
+            totalOX += s.maxOffset * shake * nx;
+            totalOY += s.maxOffset * shake * ny;
+        }
+
+        totalAngle += s.maxAngle * shake * na;
+    }
+
+    // Apply global scale
+    state.offsetX = Math.fround(totalOX * state.globalScale);
+    state.offsetY = Math.fround(totalOY * state.globalScale);
+    state.angle = Math.fround(totalAngle * state.globalScale);
+}
+
+/**
+ * Stop all active shakes immediately.
+ *
+ * @param {Object} state ShakeState
+ */
+export function clearShakes(state) {
+    for (let i = 0; i < state.slotCount; i++) {
+        state.slots[i].active = false;
+        state.slots[i].trauma = 0;
+    }
+    state.active = false;
+    state.offsetX = 0;
+    state.offsetY = 0;
+    state.angle = 0;
+}

package/src/ShakePresets.js

@@ -0,0 +1,177 @@
+/**
+ * @zakkster/lite-camera-pro — Shake Presets
+ *
+ * Frozen profile objects for common game shake scenarios.
+ * Each preset is a plain object matching the ShakeEngine profile shape.
+ * Developers can register custom presets via registerPreset().
+ *
+ * Zero dependencies. Pure data.
+ */
+
+// ─────────────────────────────────────────────────────
+//  BUILT-IN PRESETS
+// ─────────────────────────────────────────────────────
+
+/**
+ * EXPLOSION — Big boom. High trauma, low frequency for heavy sway,
+ * large offset, medium rotation. Slow decay for lingering feel.
+ */
+export const EXPLOSION = Object.freeze({
+    trauma:    0.8,
+    freq:      12,
+    decay:     0.7,
+    maxOffset: 25,
+    maxAngle:  0.06,
+    dirX:      0,
+    dirY:      0,
+});
+
+/**
+ * EARTHQUAKE — Sustained rumble. Medium trauma, very low frequency
+ * for slow, heavy rolling. Large offset, minimal rotation. Slow decay.
+ */
+export const EARTHQUAKE = Object.freeze({
+    trauma:    0.5,
+    freq:      6,
+    decay:     0.3,
+    maxOffset: 30,
+    maxAngle:  0.02,
+    dirX:      0,
+    dirY:      0,
+});
+
+/**
+ * RECOIL — Gun/weapon kickback. Directional (upward by default).
+ * Short, sharp burst with fast decay.
+ */
+export const RECOIL = Object.freeze({
+    trauma:    0.5,
+    freq:      20,
+    decay:     2.5,
+    maxOffset: 12,
+    maxAngle:  0.02,
+    dirX:      0,
+    dirY:      -1,  // upward kick
+});
+
+/**
+ * IMPACT — Something hit the player/world. Sharp trauma spike,
+ * high frequency for a snappy jolt, fast decay.
+ */
+export const IMPACT = Object.freeze({
+    trauma:    0.7,
+    freq:      25,
+    decay:     2.0,
+    maxOffset: 18,
+    maxAngle:  0.04,
+    dirX:      0,
+    dirY:      0,
+});
+
+/**
+ * LANDING — Player lands from a height. Vertical-only shake.
+ * Medium trauma, medium frequency, moderate decay.
+ */
+export const LANDING = Object.freeze({
+    trauma:    0.4,
+    freq:      18,
+    decay:     1.5,
+    maxOffset: 10,
+    maxAngle:  0.01,
+    dirX:      0,
+    dirY:      1,  // downward push
+});
+
+/**
+ * DAMAGE — Player takes a hit. Quick pulse, low offset,
+ * no rotation. Feels like a screen flash without the flash.
+ */
+export const DAMAGE = Object.freeze({
+    trauma:    0.35,
+    freq:      22,
+    decay:     3.0,
+    maxOffset: 6,
+    maxAngle:  0,
+    dirX:      0,
+    dirY:      0,
+});
+
+/**
+ * RUMBLE — Continuous low-level vibration. Low trauma, high frequency
+ * for a "motor hum" feel. Very slow decay (lingers).
+ * Good for approaching boss, earthquake precursor, engine vibration.
+ */
+export const RUMBLE = Object.freeze({
+    trauma:    0.2,
+    freq:      30,
+    decay:     0.15,
+    maxOffset: 3,
+    maxAngle:  0,
+    dirX:      0,
+    dirY:      0,
+});
+
+/**
+ * HEAVY_IMPACT — Boss stomp, meteor hit, critical attack.
+ * Maximum everything. The "oh no" shake.
+ */
+export const HEAVY_IMPACT = Object.freeze({
+    trauma:    1.0,
+    freq:      10,
+    decay:     0.5,
+    maxOffset: 35,
+    maxAngle:  0.08,
+    dirX:      0,
+    dirY:      0,
+});
+
+// ─────────────────────────────────────────────────────
+//  PRESET REGISTRY
+// ─────────────────────────────────────────────────────
+
+/** @type {Object<string, Object>} */
+const _registry = {
+    explosion:    EXPLOSION,
+    earthquake:   EARTHQUAKE,
+    recoil:       RECOIL,
+    impact:       IMPACT,
+    landing:      LANDING,
+    damage:       DAMAGE,
+    rumble:        RUMBLE,
+    heavy_impact: HEAVY_IMPACT,
+};
+
+/**
+ * Get a preset by name.
+ *
+ * @param {string} name  Preset name (case-insensitive)
+ * @returns {Object|null} Shake profile or null
+ */
+export function getPreset(name) {
+    return _registry[name.toLowerCase()] || null;
+}
+
+/**
+ * Register a custom preset. Overwrites existing presets with the same name.
+ *
+ * @param {string} name    Preset name
+ * @param {Object} profile Shake profile object
+ *
+ * @example
+ * registerPreset('sword_clash', {
+ *   trauma: 0.3, freq: 28, decay: 3.0,
+ *   maxOffset: 8, maxAngle: 0.03,
+ *   dirX: 1, dirY: 0,  // horizontal only
+ * });
+ */
+export function registerPreset(name, profile) {
+    _registry[name.toLowerCase()] = Object.freeze({ ...profile });
+}
+
+/**
+ * List all registered preset names.
+ * @returns {string[]}
+ */
+export function listPresets() {
+    return Object.keys(_registry);
+}