babylon.quarks-editor 0.17.8 → 0.18.0

package/src/core/binding.ts

@@ -85,13 +85,10 @@ export class EffectBinding {
     }
 
     restart(): void {
-        // Replay every independent system; sub-emitter targets (onlyUsedByOther) are only
-        // reset — their parents re-drive them, so playing them directly would double-emit.
+        // onlyUsedByOther systems skip self-emission in update(); play() only unpauses sim.
         for (const system of [this.system, ...this.subSystems]) {
             system.restart();
-            if (!system.onlyUsedByOther) {
-                system.play();
-            }
+            system.play();
         }
     }
 

package/src/core/defaultEffect.ts

@@ -0,0 +1,74 @@
+import type {Scene} from '@babylonjs/core/scene';
+import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import {
+    ColorOverLife,
+    ConeEmitter,
+    ConstantColor,
+    ConstantValue,
+    IntervalValue,
+    ParticleSystem,
+    RenderMode,
+    Vector4,
+} from 'babylon.quarks';
+import {DEFAULT_GRADIENT_STOPS, buildGradient} from './colors';
+import type {GalleryEntry} from './loadEffectGallery';
+
+export interface CreateGalleryDefaultOptions {
+    resolveTexture?: (url: string, scene: Scene) => unknown;
+    textureUrl?: string;
+}
+
+/** Creates a simple cone burst preset for new editor effects. */
+export function createDefaultEffect(
+    scene: Scene,
+    resolveTexture?: (url: string, scene: Scene) => unknown,
+    textureUrl?: string
+): ParticleSystem {
+    const system = new ParticleSystem({
+        scene,
+        duration: 4,
+        looping: true,
+        startLife: new IntervalValue(1.2, 1.8),
+        startSpeed: new IntervalValue(3, 5),
+        startSize: new IntervalValue(0.25, 0.5),
+        startColor: new ConstantColor(new Vector4(1, 1, 1, 1)),
+        emissionOverTime: new ConstantValue(80),
+        shape: new ConeEmitter({radius: 0.3, angle: 0.25}),
+        renderMode: RenderMode.BillBoard,
+        texture: (textureUrl && resolveTexture ? resolveTexture(textureUrl, scene) : undefined) as never,
+        transparent: true,
+        blendMode: 1,
+    });
+    system.addBehavior(new ColorOverLife(buildGradient(DEFAULT_GRADIENT_STOPS)));
+    system.emitter.rotation.x = -Math.PI / 2;
+    return system;
+}
+
+/** Adds a blank preset effect to the hidden gallery catalog (not in the renderer yet). */
+export function createGalleryDefaultEntry(
+    scene: Scene,
+    catalogRoot: TransformNode,
+    existing: GalleryEntry[],
+    options: CreateGalleryDefaultOptions = {}
+): GalleryEntry {
+    const takenNames = new Set(existing.map((entry) => entry.name));
+    const takenPaths = new Set(existing.map((entry) => entry.path));
+
+    let name = existing.length === 0 ? 'Effect' : 'New Effect';
+    let suffix = 2;
+    while (takenNames.has(name) || takenPaths.has(`_created/${name}.json`)) {
+        name = `New Effect ${suffix}`;
+        suffix++;
+    }
+
+    const path = `_created/${name}.json`;
+    const system = createDefaultEffect(scene, options.resolveTexture, options.textureUrl);
+    system.pause();
+
+    const root = new TransformNode(name, scene);
+    system.emitter.parent = root;
+    root.parent = catalogRoot;
+    root.setEnabled(false);
+
+    return {name, path, root, systems: [system], inScene: false};
+}

package/src/core/editorScene.ts

