@joydle/juice-babylon 0.1.0

package/dist/CameraShake.d.ts

@@ -0,0 +1,34 @@
+import type { BabylonCamera } from './types.js';
+/**
+ * Applies random positional jitter to a Babylon.js camera.
+ *
+ * Usage:
+ * ```ts
+ * const shake = new CameraShake(camera);
+ * shake.trigger(0.5, 0.3); // intensity 0.5, duration 0.3s
+ * ```
+ */
+export declare class CameraShake {
+    private camera;
+    private originalPos;
+    private intensity;
+    private duration;
+    private elapsed;
+    private rafId;
+    private lastTime;
+    constructor(camera: BabylonCamera);
+    /**
+     * Begin (or restart) a camera shake.
+     * If a shake is already in progress the previous one is replaced -- the
+     * camera position is first restored before starting the new shake.
+     *
+     * @param intensity  Maximum displacement per axis (world units).
+     * @param duration   Shake duration in **seconds**.
+     */
+    trigger(intensity: number, duration: number): void;
+    /** Stop the shake immediately and snap back to the original position. */
+    stop(): void;
+    private loop;
+    private restore;
+}
+//# sourceMappingURL=CameraShake.d.ts.map

package/dist/CameraShake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CameraShake.d.ts","sourceRoot":"","sources":["../src/CameraShake.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAoD;IACvE,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAK;gBAET,MAAM,EAAE,aAAa;IAIjC;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAoBlD,yEAAyE;IACzE,IAAI,IAAI,IAAI;IAUZ,OAAO,CAAC,IAAI,CAsBV;IAEF,OAAO,CAAC,OAAO;CAShB"}

package/dist/CameraShake.js

@@ -0,0 +1,85 @@
+/**
+ * Applies random positional jitter to a Babylon.js camera.
+ *
+ * Usage:
+ * ```ts
+ * const shake = new CameraShake(camera);
+ * shake.trigger(0.5, 0.3); // intensity 0.5, duration 0.3s
+ * ```
+ */
+export class CameraShake {
+    camera;
+    originalPos = null;
+    intensity = 0;
+    duration = 0;
+    elapsed = 0;
+    rafId = null;
+    lastTime = 0;
+    constructor(camera) {
+        this.camera = camera;
+    }
+    /**
+     * Begin (or restart) a camera shake.
+     * If a shake is already in progress the previous one is replaced -- the
+     * camera position is first restored before starting the new shake.
+     *
+     * @param intensity  Maximum displacement per axis (world units).
+     * @param duration   Shake duration in **seconds**.
+     */
+    trigger(intensity, duration) {
+        // If we are already shaking, restore position before restarting.
+        if (this.rafId !== null) {
+            this.restore();
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+        }
+        this.intensity = intensity;
+        this.duration = duration;
+        this.elapsed = 0;
+        this.originalPos = {
+            x: this.camera.position.x,
+            y: this.camera.position.y,
+            z: this.camera.position.z,
+        };
+        this.lastTime = performance.now();
+        this.rafId = requestAnimationFrame(this.loop);
+    }
+    /** Stop the shake immediately and snap back to the original position. */
+    stop() {
+        if (this.rafId !== null) {
+            cancelAnimationFrame(this.rafId);
+            this.rafId = null;
+        }
+        this.restore();
+    }
+    // ---- internal -----------------------------------------------------------
+    loop = (now) => {
+        const dt = (now - this.lastTime) / 1000; // seconds
+        this.lastTime = now;
+        this.elapsed += dt;
+        if (this.elapsed >= this.duration) {
+            this.restore();
+            this.rafId = null;
+            return;
+        }
+        // Linear decay from 1 to 0 over the duration.
+        const decay = 1 - this.elapsed / this.duration;
+        const mag = this.intensity * decay;
+        const pos = this.camera.position;
+        const orig = this.originalPos;
+        pos.x = orig.x + (Math.random() * 2 - 1) * mag;
+        pos.y = orig.y + (Math.random() * 2 - 1) * mag;
+        pos.z = orig.z + (Math.random() * 2 - 1) * mag;
+        this.rafId = requestAnimationFrame(this.loop);
+    };
+    restore() {
+        if (this.originalPos) {
+            const pos = this.camera.position;
+            pos.x = this.originalPos.x;
+            pos.y = this.originalPos.y;
+            pos.z = this.originalPos.z;
+            this.originalPos = null;
+        }
+    }
+}
+//# sourceMappingURL=CameraShake.js.map

package/dist/CameraShake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CameraShake.js","sourceRoot":"","sources":["../src/CameraShake.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAgB;IACtB,WAAW,GAA+C,IAAI,CAAC;IAC/D,SAAS,GAAG,CAAC,CAAC;IACd,QAAQ,GAAG,CAAC,CAAC;IACb,OAAO,GAAG,CAAC,CAAC;IACZ,KAAK,GAAkB,IAAI,CAAC;IAC5B,QAAQ,GAAG,CAAC,CAAC;IAErB,YAAY,MAAqB;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,SAAiB,EAAE,QAAgB;QACzC,iEAAiE;QACjE,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACxB,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG;YACjB,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;SAC1B,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IAED,yEAAyE;IACzE,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACxB,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAED,4EAA4E;IAEpE,IAAI,GAAG,CAAC,GAAW,EAAQ,EAAE;QACnC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC,UAAU;QACnD,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC;QACpB,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;QAEnB,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClC,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,OAAO;QACT,CAAC;QAED,8CAA8C;QAC9C,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QAEnC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAY,CAAC;QAC/B,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;QAC/C,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;QAC/C,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;QAE/C,IAAI,CAAC,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC,CAAC;IAEM,OAAO;QACb,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;YACjC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;YAC3B,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;YAC3B,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;YAC3B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAC1B,CAAC;IACH,CAAC;CACF"}

