babylon.quarks-editor 0.17.7 → 0.17.9

package/dist/react/theme.js

@@ -42,10 +42,22 @@ export const buttonStyle = {
     color: '#d8e3ff',
     padding: '6px 10px',
     borderRadius: 8,
-    fontSize: 12.5,
     cursor: 'pointer',
+    fontSize: 12.5,
     fontFamily: theme.font,
 };
+/** Visually hides a file input while keeping it activatable via an associated <label>. */
+export const hiddenFileInputStyle = {
+    position: 'absolute',
+    width: 1,
+    height: 1,
+    padding: 0,
+    margin: -1,
+    overflow: 'hidden',
+    clip: 'rect(0, 0, 0, 0)',
+    whiteSpace: 'nowrap',
+    border: 0,
+};
 /**
  * Two hover conventions, applied via className (inline `style` can't express `:hover`):
  * - `qe-hover` — brightens elements that already have a solid inline background/border
@@ -54,25 +66,88 @@ export const buttonStyle = {
  *   rows), since brightening transparent does nothing. Must not be combined with an inline
  *   `background` on the same element or the tint would need `!important` to show through.
  */
-export const globalEditorStyles = `
-.qe-hover, .qe-hover-bg {
-    transition: filter 0.12s ease, background 0.12s ease;
-}
-.qe-hover:hover:not(:disabled) {
-    filter: brightness(1.3);
-}
-.qe-hover:active:not(:disabled) {
-    filter: brightness(0.85);
-}
-.qe-hover:disabled {
-    opacity: 0.45;
-    cursor: default;
-}
-.qe-hover-bg:hover {
-    background: rgba(255, 255, 255, 0.07);
-}
-select.qe-hover:hover, input.qe-hover:hover, select.qe-hover:focus, input.qe-hover:focus {
-    border-color: ${theme.borderActive};
-    filter: none;
-}
+export const globalEditorStyles = `
+.qe-hover, .qe-hover-bg {
+    transition: filter 0.12s ease, background 0.12s ease;
+}
+.qe-hover:hover:not(:disabled) {
+    filter: brightness(1.3);
+}
+.qe-hover:active:not(:disabled) {
+    filter: brightness(0.85);
+}
+.qe-hover:disabled {
+    opacity: 0.45;
+    cursor: default;
+}
+.qe-hover-bg:hover {
+    background: rgba(255, 255, 255, 0.07);
+}
+select.qe-hover:hover, input.qe-hover:hover, select.qe-hover:focus, input.qe-hover:focus {
+    border-color: ${theme.borderActive};
+    filter: none;
+}
+.qe-root, .qe-root * {
+    scrollbar-width: thin;
+    scrollbar-color: ${theme.border} transparent;
+}
+.qe-root ::-webkit-scrollbar {
+    width: 10px;
+    height: 10px;
+}
+.qe-root ::-webkit-scrollbar-track {
+    background: transparent;
+}
+.qe-root ::-webkit-scrollbar-thumb {
+    background-color: ${theme.border};
+    background-clip: padding-box;
+    border: 2px solid transparent;
+    border-radius: 8px;
+}
+.qe-root ::-webkit-scrollbar-thumb:hover {
+    background-color: ${theme.borderActive};
+}
+.qe-root ::-webkit-scrollbar-corner {
+    background: transparent;
+}
+.qe-tooltip {
+    z-index: 100000;
+    padding: 8px 10px;
+    font-size: 11.5px;
+    line-height: 1.45;
+    color: ${theme.text};
+    background: linear-gradient(180deg, rgba(18, 26, 52, 0.98), rgba(8, 12, 26, 0.98));
+    border: 1px solid ${theme.borderActive};
+    border-radius: 8px;
+    box-shadow: 0 10px 28px rgba(0, 0, 0, 0.45);
+    pointer-events: none;
+    font-family: ${theme.font};
+    animation: qe-tooltip-in 0.12s ease;
+}
+.qe-tooltip--right::before,
+.qe-tooltip--left::before {
+    content: '';
+    position: absolute;
+    top: 50%;
+    width: 0;
+    height: 0;
+    border: 5px solid transparent;
+    transform: translateY(-50%);
+}
+.qe-tooltip--right::before {
+    left: -10px;
+    border-right-color: ${theme.borderActive};
+}
+.qe-tooltip--left::before {
+    right: -10px;
+    border-left-color: ${theme.borderActive};
+}
+@keyframes qe-tooltip-in {
+    from {
+        opacity: 0;
+    }
+    to {
+        opacity: 1;
+    }
+}
 `;

package/package.json

@@ -1,63 +1,72 @@
-{
-  "name": "babylon.quarks-editor",
-  "version": "0.17.7",
-  "description": "Shuriken-style effect editor for babylon.quarks: headless edit-model core + React module-stack UI",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./react": {
-      "import": "./dist/react/index.js",
-      "types": "./dist/react/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "src",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "clean": "rimraf dist",
-    "build": "npm run clean && tsc -p tsconfig.json"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Soullnik/babylon.quarks-standalone.git"
-  },
-  "keywords": [
-    "babylonjs",
-    "particles",
-    "vfx",
-    "editor",
-    "react",
-    "quarks"
-  ],
-  "author": "soullnik <soullnik96@gmail.com>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/Soullnik/babylon.quarks-standalone/issues"
-  },
-  "homepage": "https://github.com/Soullnik/babylon.quarks-standalone#readme",
-  "peerDependencies": {
-    "@babylonjs/core": ">=9.0.0",
-    "@babylonjs/materials": ">=9.0.0",
-    "babylon.quarks": ">=0.17.0",
-    "react": ">=18",
-    "react-dom": ">=18"
-  },
-  "devDependencies": {
-    "@babylonjs/materials": "9.6.2",
-    "@types/react": "^19.0.0",
-    "react": "^19.0.0",
-    "rimraf": "^6.0.0",
-    "typescript": "^5.9.3",
-    "react-dom": "^19.0.0",
-    "@types/react-dom": "^19.0.0"
-  }
-}
+{
+  "name": "babylon.quarks-editor",
+  "version": "0.17.9",
+  "description": "Shuriken-style effect editor for babylon.quarks: headless edit-model core + React module-stack UI",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc -p tsconfig.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Soullnik/babylon.quarks-standalone.git"
+  },
+  "keywords": [
+    "babylonjs",
+    "babylon.js",
+    "particles",
+    "particle-system",
+    "particle-editor",
+    "vfx",
+    "vfx-editor",
+    "shuriken",
+    "editor",
+    "react",
+    "quarks"
+  ],
+  "author": "soullnik <soullnik96@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Soullnik/babylon.quarks-standalone/issues"
+  },
+  "homepage": "https://github.com/Soullnik/babylon.quarks-standalone#readme",
+  "peerDependencies": {
+    "@babylonjs/core": ">=9.0.0",
+    "@babylonjs/materials": ">=9.0.0",
+    "@heroicons/react": ">=2.0.0",
+    "@tanstack/react-virtual": ">=3.0.0",
+    "babylon.quarks": ">=0.17.0",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@babylonjs/materials": "9.6.2",
+    "@heroicons/react": "^2.2.0",
+    "@tanstack/react-virtual": "^3.14.6",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/core/binding.ts

@@ -1,105 +1,102 @@
-import type {ParticleSystem} from 'babylon.quarks';
-import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
-import {buildEffectTree, serializeEffectTree} from './effectTree';
-import type {EffectTreeNode} from './effectTree';
-
-export type EditorListener = () => void;
-
-/**
- * Headless edit-model over a live ParticleSystem: mutate through apply() so every
- * change notifies subscribers (React UI, save indicators, hosts like BabylonJS Editor).
- */
-export class EffectBinding {
-    /** Not `readonly` — `promoteToMain` reassigns this when the current main system is removed. */
-    system: ParticleSystem;
-    /** Systems spawned by sub-emitter behaviors; serialized as children of the root emitter. */
-    readonly subSystems: ParticleSystem[] = [];
-    /** Loaded scene root of the whole effect (Group tree); defaults to the system's emitter. */
-    readonly root: TransformNode;
-    /** Invoked before any mutation — used by EffectHistory to capture undo snapshots. */
-    onBeforeChange?: () => void;
-    private listeners = new Set<EditorListener>();
-    private revision = 0;
-
-    constructor(system: ParticleSystem, subSystems: ParticleSystem[] = [], root?: TransformNode) {
-        this.system = system;
-        this.subSystems.push(...subSystems);
-        this.root = root ?? system.emitter;
-    }
-
-    /** Editor hierarchy tree (groups + emitters) rooted at this effect's scene root. */
-    getTree(): EffectTreeNode {
-        return buildEffectTree(this.root);
-    }
-
-    subscribe(listener: EditorListener): () => void {
-        this.listeners.add(listener);
-        return () => this.listeners.delete(listener);
-    }
-
-    /** Monotonic change counter, usable as a React external-store snapshot. */
-    getRevision(): number {
-        return this.revision;
-    }
-
-    apply(mutate: (system: ParticleSystem) => void): void {
-        this.onBeforeChange?.();
-        mutate(this.system);
-        this.notify();
-    }
-
-    addSubSystem(sub: ParticleSystem): void {
-        this.subSystems.push(sub);
-        this.notify();
-    }
-
-    removeSubSystem(sub: ParticleSystem): void {
-        const index = this.subSystems.indexOf(sub);
-        if (index >= 0) {
-            this.subSystems.splice(index, 1);
-        }
-        this.notify();
-    }
-
-    /**
-     * Swaps which system is "main" — used when the current `system` is about to be removed
-     * but other top-level systems remain. Being "main" vs. a sub-system is otherwise
-     * meaningless to the effect itself (both play/restart/export the same way); it only
-     * exists so there's always a designated fallback system to select.
-     */
-    promoteToMain(next: ParticleSystem): void {
-        const index = this.subSystems.indexOf(next);
-        if (index < 0) {
-            return;
-        }
-        this.subSystems.splice(index, 1, this.system);
-        this.system = next;
-        this.notify();
-    }
-
-    private notify(): void {
-        this.revision++;
-        for (const listener of this.listeners) {
-            listener();
-        }
-    }
-
-    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.
-        for (const system of [this.system, ...this.subSystems]) {
-            system.restart();
-            if (!system.onlyUsedByOther) {
-                system.play();
-            }
-        }
-    }
-
-    /**
-     * Serializes the effect into the Quarks JSON envelope understood by QuarksLoader,
-     * preserving the loaded group/emitter hierarchy.
-     */
-    exportJSON(name = 'effect'): string {
-        return serializeEffectTree(this.root, name);
-    }
-}
+import type {ParticleSystem} from 'babylon.quarks';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import {buildEffectTree, serializeEffectTree} from './effectTree';
+import type {EffectTreeNode} from './effectTree';
+
+export type EditorListener = () => void;
+
+/**
+ * Headless edit-model over a live ParticleSystem: mutate through apply() so every
+ * change notifies subscribers (React UI, save indicators, hosts like BabylonJS Editor).
+ */
+export class EffectBinding {
+    /** Not `readonly` — `promoteToMain` reassigns this when the current main system is removed. */
+    system: ParticleSystem;
+    /** Systems spawned by sub-emitter behaviors; serialized as children of the root emitter. */
+    readonly subSystems: ParticleSystem[] = [];
+    /** Loaded scene root of the whole effect (Group tree); defaults to the system's emitter. */
+    readonly root: TransformNode;
+    /** Invoked before any mutation — used by EffectHistory to capture undo snapshots. */
+    onBeforeChange?: () => void;
+    private listeners = new Set<EditorListener>();
+    private revision = 0;
+
+    constructor(system: ParticleSystem, subSystems: ParticleSystem[] = [], root?: TransformNode) {
+        this.system = system;
+        this.subSystems.push(...subSystems);
+        this.root = root ?? system.emitter;
+    }
+
+    /** Editor hierarchy tree (groups + emitters) rooted at this effect's scene root. */
+    getTree(): EffectTreeNode {
+        return buildEffectTree(this.root);
+    }
+
+    subscribe(listener: EditorListener): () => void {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+
+    /** Monotonic change counter, usable as a React external-store snapshot. */
+    getRevision(): number {
+        return this.revision;
+    }
+
+    apply(mutate: (system: ParticleSystem) => void): void {
+        this.onBeforeChange?.();
+        mutate(this.system);
+        this.notify();
+    }
+
+    addSubSystem(sub: ParticleSystem): void {
+        this.subSystems.push(sub);
+        this.notify();
+    }
+
+    removeSubSystem(sub: ParticleSystem): void {
+        const index = this.subSystems.indexOf(sub);
+        if (index >= 0) {
+            this.subSystems.splice(index, 1);
+        }
+        this.notify();
+    }
+
+    /**
+     * Swaps which system is "main" — used when the current `system` is about to be removed
+     * but other top-level systems remain. Being "main" vs. a sub-system is otherwise
+     * meaningless to the effect itself (both play/restart/export the same way); it only
+     * exists so there's always a designated fallback system to select.
+     */
+    promoteToMain(next: ParticleSystem): void {
+        const index = this.subSystems.indexOf(next);
+        if (index < 0) {
+            return;
+        }
+        this.subSystems.splice(index, 1, this.system);
+        this.system = next;
+        this.notify();
+    }
+
+    private notify(): void {
+        this.revision++;
+        for (const listener of this.listeners) {
+            listener();
+        }
+    }
+
+    restart(): void {
+        // onlyUsedByOther systems skip self-emission in update(); play() only unpauses sim.
+        for (const system of [this.system, ...this.subSystems]) {
+            system.restart();
+            system.play();
+        }
+    }
+
+    /**
+     * Serializes the effect into the Quarks JSON envelope understood by QuarksLoader,
+     * preserving the loaded group/emitter hierarchy.
+     */
+    exportJSON(name = 'effect'): string {
+        return serializeEffectTree(this.root, name);
+    }
+}

package/src/core/collision.ts

@@ -1,40 +1,40 @@
-import {Vector3, getPhysicsResolver, setPhysicsResolver} from 'babylon.quarks';
-
-/**
- * A horizontal ground plane collider. quarks.core's ApplyCollision behavior delegates to a
- * host-provided `PhysicsResolver` (a global singleton) and ships no collider primitive of its
- * own, so the editor supplies this — the common "particles bounce off the floor" case.
- *
- * `resolve` returns true and fills the surface normal when the point is at or below the plane,
- * which is exactly what ApplyCollision.update reflects the velocity against.
- */
-export class GroundPlaneResolver {
-    constructor(public y = 0) {}
-
-    resolve(position: Vector3, normal: Vector3): boolean {
-        if (position.y <= this.y) {
-            normal.set(0, 1, 0);
-            return true;
-        }
-        return false;
-    }
-}
-
-/**
- * Registers (once) a shared ground-plane resolver so ApplyCollision behaviors — whether added
- * in the inspector or deserialized from imported JSON — have something to collide against.
- * Idempotent: an already-registered resolver is left untouched and returned.
- */
-export function ensureGroundResolver(): GroundPlaneResolver {
-    const existing = getPhysicsResolver();
-    if (existing instanceof GroundPlaneResolver) {
-        return existing;
-    }
-    if (existing) {
-        // A host registered its own resolver; don't clobber it, but we can't tweak its floor.
-        return existing as GroundPlaneResolver;
-    }
-    const resolver = new GroundPlaneResolver(0);
-    setPhysicsResolver(resolver);
-    return resolver;
-}
+import {Vector3, getPhysicsResolver, setPhysicsResolver} from 'babylon.quarks';
+
+/**
+ * A horizontal ground plane collider. quarks.core's ApplyCollision behavior delegates to a
+ * host-provided `PhysicsResolver` (a global singleton) and ships no collider primitive of its
+ * own, so the editor supplies this — the common "particles bounce off the floor" case.
+ *
+ * `resolve` returns true and fills the surface normal when the point is at or below the plane,
+ * which is exactly what ApplyCollision.update reflects the velocity against.
+ */
+export class GroundPlaneResolver {
+    constructor(public y = 0) {}
+
+    resolve(position: Vector3, normal: Vector3): boolean {
+        if (position.y <= this.y) {
+            normal.set(0, 1, 0);
+            return true;
+        }
+        return false;
+    }
+}
+
+/**
+ * Registers (once) a shared ground-plane resolver so ApplyCollision behaviors — whether added
+ * in the inspector or deserialized from imported JSON — have something to collide against.
+ * Idempotent: an already-registered resolver is left untouched and returned.
+ */
+export function ensureGroundResolver(): GroundPlaneResolver {
+    const existing = getPhysicsResolver();
+    if (existing instanceof GroundPlaneResolver) {
+        return existing;
+    }
+    if (existing) {
+        // A host registered its own resolver; don't clobber it, but we can't tweak its floor.
+        return existing as GroundPlaneResolver;
+    }
+    const resolver = new GroundPlaneResolver(0);
+    setPhysicsResolver(resolver);
+    return resolver;
+}

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));
         }
     }