@@ -0,0 +1,14 @@
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+
+/** Marks meshes/nodes created only for editor interaction or overlays (not part of the effect). */
+export const EDITOR_SCENE_NODE_METADATA = {quarksEditorSceneNode: true as const};
+
+/** True for viewport pick proxies, shape wireframes, and other non-exportable scene helpers. */
+export function isEditorSceneNode(node: TransformNode): boolean {
+    const meta = node.metadata as {quarksEditorPick?: boolean; quarksEditorSceneNode?: boolean} | undefined;
+    if (meta?.quarksEditorPick || meta?.quarksEditorSceneNode) {
+        return true;
+    }
+    const name = node.name;
+    return name.startsWith('viewport-pick-root-') || name.startsWith('wf-');
+}

package/src/core/effectTree.ts

@@ -2,6 +2,7 @@ import {ParticleEmitter} from 'babylon.quarks';
 import type {ParticleSystem} from 'babylon.quarks';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Matrix, Quaternion} from '@babylonjs/core/Maths/math.vector';
+import {isEditorSceneNode} from './editorScene';
 
 /** A node in the editor's effect hierarchy: a Group (organizational) or a ParticleEmitter. */
 export interface EffectTreeNode {
@@ -24,7 +25,7 @@ export function buildEffectTree(root: TransformNode, depth = 0): EffectTreeNode
         children: [],
     };
     for (const child of root.getChildren()) {
-        if (child instanceof TransformNode) {
+        if (child instanceof TransformNode && !isEditorSceneNode(child)) {
             treeNode.children.push(buildEffectTree(child, depth + 1));
         }
     }

package/src/core/emitterShapeWireframe.ts

@@ -0,0 +1,373 @@
+import type {ParticleSystem} from 'babylon.quarks';
+import {Color3} from '@babylonjs/core/Maths/math.color';
+import {Vector3} from '@babylonjs/core/Maths/math.vector';
+import {Mesh} from '@babylonjs/core/Meshes/mesh';
+import {LinesMesh} from '@babylonjs/core/Meshes/linesMesh';
+import {MeshBuilder} from '@babylonjs/core/Meshes/meshBuilder';
+import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {Scene} from '@babylonjs/core/scene';
+import {getShapeType, readShapeParams} from './shapes';
+import {EDITOR_SCENE_NODE_METADATA} from './editorScene';
+
+const LINE_COLOR = new Color3(0.45, 0.82, 1);
+const DIRECTION_COLOR = new Color3(0.75, 0.92, 1);
+
+/**
+ * Optional wireframe overlays for every emitter shape in the current effect.
+ * Geometry follows quarks.core spawn math (local XY spawn plane, +Z emit axis).
+ */
+export class EmitterShapeWireframes {
+    private readonly scene: Scene;
+    private readonly container: TransformNode;
+    private meshes: Mesh[] = [];
+    private visible = false;
+    private syncKey = '';
+
+    constructor(scene: Scene) {
+        this.scene = scene;
+        this.container = new TransformNode('emitter-wireframes', scene);
+        this.container.setEnabled(false);
+    }
+
+    setVisible(on: boolean): void {
+        this.visible = on;
+        if (!on) {
+            this.clearMeshes();
+            this.container.setEnabled(false);
+            this.syncKey = '';
+        }
+    }
+
+    /** Rebuilds overlays when the binding revision changes. */
+    sync(systems: ParticleSystem[], syncKey: string): void {
+        if (!this.visible) {
+            return;
+        }
+        if (syncKey === this.syncKey) {
+            return;
+        }
+        this.syncKey = syncKey;
+        this.rebuild(systems);
+    }
+
+    dispose(): void {
+        this.setVisible(false);
+        this.container.dispose();
+    }
+
+    private rebuild(systems: ParticleSystem[]): void {
+        this.clearMeshes();
+        this.container.setEnabled(true);
+        for (const system of systems) {
+            if (system.emitter.isDisposed()) {
+                continue;
+            }
+            for (const mesh of buildEmitterWireframe(system, this.scene)) {
+                mesh.parent = system.emitter;
+                mesh.metadata = {...(mesh.metadata ?? {}), ...EDITOR_SCENE_NODE_METADATA};
+                mesh.isPickable = false;
+                mesh.renderingGroupId = 1;
+                this.meshes.push(mesh);
+            }
+        }
+    }
+
+    private clearMeshes(): void {
+        for (const mesh of this.meshes) {
+            mesh.dispose();
+        }
+        this.meshes = [];
+    }
+}
+
+function buildEmitterWireframe(system: ParticleSystem, scene: Scene): Mesh[] {
+    const type = getShapeType(system.emitterShape);
+    const params = readShapeParams(system.emitterShape);
+    const meshes: Mesh[] = [];
+    const lines = (name: string, points: Vector3[], color = LINE_COLOR) => {
+        if (points.length < 2) {
+            return;
+        }
+        const mesh = MeshBuilder.CreateLines(name, {points}, scene) as LinesMesh;
+        mesh.color = color.clone();
+        mesh.isPickable = false;
+        meshes.push(mesh);
+    };
+
+    switch (type) {
+        case 'point': {
+            // Spawn at origin; velocity is random in a unit ball.
+            const s = 0.12;
+            lines('wf-point-x', [new Vector3(-s, 0, 0), new Vector3(s, 0, 0)]);
+            lines('wf-point-y', [new Vector3(0, -s, 0), new Vector3(0, s, 0)]);
+            lines('wf-point-z', [new Vector3(0, 0, -s), new Vector3(0, 0, s)], DIRECTION_COLOR);
+            break;
+        }
+        case 'cone': {
+            // Spawn: disk/ring on XY at z=0 (radius, thickness, arc).
+            // Velocity: +Z with spread angle — rim dir = (sinα·û, cosα).
+            const radius = Math.max(params.radius, 0.001);
+            const angle = Math.max(0, params.angle);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            lines('wf-cone-outer', xyArc(radius, arc));
+            if (thickness < 1) {
+                lines('wf-cone-inner', xyArc(radius * (1 - thickness), arc));
+            }
+            if (arc < Math.PI * 2 - 1e-3) {
+                lines('wf-cone-spoke-a', [Vector3.Zero(), arcPoint(radius, 0)]);
+                lines('wf-cone-spoke-b', [Vector3.Zero(), arcPoint(radius, arc)]);
+            }
+
+            const preview = Math.max(radius * 2, 1.25);
+            const farRadius = radius + preview * Math.tan(angle);
+            const spokeCount = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 12));
+            for (let i = 0; i <= spokeCount; i++) {
+                const theta = (i / spokeCount) * arc;
+                const rim = arcPoint(radius, theta);
+                const dir = new Vector3(Math.sin(angle) * Math.cos(theta), Math.sin(angle) * Math.sin(theta), Math.cos(angle));
+                const travel = preview / Math.max(Math.cos(angle), 0.05);
+                lines(`wf-cone-ray-${i}`, [rim, rim.add(dir.scale(travel))], DIRECTION_COLOR);
+            }
+            lines('wf-cone-far', xyArc(farRadius, arc, 32, preview), DIRECTION_COLOR);
+            break;
+        }
+        case 'sphere': {
+            // Spawn on spherical shell/volume; velocity radial from center.
+            const radius = Math.max(params.radius, 0.001);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            drawSphereShell(lines, 'wf-sphere', radius, arc);
+            if (thickness < 1) {
+                drawSphereShell(lines, 'wf-sphere-inner', radius * (1 - thickness), arc);
+            }
+            break;
+        }
+        case 'hemisphere': {
+            // Spawn on +Z hemisphere (phi 0..π/2): flat on XY through origin, dome toward +Z.
+            const radius = Math.max(params.radius, 0.001);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            drawHemisphereShell(lines, 'wf-hemi', radius, arc);
+            lines('wf-hemi-base', xyArc(radius, arc));
+            if (thickness < 1) {
+                drawHemisphereShell(lines, 'wf-hemi-inner', radius * (1 - thickness), arc);
+                lines('wf-hemi-base-inner', xyArc(radius * (1 - thickness), arc));
+            }
+            break;
+        }
+        case 'circle': {
+            // Spawn on circle/ring in XY; velocity radial in XY.
+            const radius = Math.max(params.radius, 0.001);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            lines('wf-circle', xyArc(radius, arc));
+            if (thickness < 1) {
+                lines('wf-circle-inner', xyArc(radius * (1 - thickness), arc));
+            }
+            if (arc < Math.PI * 2 - 1e-3) {
+                lines('wf-circle-spoke-a', [Vector3.Zero(), arcPoint(radius, 0)]);
+                lines('wf-circle-spoke-b', [Vector3.Zero(), arcPoint(radius, arc)]);
+            }
+            break;
+        }
+        case 'donut': {
+            // Spawn on torus: major ring of `radius` in XY, tube radius `donutRadius`.
+            const radius = Math.max(params.radius, 0.001);
+            const tube = Math.max(params.donutRadius, 0.001);
+            const arc = clampArc(params.arc);
+            const thickness = clamp01(params.thickness);
+            lines('wf-donut-major', xyArc(radius, arc));
+            lines('wf-donut-outer', xyArc(radius + tube, arc));
+            lines('wf-donut-inner', xyArc(Math.max(radius - tube, 0), arc));
+            if (thickness < 1) {
+                lines('wf-donut-tube-inner', xyArc(radius + tube * (1 - thickness), arc));
+            }
+            const tubeSamples = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 8));
+            for (let i = 0; i <= tubeSamples; i++) {
+                const theta = (i / tubeSamples) * arc;
+                lines(`wf-donut-tube-${i}`, torusTubeRing(radius, tube, theta));
+            }
+            break;
+        }
+        case 'rectangle': {
+            // Spawn on rectangle perimeter (thickness fills toward center); velocity outward in XY.
+            const thickness = clamp01(params.thickness);
+            lines('wf-rect', xyRect(params.width, params.height));
+            if (thickness > 0 && thickness < 1) {
+                lines('wf-rect-inner', xyRect(params.width * (1 - thickness), params.height * (1 - thickness)));
+            }
+            break;
+        }
+        case 'grid': {
+            // Discrete spawn cells in XY; velocity straight +Z.
+            const cols = Math.max(1, Math.floor(params.column));
+            const rows = Math.max(1, Math.floor(params.row));
+            const halfW = params.width / 2;
+            const halfH = params.height / 2;
+            lines('wf-grid-border', xyRect(params.width, params.height));
+            const mark = Math.min(params.width / cols, params.height / rows, 0.12) * 0.35;
+            const ray = Math.max(mark * 4, 0.25);
+            for (let c = 0; c < cols; c++) {
+                for (let r = 0; r < rows; r++) {
+                    const x = (c * params.width) / cols - halfW;
+                    const y = (r * params.height) / rows - halfH;
+                    const p = new Vector3(x, y, 0);
+                    lines(`wf-grid-x-${c}-${r}`, [new Vector3(x - mark, y, 0), new Vector3(x + mark, y, 0)]);
+                    lines(`wf-grid-y-${c}-${r}`, [new Vector3(x, y - mark, 0), new Vector3(x, y + mark, 0)]);
+                    lines(`wf-grid-ray-${c}-${r}`, [p, new Vector3(x, y, ray)], DIRECTION_COLOR);
+                }
+            }
+            break;
+        }
+        case 'mesh_surface': {
+            const source = params.mesh;
+            if (source && !source.isDisposed()) {
+                const positions = source.getVerticesData('position');
+                const indices = source.getIndices();
+                if (positions && indices && indices.length >= 3) {
+                    const edgeSet = new Set<string>();
+                    const pushEdge = (a: number, b: number) => {
+                        const key = a < b ? `${a}_${b}` : `${b}_${a}`;
+                        if (edgeSet.has(key)) {
+                            return;
+                        }
+                        edgeSet.add(key);
+                        lines(`wf-mesh-e-${key}`, [
+                            new Vector3(positions[a * 3], positions[a * 3 + 1], positions[a * 3 + 2]),
+                            new Vector3(positions[b * 3], positions[b * 3 + 1], positions[b * 3 + 2]),
+                        ]);
+                    };
+                    const maxTris = Math.min(indices.length / 3, 400);
+                    for (let t = 0; t < maxTris; t++) {
+                        const i = t * 3;
+                        pushEdge(indices[i], indices[i + 1]);
+                        pushEdge(indices[i + 1], indices[i + 2]);
+                        pushEdge(indices[i + 2], indices[i]);
+                    }
+                } else {
+                    lines('wf-mesh-missing', xyRect(0.6, 0.6));
+                }
+            } else {
+                lines('wf-mesh-missing', xyRect(0.6, 0.6));
+            }
+            break;
+        }
+        default:
+            break;
+    }
+
+    return meshes;
+}
+
+type LineFn = (name: string, points: Vector3[], color?: Color3) => void;
+
+function drawSphereShell(lines: LineFn, prefix: string, radius: number, arc: number): void {
+    // Latitude rings + longitude arcs matching spherical spawn (theta around Z via arc).
+    const latCount = 4;
+    for (let i = 1; i < latCount; i++) {
+        const phi = (i / latCount) * Math.PI;
+        const ringR = radius * Math.sin(phi);
+        const z = radius * Math.cos(phi);
+        lines(`${prefix}-lat-${i}`, xyArc(ringR, arc, 48, z));
+    }
+    const lonCount = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 8));
+    for (let i = 0; i <= lonCount; i++) {
+        const theta = (i / lonCount) * arc;
+        const points: Vector3[] = [];
+        for (let j = 0; j <= 16; j++) {
+            const phi = (j / 16) * Math.PI;
+            points.push(
+                new Vector3(
+                    radius * Math.sin(phi) * Math.cos(theta),
+                    radius * Math.sin(phi) * Math.sin(theta),
+                    radius * Math.cos(phi)
+                )
+            );
+        }
+        lines(`${prefix}-lon-${i}`, points);
+    }
+}
+
+function drawHemisphereShell(lines: LineFn, prefix: string, radius: number, arc: number): void {
+    // Quarks: phi = acos(v) ∈ [0, π/2] → z = cos(phi) ∈ [0, 1].
+    const latCount = 3;
+    for (let i = 1; i <= latCount; i++) {
+        const phi = (i / (latCount + 1)) * (Math.PI / 2);
+        const ringR = radius * Math.sin(phi);
+        const z = radius * Math.cos(phi);
+        lines(`${prefix}-lat-${i}`, xyArc(ringR, arc, 32, z));
+    }
+    const lonCount = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 8));
+    for (let i = 0; i <= lonCount; i++) {
+        const theta = (i / lonCount) * arc;
+        const points: Vector3[] = [new Vector3(0, 0, radius)];
+        for (let j = 1; j <= 12; j++) {
+            const phi = (j / 12) * (Math.PI / 2);
+            points.push(
+                new Vector3(
+                    radius * Math.sin(phi) * Math.cos(theta),
+                    radius * Math.sin(phi) * Math.sin(theta),
+                    radius * Math.cos(phi)
+                )
+            );
+        }
+        lines(`${prefix}-lon-${i}`, points);
+    }
+}
+
+function torusTubeRing(major: number, tube: number, theta: number): Vector3[] {
+    const cos = Math.cos(theta);
+    const sin = Math.sin(theta);
+    const points: Vector3[] = [];
+    for (let i = 0; i <= 16; i++) {
+        const phi = (i / 16) * Math.PI * 2;
+        points.push(
+            new Vector3(
+                (major + tube * Math.cos(phi)) * cos,
+                (major + tube * Math.cos(phi)) * sin,
+                tube * Math.sin(phi)
+            )
+        );
+    }
+    return points;
+}
+
+function xyArc(radius: number, arc: number, segments = 48, z = 0): Vector3[] {
+    const points: Vector3[] = [];
+    const steps = Math.max(8, Math.ceil(segments * (arc / (Math.PI * 2))));
+    for (let i = 0; i <= steps; i++) {
+        points.push(arcPoint(radius, (i / steps) * arc, z));
+    }
+    return points;
+}
+
+function arcPoint(radius: number, theta: number, z = 0): Vector3 {
+    return new Vector3(Math.cos(theta) * radius, Math.sin(theta) * radius, z);
+}
+
+function xyRect(width: number, height: number): Vector3[] {
+    const halfW = width / 2;
+    const halfH = height / 2;
+    return [
+        new Vector3(-halfW, -halfH, 0),
+        new Vector3(halfW, -halfH, 0),
+        new Vector3(halfW, halfH, 0),
+        new Vector3(-halfW, halfH, 0),
+        new Vector3(-halfW, -halfH, 0),
+    ];
+}
+
+function clampArc(arc: number): number {
+    if (!Number.isFinite(arc) || arc <= 0) {
+        return Math.PI * 2;
+    }
+    return Math.min(Math.PI * 2, arc);
+}
+
+function clamp01(value: number): number {
+    if (!Number.isFinite(value)) {
+        return 1;
+    }
+    return Math.min(1, Math.max(0, value));
+}