package/dist/MaterialFlash.d.ts

@@ -0,0 +1,13 @@
+import type { BabylonMesh, BabylonColor } from './types.js';
+/**
+ * Briefly flash a mesh's emissive colour and animate it back using GSAP.
+ *
+ * Handles meshes without a material (or without emissiveColor) gracefully
+ * by returning early as a no-op.
+ *
+ * @param mesh     The Babylon.js mesh to flash.
+ * @param color    Flash colour (Babylon Color3/Color4 or any `{r, g, b}`).
+ * @param duration Flash duration in **seconds**.
+ */
+export declare function MaterialFlash(mesh: BabylonMesh, color: BabylonColor, duration: number): void;
+//# sourceMappingURL=MaterialFlash.d.ts.map

package/dist/MaterialFlash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaterialFlash.d.ts","sourceRoot":"","sources":["../src/MaterialFlash.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAY,MAAM,YAAY,CAAC;AAyBtE;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,GACf,IAAI,CA0BN"}

package/dist/MaterialFlash.js

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// Resolve gsap at runtime (peer dependency).
+// ---------------------------------------------------------------------------
+function getGsap() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const g = globalThis;
+    if (g.gsap)
+        return g.gsap;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('gsap');
+    }
+    catch {
+        throw new Error('[juice-babylon] Could not resolve "gsap". ' +
+            'Make sure it is installed as a peer dependency or available as window.gsap.');
+    }
+}
+// ---------------------------------------------------------------------------
+// MaterialFlash
+// ---------------------------------------------------------------------------
+/**
+ * Briefly flash a mesh's emissive colour and animate it back using GSAP.
+ *
+ * Handles meshes without a material (or without emissiveColor) gracefully
+ * by returning early as a no-op.
+ *
+ * @param mesh     The Babylon.js mesh to flash.
+ * @param color    Flash colour (Babylon Color3/Color4 or any `{r, g, b}`).
+ * @param duration Flash duration in **seconds**.
+ */
+export function MaterialFlash(mesh, color, duration) {
+    // Guard: no material or no emissiveColor property.
+    if (!mesh.material)
+        return;
+    if (!mesh.material.emissiveColor)
+        return;
+    const gsap = getGsap();
+    const emissive = mesh.material.emissiveColor;
+    // Save the original emissive values.
+    const origR = emissive.r;
+    const origG = emissive.g;
+    const origB = emissive.b;
+    // Snap to the flash colour immediately.
+    emissive.r = color.r;
+    emissive.g = color.g;
+    emissive.b = color.b;
+    // Animate back to the original emissive colour over `duration` seconds.
+    gsap.to(emissive, {
+        r: origR,
+        g: origG,
+        b: origB,
+        duration,
+        overwrite: true,
+    });
+}
+//# sourceMappingURL=MaterialFlash.js.map

package/dist/MaterialFlash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaterialFlash.js","sourceRoot":"","sources":["../src/MaterialFlash.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,6CAA6C;AAC7C,8EAA8E;AAE9E,SAAS,OAAO;IACd,8DAA8D;IAC9D,MAAM,CAAC,GAAG,UAAiB,CAAC;IAC5B,IAAI,CAAC,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC,IAAgB,CAAC;IACtC,IAAI,CAAC;QACH,iEAAiE;QACjE,OAAO,OAAO,CAAC,MAAM,CAAa,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,4CAA4C;YAC1C,6EAA6E,CAChF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAiB,EACjB,KAAmB,EACnB,QAAgB;IAEhB,mDAAmD;IACnD,IAAI,CAAC,IAAI,CAAC,QAAQ;QAAE,OAAO;IAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa;QAAE,OAAO;IAEzC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC;IAE7C,qCAAqC;IACrC,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC;IACzB,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC;IACzB,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC;IAEzB,wCAAwC;IACxC,QAAQ,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACrB,QAAQ,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACrB,QAAQ,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IAErB,wEAAwE;IACxE,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE;QAChB,CAAC,EAAE,KAAK;QACR,CAAC,EAAE,KAAK;QACR,CAAC,EAAE,KAAK;QACR,QAAQ;QACR,SAAS,EAAE,IAAI;KAChB,CAAC,CAAC;AACL,CAAC"}

package/dist/MeshHelpers.d.ts

@@ -0,0 +1,57 @@
+import type { BabylonMesh } from './types.js';
+export interface SquashOptions {
+    /** Axis to squash along. @default 'y' */
+    axis?: 'x' | 'y' | 'z';
+    /** Squash amount (0-1, where 1 = fully flattened). @default 0.4 */
+    amount?: number;
+    /** Duration in seconds. @default 0.2 */
+    duration?: number;
+}
+export interface ExplodeOutOptions {
+    /** Target scale multiplier. @default 2 */
+    scaleTo?: number;
+    /** Duration of the fade/scale animation in seconds. @default 0.4 */
+    fadeDuration?: number;
+}
+export interface BobOptions {
+    /** Vertical displacement in world units. @default 0.3 */
+    height?: number;
+    /** Full cycle duration in seconds. @default 1.5 */
+    speed?: number;
+}
+export interface SpinOptions {
+    /** Axis to spin around. @default 'y' */
+    axis?: 'x' | 'y' | 'z';
+    /** Full rotation duration in seconds. @default 2 */
+    speed?: number;
+}
+export interface JuicedMesh extends BabylonMesh {
+    /** Squash-and-stretch on one axis, then return to normal scale. */
+    squash(opts?: SquashOptions): void;
+    /** Scale up and fade out (visibility -> 0). */
+    explodeOut(opts?: ExplodeOutOptions): void;
+    /** Continuous bobbing on position.y. Returns a kill function. */
+    bob(opts?: BobOptions): {
+        kill(): void;
+    };
+    /** Continuous spinning on one rotation axis. Returns a kill function. */
+    spin(opts?: SpinOptions): {
+        kill(): void;
+    };
+}
+/**
+ * Attaches juice helper methods (`.squash()`, `.explodeOut()`, `.bob()`,
+ * `.spin()`) directly onto a Babylon mesh instance.
+ *
+ * All animations use GSAP and operate on the mesh's `scaling`, `position`,
+ * `rotation`, and `visibility` properties -- fully compatible with Babylon's
+ * render loop.
+ *
+ * Usage:
+ * ```ts
+ * addMeshHelpers(myMesh);
+ * (myMesh as JuicedMesh).squash({ axis: 'y', amount: 0.5 });
+ * ```
+ */
+export declare function addMeshHelpers(mesh: BabylonMesh): void;
+//# sourceMappingURL=MeshHelpers.d.ts.map

package/dist/MeshHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshHelpers.d.ts","sourceRoot":"","sources":["../src/MeshHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAA2B,MAAM,YAAY,CAAC;AAyBvE,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACvB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACvB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,mEAAmE;IACnE,MAAM,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC,+CAA+C;IAC/C,UAAU,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC3C,iEAAiE;IACjE,GAAG,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG;QAAE,IAAI,IAAI,IAAI,CAAA;KAAE,CAAC;IACzC,yEAAyE;IACzE,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG;QAAE,IAAI,IAAI,IAAI,CAAA;KAAE,CAAC;CAC5C;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CA4HtD"}

package/dist/MeshHelpers.js

@@ -0,0 +1,140 @@
+// ---------------------------------------------------------------------------
+// Resolve gsap at runtime (peer dependency).
+// ---------------------------------------------------------------------------
+function getGsap() {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const g = globalThis;
+    if (g.gsap)
+        return g.gsap;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('gsap');
+    }
+    catch {
+        throw new Error('[juice-babylon] Could not resolve "gsap". ' +
+            'Make sure it is installed as a peer dependency or available as window.gsap.');
+    }
+}
+// ---------------------------------------------------------------------------
+// addMeshHelpers
+// ---------------------------------------------------------------------------
+/**
+ * Attaches juice helper methods (`.squash()`, `.explodeOut()`, `.bob()`,
+ * `.spin()`) directly onto a Babylon mesh instance.
+ *
+ * All animations use GSAP and operate on the mesh's `scaling`, `position`,
+ * `rotation`, and `visibility` properties -- fully compatible with Babylon's
+ * render loop.
+ *
+ * Usage:
+ * ```ts
+ * addMeshHelpers(myMesh);
+ * (myMesh as JuicedMesh).squash({ axis: 'y', amount: 0.5 });
+ * ```
+ */
+export function addMeshHelpers(mesh) {
+    const m = mesh;
+    // -- squash --------------------------------------------------------------
+    m.squash = function squash(opts = {}) {
+        const gsap = getGsap();
+        const axis = opts.axis ?? 'y';
+        const amount = opts.amount ?? 0.4;
+        const duration = opts.duration ?? 0.2;
+        const halfDur = duration / 2;
+        // Remember the original scale on the target axis.
+        const origScale = mesh.scaling[axis];
+        const squashedScale = origScale * (1 - amount);
+        // Complementary axes stretch to conserve volume.
+        const stretchAxes = ['x', 'y', 'z'].filter((a) => a !== axis);
+        const stretchFactor = 1 / Math.sqrt(1 - amount);
+        const origStretch = {};
+        for (const a of stretchAxes) {
+            origStretch[a] = mesh.scaling[a];
+        }
+        // Phase 1: squash down.
+        const squashVars = {
+            [axis]: squashedScale,
+            duration: halfDur,
+            overwrite: true,
+            onComplete: () => {
+                // Phase 2: spring back to original.
+                const restoreVars = {
+                    [axis]: origScale,
+                    duration: halfDur,
+                    ease: 'back.out(2)',
+                };
+                for (const a of stretchAxes) {
+                    restoreVars[a] = origStretch[a];
+                }
+                gsap.to(mesh.scaling, restoreVars);
+            },
+        };
+        for (const a of stretchAxes) {
+            squashVars[a] = origStretch[a] * stretchFactor;
+        }
+        gsap.to(mesh.scaling, squashVars);
+    };
+    // -- explodeOut ----------------------------------------------------------
+    m.explodeOut = function explodeOut(opts = {}) {
+        const gsap = getGsap();
+        const scaleTo = opts.scaleTo ?? 2;
+        const fadeDuration = opts.fadeDuration ?? 0.4;
+        // Scale up on all axes.
+        gsap.to(mesh.scaling, {
+            x: mesh.scaling.x * scaleTo,
+            y: mesh.scaling.y * scaleTo,
+            z: mesh.scaling.z * scaleTo,
+            duration: fadeDuration,
+            ease: 'power2.out',
+            overwrite: true,
+        });
+        // Fade out visibility.
+        // Babylon meshes use `visibility` (0..1) rather than `opacity`.
+        gsap.to(mesh, {
+            visibility: 0,
+            duration: fadeDuration,
+            ease: 'power2.out',
+            overwrite: 'auto',
+        });
+    };
+    // -- bob -----------------------------------------------------------------
+    m.bob = function bob(opts = {}) {
+        const gsap = getGsap();
+        const height = opts.height ?? 0.3;
+        const speed = opts.speed ?? 1.5;
+        const baseY = mesh.position.y;
+        const tween = gsap.to(mesh.position, {
+            y: baseY + height,
+            duration: speed / 2,
+            ease: 'sine.inOut',
+            yoyo: true,
+            repeat: -1, // infinite
+        });
+        return {
+            kill() {
+                tween.kill();
+                mesh.position.y = baseY;
+            },
+        };
+    };
+    // -- spin ----------------------------------------------------------------
+    m.spin = function spin(opts = {}) {
+        const gsap = getGsap();
+        const axis = opts.axis ?? 'y';
+        const speed = opts.speed ?? 2;
+        const baseRotation = mesh.rotation[axis];
+        const tween = gsap.to(mesh.rotation, {
+            [axis]: baseRotation + Math.PI * 2,
+            duration: speed,
+            ease: 'none',
+            repeat: -1, // infinite
+        });
+        return {
+            kill() {
+                tween.kill();
+                mesh.rotation[axis] = baseRotation;
+            },
+        };
+    };
+}
+//# sourceMappingURL=MeshHelpers.js.map