package/src/core/galleryDragSession.ts

@@ -0,0 +1,12 @@
+import type {GalleryDragPayload} from './galleryTree';
+
+let activeDrag: GalleryDragPayload | null = null;
+
+/** Stores the current gallery drag payload for viewport preview (getData is drop-only in most browsers). */
+export function setGalleryDragSession(payload: GalleryDragPayload | null): void {
+    activeDrag = payload;
+}
+
+export function getGalleryDragSession(): GalleryDragPayload | null {
+    return activeDrag;
+}

package/src/core/galleryDropMarker.ts

@@ -0,0 +1,57 @@
+import {Color3} from '@babylonjs/core/Maths/math.color';
+import {Vector3} from '@babylonjs/core/Maths/math.vector';
+import {StandardMaterial} from '@babylonjs/core/Materials/standardMaterial';
+import {Mesh} from '@babylonjs/core/Meshes/mesh';
+import {MeshBuilder} from '@babylonjs/core/Meshes/meshBuilder';
+import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {Scene} from '@babylonjs/core/scene';
+import {DEFAULT_GALLERY_SPACING, gallerySpan} from './galleryLayout';
+
+/** Ground decal shown while dragging gallery items over the viewport. */
+export class GalleryDropMarker {
+    private readonly root: TransformNode;
+    private readonly disc: Mesh;
+    private readonly material: StandardMaterial;
+
+    constructor(scene: Scene) {
+        this.root = new TransformNode('gallery-drop-root', scene);
+        this.disc = MeshBuilder.CreateDisc('gallery-drop-fill', {radius: 1, tessellation: 48, sideOrientation: Mesh.DOUBLESIDE}, scene);
+        this.disc.parent = this.root;
+        this.disc.rotation.x = Math.PI / 2;
+
+        this.material = new StandardMaterial('gallery-drop-fill-mat', scene);
+        this.material.emissiveColor = new Color3(0.35, 0.55, 1);
+        this.material.alpha = 0.24;
+        this.material.disableLighting = true;
+        this.material.backFaceCulling = false;
+
+        this.disc.material = this.material;
+        this.disc.isPickable = false;
+        this.disc.renderingGroupId = 1;
+        this.hide();
+    }
+
+    /** Positions the marker for a single effect or a folder grid footprint. */
+    show(position: Vector3, effectCount: number, spacing = DEFAULT_GALLERY_SPACING): void {
+        const span = Math.max(gallerySpan(effectCount, spacing), spacing);
+        const radius = Math.max(0.375, span * 0.25 + spacing * 0.175);
+
+        this.root.position.set(position.x, 0.03, position.z);
+        this.root.scaling.set(radius, radius, radius);
+
+        this.material.alpha = effectCount > 1 ? 0.16 : 0.24;
+        this.material.emissiveColor = effectCount > 1 ? new Color3(0.45, 0.9, 0.75) : new Color3(0.55, 0.78, 1);
+
+        this.root.setEnabled(true);
+    }
+
+    hide(): void {
+        this.root.setEnabled(false);
+    }
+
+    dispose(): void {
+        this.material.dispose();
+        this.disc.dispose();
+        this.root.dispose();
+    }
+}