package/dist/MeshHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshHelpers.js","sourceRoot":"","sources":["../src/MeshHelpers.ts"],"names":[],"mappings":"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"}

package/dist/ParticleBurst.d.ts

@@ -0,0 +1,44 @@
+import type { BabylonScene, BabylonColor } from './types.js';
+export interface ParticleBurstOptions {
+    /** Maximum particle capacity. @default 60 */
+    max?: number;
+}
+export interface BurstOptions {
+    /** Particle colour (Babylon Color4 or any {r,g,b,a?}). */
+    color: BabylonColor;
+    /** Number of particles to emit. */
+    count: number;
+    /** Ejection speed (units/s). @default 3 */
+    speed?: number;
+    /** Particle lifetime in seconds. @default 0.6 */
+    lifetime?: number;
+}
+/**
+ * Wrapper around Babylon's `ParticleSystem` providing a one-shot burst API.
+ *
+ * Each call to `burst()` creates a short-lived particle system that
+ * automatically disposes itself after the particles die.
+ *
+ * Usage:
+ * ```ts
+ * const pb = new ParticleBurst(scene);
+ * pb.burst({ x: 0, y: 1, z: 0 }, { color: new Color4(1,0,0,1), count: 30 });
+ * ```
+ */
+export declare class ParticleBurst {
+    private scene;
+    private max;
+    private activeSystems;
+    constructor(scene: BabylonScene, opts?: ParticleBurstOptions);
+    /**
+     * Emit a burst of particles at a world-space position.
+     */
+    burst(position: {
+        x: number;
+        y: number;
+        z: number;
+    }, opts: BurstOptions): void;
+    /** Dispose all active particle systems immediately. */
+    dispose(): void;
+}
+//# sourceMappingURL=ParticleBurst.d.ts.map

package/dist/ParticleBurst.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleBurst.d.ts","sourceRoot":"","sources":["../src/ParticleBurst.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAEb,MAAM,YAAY,CAAC;AAuEpB,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,KAAK,EAAE,YAAY,CAAC;IACpB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,aAAa,CAAmC;gBAE5C,KAAK,EAAE,YAAY,EAAE,IAAI,GAAE,oBAAyB;IAKhE;;OAEG;IACH,KAAK,CACH,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAC7C,IAAI,EAAE,YAAY,GACjB,IAAI;IAoFP,uDAAuD;IACvD,OAAO,IAAI,IAAI;CAWhB"}

package/dist/ParticleBurst.js

@@ -0,0 +1,126 @@
+/** Cached reference to the Babylon namespace. */
+let BABYLON = null;
+function ensureBabylon() {
+    if (BABYLON)
+        return BABYLON;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const g = globalThis;
+    if (g.BABYLON) {
+        BABYLON = g.BABYLON;
+        return BABYLON;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        BABYLON = require('@babylonjs/core');
+        return BABYLON;
+    }
+    catch {
+        throw new Error('[juice-babylon] Could not resolve "@babylonjs/core". ' +
+            'Make sure it is installed as a peer dependency or available as window.BABYLON.');
+    }
+}
+// ---------------------------------------------------------------------------
+// 1x1 white pixel as a minimal default particle texture (base64 PNG).
+// ---------------------------------------------------------------------------
+const WHITE_PIXEL_BASE64 = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5/hPwAIAgL/4d1j8wAAAABJRU5ErkJggg==';
+/**
+ * Wrapper around Babylon's `ParticleSystem` providing a one-shot burst API.
+ *
+ * Each call to `burst()` creates a short-lived particle system that
+ * automatically disposes itself after the particles die.
+ *
+ * Usage:
+ * ```ts
+ * const pb = new ParticleBurst(scene);
+ * pb.burst({ x: 0, y: 1, z: 0 }, { color: new Color4(1,0,0,1), count: 30 });
+ * ```
+ */
+export class ParticleBurst {
+    scene;
+    max;
+    activeSystems = [];
+    constructor(scene, opts = {}) {
+        this.scene = scene;
+        this.max = opts.max ?? 60;
+    }
+    /**
+     * Emit a burst of particles at a world-space position.
+     */
+    burst(position, opts) {
+        const B = ensureBabylon();
+        const speed = opts.speed ?? 3;
+        const lifetime = opts.lifetime ?? 0.6;
+        const count = opts.count;
+        const ps = new B.ParticleSystem('juice_burst_' + Date.now(), this.max, this.scene);
+        // -- Emitter at the given position ------------------------------------
+        ps.emitter = new B.Vector3(position.x, position.y, position.z);
+        // Emit from a single point.
+        ps.minEmitBox = new B.Vector3(0, 0, 0);
+        ps.maxEmitBox = new B.Vector3(0, 0, 0);
+        // -- Colours ----------------------------------------------------------
+        const c = opts.color;
+        const alpha = c.a ?? 1;
+        ps.color1 = new B.Color4(c.r, c.g, c.b, alpha);
+        ps.color2 = new B.Color4(c.r * 0.8, c.g * 0.8, c.b * 0.8, alpha);
+        ps.colorDead = new B.Color4(c.r * 0.2, c.g * 0.2, c.b * 0.2, 0);
+        // -- Size -------------------------------------------------------------
+        ps.minSize = 0.05;
+        ps.maxSize = 0.15;
+        // -- Lifetime ---------------------------------------------------------
+        ps.minLifeTime = lifetime * 0.5;
+        ps.maxLifeTime = lifetime;
+        // -- Emission rate (high burst then stop) ------------------------------
+        // We emit all particles immediately in one big burst by setting a high
+        // rate and a short target stop duration.
+        ps.emitRate = count * 10; // emit very fast
+        ps.blendMode = 1; // BLENDMODE_ONEONE (additive)
+        // -- Speed / direction ------------------------------------------------
+        ps.minEmitPower = speed * 0.5;
+        ps.maxEmitPower = speed;
+        ps.updateSpeed = 0.01;
+        // Omnidirectional burst.
+        ps.direction1 = new B.Vector3(-1, -1, -1);
+        ps.direction2 = new B.Vector3(1, 1, 1);
+        // -- Auto-stop & dispose ----------------------------------------------
+        // targetStopDuration causes the system to stop emitting after N seconds,
+        // and disposeOnStop cleans up the GPU resources automatically.
+        ps.targetStopDuration = 0.05; // emit for a very short window
+        ps.disposeOnStop = true;
+        // Try to create a default particle texture. Babylon ParticleSystem
+        // requires a particleTexture to render. We use a 1x1 white pixel so the
+        // system works without external asset loading.
+        try {
+            if (B.Texture?.CreateFromBase64String) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                ps.particleTexture = B.Texture.CreateFromBase64String(WHITE_PIXEL_BASE64, 'juice_particle_tex', this.scene);
+            }
+        }
+        catch {
+            // Non-critical -- particles may render as white squares.
+        }
+        // Track for bulk dispose.
+        this.activeSystems.push(ps);
+        ps.start();
+        // Remove from tracking after particles are fully dead.
+        const cleanupDelay = (lifetime + 0.1) * 1000;
+        setTimeout(() => {
+            const idx = this.activeSystems.indexOf(ps);
+            if (idx !== -1)
+                this.activeSystems.splice(idx, 1);
+        }, cleanupDelay);
+    }
+    /** Dispose all active particle systems immediately. */
+    dispose() {
+        for (const ps of this.activeSystems) {
+            try {
+                ps.stop();
+                ps.dispose();
+            }
+            catch {
+                // Already disposed or scene gone.
+            }
+        }
+        this.activeSystems.length = 0;
+    }
+}
+//# sourceMappingURL=ParticleBurst.js.map

package/dist/ParticleBurst.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleBurst.js","sourceRoot":"","sources":["../src/ParticleBurst.ts"],"names":[],"mappings":"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"}

package/dist/TrailMesh.d.ts

@@ -0,0 +1,30 @@
+import type { BabylonScene, BabylonMesh, BabylonColor } from './types.js';
+export interface TrailOptions {
+    /** Trail length (number of segments). @default 60 */
+    length?: number;
+    /** Trail diameter. @default 0.2 */
+    diameter?: number;
+    /** Trail colour. If omitted, uses a default white. */
+    color?: BabylonColor;
+}
+/**
+ * Wrapper around Babylon's `TrailMesh` that follows a source mesh.
+ *
+ * If `TrailMesh` is not available in the current Babylon.js build, all
+ * operations become no-ops, so it is safe to use unconditionally.
+ *
+ * Usage:
+ * ```ts
+ * const trail = new TrailEffect(scene, playerMesh, { length: 80, color: myColor });
+ * // ... later
+ * trail.dispose();
+ * ```
+ */
+export declare class TrailEffect {
+    private trail;
+    private material;
+    constructor(scene: BabylonScene, mesh: BabylonMesh, opts?: TrailOptions);
+    /** Stop the trail and release GPU resources. */
+    dispose(): void;
+}
+//# sourceMappingURL=TrailMesh.d.ts.map

package/dist/TrailMesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrailMesh.d.ts","sourceRoot":"","sources":["../src/TrailMesh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA4E1E,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,QAAQ,CAAqC;gBAGnD,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,WAAW,EACjB,IAAI,GAAE,YAAiB;IAqDzB,gDAAgD;IAChD,OAAO,IAAI,IAAI;CAkBhB"}

package/dist/TrailMesh.js