package/src/core/galleryLayout.ts

@@ -0,0 +1,90 @@
+import type {ArcRotateCamera} from '@babylonjs/core/Cameras/arcRotateCamera';
+import {Vector3} from '@babylonjs/core/Maths/math.vector';
+import type {Mesh} from '@babylonjs/core/Meshes/mesh';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+
+/** Default gap between neighbouring effects in a folder gallery import. */
+export const DEFAULT_GALLERY_SPACING = 4;
+
+/** Square-grid column count for `count` items. */
+export function galleryColumnCount(count: number): number {
+    return Math.max(1, Math.ceil(Math.sqrt(count)));
+}
+
+/** World X/Z offset for the `index`th effect in a square grid. */
+export function galleryGridPosition(
+    index: number,
+    count: number,
+    spacing = DEFAULT_GALLERY_SPACING
+): {x: number; z: number} {
+    const cols = galleryColumnCount(count);
+    const rows = Math.ceil(count / cols);
+    const col = index % cols;
+    const row = Math.floor(index / cols);
+    return {
+        x: (col - (cols - 1) / 2) * spacing,
+        z: (row - (rows - 1) / 2) * spacing,
+    };
+}
+
+/** Longest side of the grid footprint in world units. */
+export function gallerySpan(count: number, spacing = DEFAULT_GALLERY_SPACING): number {
+    const cols = galleryColumnCount(count);
+    const rows = Math.ceil(count / cols);
+    return Math.max((cols - 1) * spacing, (rows - 1) * spacing, spacing);
+}
+
+/** Pulls the camera back and scales the ground plane to frame a gallery grid. */
+export function fitGalleryView(
+    camera: ArcRotateCamera,
+    ground: Mesh,
+    count: number,
+    spacing = DEFAULT_GALLERY_SPACING
+): void {
+    const span = gallerySpan(count, spacing);
+    camera.setTarget(new Vector3(0, 1.4, 0));
+    camera.radius = Math.max(span * 0.85, 12);
+    camera.beta = Math.min(camera.beta, 1.1);
+    const groundSize = Math.max(span + spacing * 4, 100);
+    ground.scaling.x = groundSize / 100;
+    ground.scaling.z = groundSize / 100;
+}
+
+let cameraFocusFrame = 0;
+
+function easeOutCubic(t: number): number {
+    return 1 - (1 - t) ** 3;
+}
+
+/** Stops an in-flight gallery camera focus animation. */
+export function cancelGalleryCameraFocus(): void {
+    if (cameraFocusFrame) {
+        cancelAnimationFrame(cameraFocusFrame);
+        cameraFocusFrame = 0;
+    }
+}
+
+/** Smoothly frames the camera on an in-scene gallery effect. */
+export function focusGalleryEntry(camera: ArcRotateCamera, entryRoot: TransformNode, durationMs = 450): void {
+    cancelGalleryCameraFocus();
+
+    const pos = entryRoot.getAbsolutePosition();
+    const target = new Vector3(pos.x, pos.y + 1.4, pos.z);
+    const startTarget = camera.target.clone();
+    const startRadius = camera.radius;
+    const jumpDist = Vector3.Distance(startTarget, target);
+    const desiredRadius = jumpDist > 3 ? 12 : Math.min(startRadius, 16);
+    const start = performance.now();
+
+    const tick = () => {
+        const t = easeOutCubic(Math.min(1, (performance.now() - start) / durationMs));
+        camera.setTarget(Vector3.Lerp(startTarget, target, t));
+        camera.radius = startRadius + (desiredRadius - startRadius) * t;
+        if (t < 1) {
+            cameraFocusFrame = requestAnimationFrame(tick);
+        } else {
+            cameraFocusFrame = 0;
+        }
+    };
+    cameraFocusFrame = requestAnimationFrame(tick);
+}