@@ -0,0 +1,98 @@
+/** Cached reference. */
+let BABYLON = null;
+function resolveBabylon() {
+    if (BABYLON)
+        return BABYLON;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const g = globalThis;
+    if (g.BABYLON) {
+        BABYLON = g.BABYLON;
+        return BABYLON;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        BABYLON = require('@babylonjs/core');
+        return BABYLON;
+    }
+    catch {
+        // Return empty namespace -- TrailMesh will be unavailable and we gracefully no-op.
+        BABYLON = {};
+        return BABYLON;
+    }
+}
+/**
+ * Wrapper around Babylon's `TrailMesh` that follows a source mesh.
+ *
+ * If `TrailMesh` is not available in the current Babylon.js build, all
+ * operations become no-ops, so it is safe to use unconditionally.
+ *
+ * Usage:
+ * ```ts
+ * const trail = new TrailEffect(scene, playerMesh, { length: 80, color: myColor });
+ * // ... later
+ * trail.dispose();
+ * ```
+ */
+export class TrailEffect {
+    trail = null;
+    material = null;
+    constructor(scene, mesh, opts = {}) {
+        const B = resolveBabylon();
+        if (!B.TrailMesh) {
+            // TrailMesh not available in this Babylon build -- graceful no-op.
+            return;
+        }
+        const length = opts.length ?? 60;
+        const diameter = opts.diameter ?? 0.2;
+        try {
+            this.trail = new B.TrailMesh('juice_trail_' + mesh.name, mesh, scene, diameter, length, true);
+            // Apply colour via a simple emissive material if constructors are available.
+            if (B.StandardMaterial && opts.color) {
+                const mat = new B.StandardMaterial('juice_trail_mat_' + mesh.name, scene);
+                mat.emissiveColor = opts.color;
+                if (B.Color3) {
+                    mat.diffuseColor = new B.Color3(0, 0, 0);
+                }
+                mat.alpha = 0.6;
+                mat.backFaceCulling = false;
+                // The TrailMesh exposes .mesh for the generated mesh geometry.
+                if (this.trail.mesh && this.trail.mesh.material !== undefined) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    this.trail.mesh.material = mat;
+                }
+                else {
+                    // Some versions expose the material directly on the trail instance.
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    this.trail.material = mat;
+                }
+                this.material = mat;
+            }
+        }
+        catch {
+            // Construction failed -- remain in no-op state.
+            this.trail = null;
+        }
+    }
+    /** Stop the trail and release GPU resources. */
+    dispose() {
+        if (this.trail) {
+            try {
+                this.trail.dispose();
+            }
+            catch {
+                // Already disposed.
+            }
+            this.trail = null;
+        }
+        if (this.material) {
+            try {
+                this.material.dispose();
+            }
+            catch {
+                // Already disposed.
+            }
+            this.material = null;
+        }
+    }
+}
+//# sourceMappingURL=TrailMesh.js.map

package/dist/TrailMesh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrailMesh.js","sourceRoot":"","sources":["../src/TrailMesh.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { BabylonVec3, BabylonColor, BabylonMaterial, BabylonMesh, BabylonCamera, BabylonScene, BabylonParticleSystemLike, GsapLike, GsapTweenLike, JuiceToolkit, } from './types.js';
+export { CameraShake } from './CameraShake.js';
+export { ParticleBurst } from './ParticleBurst.js';
+export type { ParticleBurstOptions, BurstOptions } from './ParticleBurst.js';
+export { MaterialFlash } from './MaterialFlash.js';
+export { TrailEffect } from './TrailMesh.js';
+export type { TrailOptions } from './TrailMesh.js';
+export { addMeshHelpers } from './MeshHelpers.js';
+export type { JuicedMesh, SquashOptions, ExplodeOutOptions, BobOptions, SpinOptions, } from './MeshHelpers.js';
+export { createBabylonJuiceToolkit } from './toolkit.js';
+export type { CreateToolkitOptions } from './toolkit.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,YAAY,EACZ,yBAAyB,EACzB,QAAQ,EACR,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG7E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,WAAW,GACZ,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+// ---------------------------------------------------------------------------
+//  @joydle/juice-babylon -- Public API barrel
+// ---------------------------------------------------------------------------
+// Camera shake
+export { CameraShake } from './CameraShake.js';
+// Particle burst
+export { ParticleBurst } from './ParticleBurst.js';
+// Material flash
+export { MaterialFlash } from './MaterialFlash.js';
+// Trail mesh
+export { TrailEffect } from './TrailMesh.js';
+// Mesh helpers
+export { addMeshHelpers } from './MeshHelpers.js';
+// Toolkit factory
+export { createBabylonJuiceToolkit } from './toolkit.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8CAA8C;AAC9C,8EAA8E;AAgB9E,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,iBAAiB;AACjB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,iBAAiB;AACjB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,aAAa;AACb,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C,eAAe;AACf,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASlD,kBAAkB;AAClB,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC"}

package/dist/toolkit.d.ts

@@ -0,0 +1,30 @@
+import type { BabylonScene, BabylonCamera, JuiceToolkit } from './types.js';
+export interface CreateToolkitOptions {
+    /** Maximum particles per burst system. @default 60 */
+    maxParticles?: number;
+}
+/**
+ * Creates a unified `JuiceToolkit` for Babylon.js scenes.
+ *
+ * Internally instantiates a `CameraShake` and `ParticleBurst` and exposes
+ * them through the unified toolkit interface.  Also provides `flash()`,
+ * `trail()`, and `addHelpers()` for material, trail, and mesh utilities.
+ *
+ * Usage:
+ * ```ts
+ * import { createBabylonJuiceToolkit } from '@joydle/juice-babylon';
+ *
+ * const juice = createBabylonJuiceToolkit(scene, camera);
+ * juice.shake({ intensity: 0.4, duration: 0.3 });
+ * juice.flash(mesh, { color: redColor, duration: 0.2 });
+ * juice.particles({ position: { x: 0, y: 1, z: 0 }, color: whiteColor, count: 30 });
+ * const trail = juice.trail(mesh, { length: 80, color: blueColor });
+ * juice.addHelpers(mesh);
+ * ```
+ *
+ * @param scene   The Babylon.js scene.
+ * @param camera  The Babylon.js camera (used for shake).
+ * @param opts    Optional configuration.
+ */
+export declare function createBabylonJuiceToolkit(scene: BabylonScene, camera: BabylonCamera, opts?: CreateToolkitOptions): JuiceToolkit;
+//# sourceMappingURL=toolkit.d.ts.map

package/dist/toolkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolkit.d.ts","sourceRoot":"","sources":["../src/toolkit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAA6B,YAAY,EAAE,MAAM,YAAY,CAAC;AAWvG,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,aAAa,EACrB,IAAI,GAAE,oBAAyB,GAC9B,YAAY,CA0Ed"}

package/dist/toolkit.js

@@ -0,0 +1,87 @@
+import { CameraShake } from './CameraShake.js';
+import { ParticleBurst } from './ParticleBurst.js';
+import { MaterialFlash } from './MaterialFlash.js';
+import { TrailEffect } from './TrailMesh.js';
+import { addMeshHelpers } from './MeshHelpers.js';
+// ---------------------------------------------------------------------------
+// createBabylonJuiceToolkit
+// ---------------------------------------------------------------------------
+/**
+ * Creates a unified `JuiceToolkit` for Babylon.js scenes.
+ *
+ * Internally instantiates a `CameraShake` and `ParticleBurst` and exposes
+ * them through the unified toolkit interface.  Also provides `flash()`,
+ * `trail()`, and `addHelpers()` for material, trail, and mesh utilities.
+ *
+ * Usage:
+ * ```ts
+ * import { createBabylonJuiceToolkit } from '@joydle/juice-babylon';
+ *
+ * const juice = createBabylonJuiceToolkit(scene, camera);
+ * juice.shake({ intensity: 0.4, duration: 0.3 });
+ * juice.flash(mesh, { color: redColor, duration: 0.2 });
+ * juice.particles({ position: { x: 0, y: 1, z: 0 }, color: whiteColor, count: 30 });
+ * const trail = juice.trail(mesh, { length: 80, color: blueColor });
+ * juice.addHelpers(mesh);
+ * ```
+ *
+ * @param scene   The Babylon.js scene.
+ * @param camera  The Babylon.js camera (used for shake).
+ * @param opts    Optional configuration.
+ */
+export function createBabylonJuiceToolkit(scene, camera, opts = {}) {
+    const shake = new CameraShake(camera);
+    const particles = new ParticleBurst(scene, { max: opts.maxParticles ?? 60 });
+    // Track trails for bulk disposal.
+    const activeTrails = [];
+    const toolkit = {
+        // -- shake ---------------------------------------------------------------
+        shake(shakeOpts) {
+            shake.trigger(shakeOpts.intensity, shakeOpts.duration);
+        },
+        // -- flash ---------------------------------------------------------------
+        flash(target, flashOpts) {
+            MaterialFlash(target, flashOpts.color, flashOpts.duration);
+        },
+        // -- particles -----------------------------------------------------------
+        particles(burstOpts) {
+            particles.burst(burstOpts.position, {
+                color: burstOpts.color,
+                count: burstOpts.count,
+                speed: burstOpts.speed,
+                lifetime: burstOpts.lifetime,
+            });
+        },
+        // -- trail ---------------------------------------------------------------
+        trail(target, trailOpts) {
+            const trail = new TrailEffect(scene, target, {
+                length: trailOpts.length,
+                color: trailOpts.color,
+            });
+            activeTrails.push(trail);
+            return {
+                dispose() {
+                    trail.dispose();
+                    const idx = activeTrails.indexOf(trail);
+                    if (idx !== -1)
+                        activeTrails.splice(idx, 1);
+                },
+            };
+        },
+        // -- helpers -------------------------------------------------------------
+        addHelpers(mesh) {
+            addMeshHelpers(mesh);
+        },
+        // -- dispose -------------------------------------------------------------
+        dispose() {
+            shake.stop();
+            particles.dispose();
+            for (const t of activeTrails) {
+                t.dispose();
+            }
+            activeTrails.length = 0;
+        },
+    };
+    return toolkit;
+}
+//# sourceMappingURL=toolkit.js.map

package/dist/toolkit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolkit.js","sourceRoot":"","sources":["../src/toolkit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAWlD,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAmB,EACnB,MAAqB,EACrB,OAA6B,EAAE;IAE/B,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,IAAI,aAAa,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,YAAY,IAAI,EAAE,EAAE,CAAC,CAAC;IAE7E,kCAAkC;IAClC,MAAM,YAAY,GAAkB,EAAE,CAAC;IAEvC,MAAM,OAAO,GAAiB;QAC5B,2EAA2E;QAC3E,KAAK,CAAC,SAAkD;YACtD,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;QACzD,CAAC;QAED,2EAA2E;QAC3E,KAAK,CACH,MAAmB,EACnB,SAAoD;YAEpD,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC7D,CAAC;QAED,2EAA2E;QAC3E,SAAS,CAAC,SAMT;YACC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,EAAE;gBAClC,KAAK,EAAE,SAAS,CAAC,KAAK;gBACtB,KAAK,EAAE,SAAS,CAAC,KAAK;gBACtB,KAAK,EAAE,SAAS,CAAC,KAAK;gBACtB,QAAQ,EAAE,SAAS,CAAC,QAAQ;aAC7B,CAAC,CAAC;QACL,CAAC;QAED,2EAA2E;QAC3E,KAAK,CACH,MAAmB,EACnB,SAAoD;YAEpD,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE;gBAC3C,MAAM,EAAE,SAAS,CAAC,MAAM;gBACxB,KAAK,EAAE,SAAS,CAAC,KAAK;aACvB,CAAC,CAAC;YACH,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAEzB,OAAO;gBACL,OAAO;oBACL,KAAK,CAAC,OAAO,EAAE,CAAC;oBAChB,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;oBACxC,IAAI,GAAG,KAAK,CAAC,CAAC;wBAAE,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBAC9C,CAAC;aACF,CAAC;QACJ,CAAC;QAED,2EAA2E;QAC3E,UAAU,CAAC,IAAiB;YAC1B,cAAc,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;QAED,2EAA2E;QAC3E,OAAO;YACL,KAAK,CAAC,IAAI,EAAE,CAAC;YACb,SAAS,CAAC,OAAO,EAAE,CAAC;YACpB,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;gBAC7B,CAAC,CAAC,OAAO,EAAE,CAAC;YACd,CAAC;YACD,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;QAC1B,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+/** Subset of BABYLON.Vector3 we rely on. */
+export interface BabylonVec3 {
+    x: number;
+    y: number;
+    z: number;
+    copyFrom(source: BabylonVec3): void;
+}
+/** Subset of BABYLON.Color3 / Color4 we rely on. */
+export interface BabylonColor {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+    clone(): BabylonColor;
+    copyFrom(source: BabylonColor): void;
+}
+/** Subset of BABYLON.Material we rely on (StandardMaterial / PBRMaterial). */
+export interface BabylonMaterial {
+    emissiveColor?: BabylonColor;
+    dispose?(): void;
+}
+/** Subset of BABYLON.AbstractMesh we rely on. */
+export interface BabylonMesh {
+    name: string;
+    position: BabylonVec3;
+    scaling: BabylonVec3;
+    rotation: BabylonVec3;
+    visibility: number;
+    material: BabylonMaterial | null;
+    isDisposed(): boolean;
+}
+/** Subset of BABYLON.Camera we rely on (any camera type). */
+export interface BabylonCamera {
+    position: BabylonVec3;
+}
+/** Subset of BABYLON.Scene we rely on. */
+export interface BabylonScene {
+    [key: string]: any;
+}
+/** Subset of BABYLON.ParticleSystem we construct at runtime. */
+export interface BabylonParticleSystemLike {
+    emitter: BabylonVec3 | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    minEmitBox: BabylonVec3;
+    maxEmitBox: BabylonVec3;
+    color1: BabylonColor;
+    color2: BabylonColor;
+    colorDead: BabylonColor;
+    minSize: number;
+    maxSize: number;
+    minLifeTime: number;
+    maxLifeTime: number;
+    emitRate: number;
+    blendMode: number;
+    minEmitPower: number;
+    maxEmitPower: number;
+    updateSpeed: number;
+    direction1: BabylonVec3;
+    direction2: BabylonVec3;
+    targetStopDuration: number;
+    disposeOnStop: boolean;
+    start(): void;
+    stop(): void;
+    dispose(): void;
+}
+export interface GsapLike {
+    to(target: unknown, vars: Record<string, unknown>): GsapTweenLike;
+    killTweensOf(target: unknown): void;
+}
+export interface GsapTweenLike {
+    kill(): void;
+}
+export interface JuiceToolkit {
+    /** Trigger camera shake. */
+    shake(opts: {
+        intensity: number;
+        duration: number;
+    }): void;
+    /** Flash an emissive colour on a mesh's material. */
+    flash(target: BabylonMesh, opts: {
+        color: BabylonColor;
+        duration: number;
+    }): void;
+    /** Emit a burst of particles at a world position. */
+    particles(opts: {
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        color: BabylonColor;
+        count: number;
+        speed?: number;
+        lifetime?: number;
+    }): void;
+    /** Attach a trail to a mesh. Returns a dispose function. */
+    trail(target: BabylonMesh, opts: {
+        length?: number;
+        color?: BabylonColor;
+    }): {
+        dispose(): void;
+    };
+    /** Add squash/explodeOut/bob/spin helpers to a mesh. */
+    addHelpers(mesh: BabylonMesh): void;
+    /** Dispose all internal resources. */
+    dispose(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,9 @@
+// ---------------------------------------------------------------------------
+//  @joydle/juice-babylon -- Local type definitions
+//
+//  Minimal inline interfaces for Babylon.js and GSAP so this package compiles
+//  without importing from the peer dependency type roots.  Consumers supply
+//  real Babylon.js / GSAP objects at runtime.
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mDAAmD;AACnD,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,8CAA8C;AAC9C,8EAA8E"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@joydle/juice-babylon",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Joydle <contact@joydle.dev>",
+  "homepage": "https://joydle.dev",
+  "peerDependencies": {
+    "@babylonjs/core": "^6.0 || ^7.0",
+    "gsap": "^3.12"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}