babylon.quarks-editor 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to the `babylon.quarks-editor` package are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project follows the `quarks.core` 0.x version line.
 
+## [0.20.0] — 2026-10-16
+
+### Added
+
+- **Projects**: a start page lists the projects saved in IndexedDB (new, rename, duplicate,
+  delete), with storage usage and a "make storage persistent" button. `ProjectStore` with an
+  `IndexedDbProjectStore` default keeps each texture once per project by content hash. The scene
+  is saved explicitly (Save / Ctrl+S, `*` while unsaved), and assets are written as they change.
+- **Scene and Assets panels**: the Scene panel lists only the effects placed in the viewport
+  (show/hide, solo, delete, "Save as new asset…"), and the Assets drawer holds the library.
+- **Prefab mode**: open an asset to edit it on its own, with the scene set aside. Double-clicking
+  another asset swaps it in place, asking Save / Don't save / Cancel when there are unsaved edits.
+- **Effect tree** in the Scene and prefab panels: each effect unfolds into its group/emitter tree,
+  and clicking a node selects it for the inspector and gizmo, sub-emitters included, without
+  opening the timeline.
+
+### Changed
+
+- Selecting a node no longer stalls the viewport: the inspector renders after the selection
+  instead of in the same frame, cutting main-thread blocking per switch from ~50 ms to ~15–19 ms.
+
+### Fixed
+
+- The camera renders only above the floating Assets drawer, so a focused effect or an opened
+  prefab is centred where it can be seen.
+- Selection rings rendered nothing under Vite's dev server: the color shaders they use are now
+  registered up front instead of being fetched at runtime.
+
 ## [0.17.9] — 2026-07-14
 
 ### Added

package/README.md

@@ -13,17 +13,17 @@ npm install babylon.quarks-editor babylon.quarks @babylonjs/core react @heroicon
 ## Usage
 
 ```tsx
-import {EffectBinding, EffectHistory} from "babylon.quarks-editor";
-import {EffectEditor} from "babylon.quarks-editor/react";
+import {EffectBinding, EffectHistory} from 'babylon.quarks-editor';
+import {EffectEditor} from 'babylon.quarks-editor/react';
 
-const binding = new EffectBinding(particleSystem);   // your babylon.quarks ParticleSystem
+const binding = new EffectBinding(particleSystem); // your babylon.quarks ParticleSystem
 const history = new EffectHistory();
 history.attach(binding);
 
 <EffectEditor binding={binding} />;
 
 // Serialize to Quarks JSON (round-trips through QuarksLoader):
-const json = binding.exportJSON("MyEffect");
+const json = binding.exportJSON('MyEffect');
 ```
 
 Modules: Main, Emission (bursts), Shape (7 emitter types), Speed/Limit Speed/Force/Rotation over Lifetime, Gravity, Color over Lifetime (gradient), Size over Lifetime (curve), Noise, Sub Emitters, Texture Sheet Animation, Renderer. Multi-system hierarchy with add/remove/rename, undo/redo via `EffectHistory`.
@@ -39,9 +39,9 @@ an opinion on your CDN, asset pipeline, or loader (`@babylonjs/loaders`, your ow
   "Load from file…" in the Renderer module) into whatever object you assign as `system.texture`.
 - `resolveGeometry(file) => Promise<GeometryData>` — turns a picked file (from "Load from file…"
   in the Mesh render mode's geometry dropdown) into vertex buffers: `{positions, indices?, uvs?,
-  normals?}` (typed arrays or plain number arrays).
+normals?}` (typed arrays or plain number arrays).
 - `textureOptions?: {label, url}[]` / `geometryOptions?: {label, positions, indices?, uvs?,
-  normals?}[]` — preset lists shown alongside "Custom URL…" / "Load from file…".
+normals?}[]` — preset lists shown alongside "Custom URL…" / "Load from file…".
 
 **Signature differs by entry point** — a common source of "works in the demo, throws in my
 host" bugs:

package/dist/core/assetDragSession.d.ts

@@ -0,0 +1,4 @@
+import type { AssetDragPayload } from './assetTree';
+/** Stores the current asset drag payload for viewport preview (getData is drop-only in most browsers). */
+export declare function setAssetDragSession(payload: AssetDragPayload | null): void;
+export declare function getAssetDragSession(): AssetDragPayload | null;

package/dist/core/assetDragSession.js

@@ -0,0 +1,8 @@
+let activeDrag = null;
+/** Stores the current asset drag payload for viewport preview (getData is drop-only in most browsers). */
+export function setAssetDragSession(payload) {
+    activeDrag = payload;
+}
+export function getAssetDragSession() {
+    return activeDrag;
+}

package/dist/core/assetTree.d.ts

@@ -0,0 +1,39 @@
+import type { EffectAsset } from './assets';
+export interface AssetTreeFolder {
+    kind: 'folder';
+    name: string;
+    path: string;
+    children: AssetTreeNode[];
+}
+export interface AssetTreeEffect {
+    kind: 'asset';
+    name: string;
+    path: string;
+    asset: EffectAsset;
+}
+export type AssetTreeNode = AssetTreeFolder | AssetTreeEffect;
+/** Builds a folder tree from asset relative paths (e.g. `VFX/Fire/Explosion.json`). */
+export declare function buildAssetTree(assets: EffectAsset[]): AssetTreeNode[];
+/** Children of the folder at `path` (`''` is the top level), or null when it no longer exists. */
+export declare function folderChildren(tree: AssetTreeNode[], path: string): AssetTreeNode[] | null;
+/** Assets whose name or path contains `query`, across every folder, sorted by name. */
+export declare function searchAssets(assets: EffectAsset[], query: string): EffectAsset[];
+export declare const ASSET_DRAG_MIME = "application/x-quarks-asset-drop";
+export type AssetDragPayload = {
+    kind: 'asset';
+    id: number;
+} | {
+    kind: 'folder';
+    path: string;
+};
+export declare function writeAssetDrag(dataTransfer: DataTransfer, payload: AssetDragPayload): void;
+export declare function readAssetDrag(dataTransfer: DataTransfer): AssetDragPayload | null;
+/** Returns every asset whose JSON path sits inside `folderPath` (recursive). */
+export declare function collectAssetsInFolder(assets: EffectAsset[], folderPath: string): EffectAsset[];
+/** Collects all assets under a folder tree node. */
+export declare function collectFolderAssets(node: AssetTreeFolder): EffectAsset[];
+/** Resolves a drag payload to the assets that would be instantiated on drop. */
+export declare function describeAssetDrag(assets: EffectAsset[], payload: AssetDragPayload): {
+    assets: EffectAsset[];
+    label: string;
+};

package/dist/core/assetTree.js

@@ -0,0 +1,112 @@
+function compareNodes(a, b) {
+    if (a.kind !== b.kind) {
+        return a.kind === 'folder' ? -1 : 1;
+    }
+    return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+}
+/** Builds a folder tree from asset relative paths (e.g. `VFX/Fire/Explosion.json`). */
+export function buildAssetTree(assets) {
+    const roots = [];
+    for (const asset of assets) {
+        const segments = asset.path
+            .replace(/\.json$/i, '')
+            .split('/')
+            .filter(Boolean);
+        const fileName = segments.pop() ?? asset.name;
+        let level = roots;
+        let pathSoFar = '';
+        for (const segment of segments) {
+            pathSoFar = pathSoFar ? `${pathSoFar}/${segment}` : segment;
+            let folder = level.find((node) => node.kind === 'folder' && node.name === segment);
+            if (!folder) {
+                folder = { kind: 'folder', name: segment, path: pathSoFar, children: [] };
+                level.push(folder);
+            }
+            level = folder.children;
+        }
+        level.push({ kind: 'asset', name: fileName, path: asset.path, asset });
+    }
+    const sortTree = (nodes) => {
+        nodes.sort(compareNodes);
+        for (const node of nodes) {
+            if (node.kind === 'folder') {
+                sortTree(node.children);
+            }
+        }
+    };
+    sortTree(roots);
+    return roots;
+}
+/** Children of the folder at `path` (`''` is the top level), or null when it no longer exists. */
+export function folderChildren(tree, path) {
+    let level = tree;
+    for (const segment of path.split('/').filter(Boolean)) {
+        const folder = level.find((node) => node.kind === 'folder' && node.name === segment);
+        if (!folder) {
+            return null;
+        }
+        level = folder.children;
+    }
+    return level;
+}
+/** Assets whose name or path contains `query`, across every folder, sorted by name. */
+export function searchAssets(assets, query) {
+    const q = query.trim().toLowerCase();
+    return assets
+        .filter((asset) => `${asset.path} ${asset.name}`.toLowerCase().includes(q))
+        .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+}
+export const ASSET_DRAG_MIME = 'application/x-quarks-asset-drop';
+export function writeAssetDrag(dataTransfer, payload) {
+    dataTransfer.setData(ASSET_DRAG_MIME, JSON.stringify(payload));
+    dataTransfer.effectAllowed = 'copy';
+}
+export function readAssetDrag(dataTransfer) {
+    const raw = dataTransfer.getData(ASSET_DRAG_MIME);
+    if (!raw) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.kind === 'asset' && typeof parsed.id === 'number') {
+            return parsed;
+        }
+        if (parsed?.kind === 'folder' && typeof parsed.path === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/** Returns every asset whose JSON path sits inside `folderPath` (recursive). */
+export function collectAssetsInFolder(assets, folderPath) {
+    const prefix = `${folderPath}/`;
+    return assets.filter((asset) => asset.path.startsWith(prefix));
+}
+/** Collects all assets under a folder tree node. */
+export function collectFolderAssets(node) {
+    const collected = [];
+    const walk = (nodes) => {
+        for (const child of nodes) {
+            if (child.kind === 'asset') {
+                collected.push(child.asset);
+            }
+            else {
+                walk(child.children);
+            }
+        }
+    };
+    walk(node.children);
+    return collected;
+}
+/** Resolves a drag payload to the assets that would be instantiated on drop. */
+export function describeAssetDrag(assets, payload) {
+    if (payload.kind === 'asset') {
+        const asset = assets.find((item) => item.id === payload.id);
+        return { assets: asset ? [asset] : [], label: asset?.name ?? 'Effect' };
+    }
+    const label = payload.path.split('/').filter(Boolean).pop() ?? payload.path;
+    return { assets: collectAssetsInFolder(assets, payload.path), label };
+}

package/dist/core/assets.d.ts

@@ -0,0 +1,56 @@
+/**
+ * One effect file in the Assets panel. Holds the source JSON only — nothing is live in the
+ * Babylon scene until the asset is dropped into the viewport, and every drop instantiates a
+ * fresh, independent copy (see `instantiateSceneEntry`).
+ */
+export interface EffectAsset {
+    id: number;
+    name: string;
+    /** Relative path inside the imported folder (preserves subfolders). */
+    path: string;
+    /** Quarks JSON with every external file reference already inlined. */
+    json: unknown;
+    /** Texture/geometry files the effect references that were not among the imported files. */
+    missingFiles: string[];
+}
+export interface AssetLoadProgress {
+    done: number;
+    total: number;
+    loaded: number;
+    failed: number;
+}
+export declare function relativePathOf(file: File): string;
+/** Files an asset import reads: effect `.json` files plus the images/geometries they may reference. */
+export declare function isAssetImportFile(name: string): boolean;
+/** Collects `.json` files from a picker result, sorted by relative path. */
+export declare function collectJsonFiles(files: FileList | File[]): File[];
+/** Resolves `url` against the folder of `fromPath` (`a/b/fx.json` + `../t.png` → `a/t.png`). */
+export declare function resolveRelativePath(fromPath: string, url: string): string;
+/** True for a Quarks effect envelope with at least one particle emitter. */
+export declare function isEffectJson(json: unknown): boolean;
+/**
+ * Reads every effect JSON among `files` into an asset. Files that are not effects (geometry
+ * files, unrelated JSON, images) are skipped silently; unreadable JSON is skipped with a warning.
+ */
+export declare function loadEffectAssets(files: FileList | File[], onProgress: (progress: AssetLoadProgress) => void): Promise<EffectAsset[]>;
+/** Wraps an in-memory effect JSON (e.g. the host's `effectJson`) as an asset. */
+export declare function createEffectAsset(name: string, path: string, json: unknown): EffectAsset;
+/** Merges newly imported assets, skipping paths already in the list. */
+export declare function mergeAssets(existing: EffectAsset[], incoming: EffectAsset[]): {
+    merged: EffectAsset[];
+    added: EffectAsset[];
+    skipped: number;
+};
+/** Removes one asset, or every asset under a folder path. */
+export declare function removeAssets(assets: EffectAsset[], target: {
+    kind: 'asset';
+    id: number;
+} | {
+    kind: 'folder';
+    path: string;
+}): EffectAsset[];
+/**
+ * Url of the effect's main texture — the first emitter's material map — used as its icon in
+ * the Assets panel. Falls back to the first image; null when the effect has no texture.
+ */
+export declare function assetIconUrl(asset: EffectAsset): string | null;

package/dist/core/assets.js

@@ -0,0 +1,207 @@
+import { QuarksLoader } from 'babylon.quarks';
+const YIELD_EVERY = 8;
+const IMAGE_FILE = /\.(png|jpe?g|webp|gif|bmp)$/i;
+let nextAssetId = 1;
+function yieldToBrowser() {
+    return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+export function relativePathOf(file) {
+    return (file.webkitRelativePath || file.name).replace(/\\/g, '/');
+}
+/** Files an asset import reads: effect `.json` files plus the images/geometries they may reference. */
+export function isAssetImportFile(name) {
+    return /\.json$/i.test(name) || IMAGE_FILE.test(name);
+}
+/** Collects `.json` files from a picker result, sorted by relative path. */
+export function collectJsonFiles(files) {
+    return Array.from(files)
+        .filter((file) => file.name.toLowerCase().endsWith('.json'))
+        .sort((a, b) => relativePathOf(a).localeCompare(relativePathOf(b)));
+}
+/** Resolves `url` against the folder of `fromPath` (`a/b/fx.json` + `../t.png` → `a/t.png`). */
+export function resolveRelativePath(fromPath, url) {
+    const segments = fromPath.split('/').slice(0, -1);
+    for (const part of url.split('/')) {
+        if (part === '..') {
+            segments.pop();
+        }
+        else if (part !== '.' && part !== '') {
+            segments.push(part);
+        }
+    }
+    return segments.join('/');
+}
+function isExternalUrl(url) {
+    return /^(data|blob):/i.test(url) || /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('/');
+}
+function readAsDataUrl(file) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(reader.result);
+        reader.onerror = () => reject(reader.error);
+        reader.readAsDataURL(file);
+    });
+}
+/** True for a Quarks effect envelope with at least one particle emitter. */
+export function isEffectJson(json) {
+    const object = json?.object;
+    const walk = (node) => {
+        if (!node || typeof node !== 'object')
+            return false;
+        const typed = node;
+        if (typed.type === 'ParticleEmitter')
+            return true;
+        return Array.isArray(typed.children) && typed.children.some(walk);
+    };
+    return walk(object);
+}
+/**
+ * Looks files up by path relative to the import root, falling back to the bare file name — a
+ * multi-file "Import effect" pick has no folder structure, only names.
+ */
+class ImportedFileIndex {
+    constructor(files) {
+        this.byPath = new Map();
+        this.byName = new Map();
+        this.cache = new Map();
+        for (const file of files) {
+            this.byPath.set(relativePathOf(file).toLowerCase(), file);
+            if (!this.byName.has(file.name.toLowerCase())) {
+                this.byName.set(file.name.toLowerCase(), file);
+            }
+        }
+    }
+    find(fromPath, url) {
+        const clean = decodeURIComponent(url.split(/[?#]/)[0]);
+        return (this.byPath.get(resolveRelativePath(fromPath, clean).toLowerCase()) ??
+            this.byName.get((clean.split('/').pop() ?? clean).toLowerCase()));
+    }
+    /** Reads each file once, however many effects reference it. */
+    read(file, read) {
+        let pending = this.cache.get(file);
+        if (!pending) {
+            pending = read(file);
+            this.cache.set(file, pending);
+        }
+        return pending;
+    }
+}
+/**
+ * Inlines what an "assets as files" export put in separate files: image urls become data URIs
+ * and external geometries are read into the JSON, so the effect loads (and later exports) as a
+ * self-contained effect. Returns the references that could not be found among the files.
+ */
+async function inlineExternalFiles(json, effectPath, index) {
+    const missing = [];
+    for (const image of Array.isArray(json.images) ? json.images : []) {
+        const url = image?.url;
+        if (typeof url !== 'string' || isExternalUrl(url))
+            continue;
+        const file = index.find(effectPath, url);
+        if (file) {
+            image.url = await index.read(file, readAsDataUrl);
+        }
+        else {
+            missing.push(url);
+        }
+    }
+    await QuarksLoader.resolveExternalGeometries(json, async (url) => {
+        const file = index.find(effectPath, url);
+        if (!file) {
+            missing.push(url);
+            throw new Error('not among the imported files');
+        }
+        return index.read(file, async (f) => JSON.parse(await f.text()));
+    });
+    return missing;
+}
+/**
+ * Reads every effect JSON among `files` into an asset. Files that are not effects (geometry
+ * files, unrelated JSON, images) are skipped silently; unreadable JSON is skipped with a warning.
+ */
+export async function loadEffectAssets(files, onProgress) {
+    const all = Array.from(files).filter((file) => isAssetImportFile(file.name));
+    const jsonFiles = collectJsonFiles(all);
+    const index = new ImportedFileIndex(all);
+    const assets = [];
+    let failed = 0;
+    onProgress({ done: 0, total: jsonFiles.length, loaded: 0, failed: 0 });
+    for (let i = 0; i < jsonFiles.length; i++) {
+        const file = jsonFiles[i];
+        const path = relativePathOf(file);
+        try {
+            const json = JSON.parse(await file.text());
+            if (isEffectJson(json)) {
+                const missingFiles = await inlineExternalFiles(json, path, index);
+                if (missingFiles.length > 0) {
+                    console.warn(`[Quarks editor] "${path}" references files that were not imported:`, missingFiles);
+                }
+                assets.push({ id: nextAssetId++, name: file.name.replace(/\.json$/i, ''), path, json, missingFiles });
+            }
+        }
+        catch (err) {
+            failed++;
+            console.warn(`[Quarks editor] Skipped "${path}":`, err);
+        }
+        onProgress({ done: i + 1, total: jsonFiles.length, loaded: assets.length, failed });
+        if ((i + 1) % YIELD_EVERY === 0) {
+            await yieldToBrowser();
+        }
+    }
+    return assets;
+}
+/** Wraps an in-memory effect JSON (e.g. the host's `effectJson`) as an asset. */
+export function createEffectAsset(name, path, json) {
+    return { id: nextAssetId++, name, path, json, missingFiles: [] };
+}
+/** Merges newly imported assets, skipping paths already in the list. */
+export function mergeAssets(existing, incoming) {
+    const paths = new Set(existing.map((asset) => asset.path));
+    const added = [];
+    for (const asset of incoming) {
+        if (paths.has(asset.path))
+            continue;
+        paths.add(asset.path);
+        added.push(asset);
+    }
+    return { merged: [...existing, ...added], added, skipped: incoming.length - added.length };
+}
+/** Removes one asset, or every asset under a folder path. */
+export function removeAssets(assets, target) {
+    if (target.kind === 'asset') {
+        return assets.filter((asset) => asset.id !== target.id);
+    }
+    const prefix = `${target.path}/`;
+    return assets.filter((asset) => !asset.path.startsWith(prefix));
+}
+const iconCache = new WeakMap();
+/**
+ * Url of the effect's main texture — the first emitter's material map — used as its icon in
+ * the Assets panel. Falls back to the first image; null when the effect has no texture.
+ */
+export function assetIconUrl(asset) {
+    const cached = iconCache.get(asset);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const json = asset.json;
+    const findMaterial = (node) => {
+        if (!node || typeof node !== 'object')
+            return undefined;
+        if (node.type === 'ParticleEmitter' && node.ps?.material)
+            return node.ps.material;
+        for (const child of Array.isArray(node.children) ? node.children : []) {
+            const found = findMaterial(child);
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    const byUuid = (list, uuid) => (Array.isArray(list) ? list : []).find((item) => item?.uuid === uuid);
+    const material = byUuid(json?.materials, findMaterial(json?.object));
+    const texture = byUuid(json?.textures, material?.map ?? material?.texture);
+    const image = byUuid(json?.images, texture?.image) ?? (Array.isArray(json?.images) ? json.images[0] : undefined);
+    const url = typeof image?.url === 'string' && image.url ? image.url : null;
+    iconCache.set(asset, url);
+    return url;
+}

package/dist/core/binding.d.ts

@@ -1,5 +1,5 @@
-import type { ParticleSystem } from 'babylon.quarks';
 import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import type { ParticleSystem } from 'babylon.quarks';
 import type { EffectTreeNode } from './effectTree';
 export type EditorListener = () => void;
 /**
@@ -33,6 +33,11 @@ export declare class EffectBinding {
      * exists so there's always a designated fallback system to select.
      */
     promoteToMain(next: ParticleSystem): void;
+    /**
+     * Notifies subscribers of a change made outside `apply()` — e.g. a transform edited by the
+     * gizmo, or a sub-system edited through its own nested binding.
+     */
+    markChanged(): void;
     private notify;
     restart(): void;
     /**

package/dist/core/binding.js

@@ -56,6 +56,13 @@ export class EffectBinding {
         this.system = next;
         this.notify();
     }
+    /**
+     * Notifies subscribers of a change made outside `apply()` — e.g. a transform edited by the
+     * gizmo, or a sub-system edited through its own nested binding.
+     */
+    markChanged() {
+        this.notify();
+    }
     notify() {
         this.revision++;
         for (const listener of this.listeners) {

package/dist/core/collision.d.ts

@@ -1,8 +1,7 @@
 import { Vector3 } 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.
+ * A horizontal ground plane collider for hosts/demos that opt in via ensureGroundResolver /
+ * setPhysicsResolver. The editor never registers this automatically.
  *
  * `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.
@@ -13,8 +12,8 @@ export declare class GroundPlaneResolver {
     resolve(position: Vector3, normal: Vector3): boolean;
 }
 /**
- * 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.
+ * Opt-in helper for hosts/demos that want a simple floor collider.
+ * The editor does not call this — like Unity, collision needs an explicit host-provided resolver.
  * Idempotent: an already-registered resolver is left untouched and returned.
  */
 export declare function ensureGroundResolver(): GroundPlaneResolver;

package/dist/core/collision.js

@@ -1,8 +1,7 @@
 import { 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.
+ * A horizontal ground plane collider for hosts/demos that opt in via ensureGroundResolver /
+ * setPhysicsResolver. The editor never registers this automatically.
  *
  * `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.
@@ -20,8 +19,8 @@ export class GroundPlaneResolver {
     }
 }
 /**
- * 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.
+ * Opt-in helper for hosts/demos that want a simple floor collider.
+ * The editor does not call this — like Unity, collision needs an explicit host-provided resolver.
  * Idempotent: an already-registered resolver is left untouched and returned.
  */
 export function ensureGroundResolver() {

package/dist/core/colors.d.ts

@@ -1,5 +1,5 @@
-import { ColorOverLife, Gradient, Vector4 } from 'babylon.quarks';
 import type { Behavior } from 'babylon.quarks';
+import { ColorOverLife, Gradient, Vector4 } from 'babylon.quarks';
 /** One RGBA stop of the editable gradient (all channels 0..1, pos 0..1). */
 export interface GradientStop {
     pos: number;

package/dist/core/defaultEffect.d.ts

@@ -1,12 +1,11 @@
 import type { Scene } from '@babylonjs/core/scene';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import { ParticleSystem } from 'babylon.quarks';
-import type { GalleryEntry } from './loadEffectGallery';
-export interface CreateGalleryDefaultOptions {
+import { type SceneEntry } from './sceneEntries';
+export interface CreateSceneDefaultOptions {
     resolveTexture?: (url: string, scene: Scene) => unknown;
     textureUrl?: string;
 }
 /** Creates a simple cone burst preset for new editor effects. */
 export declare function createDefaultEffect(scene: Scene, resolveTexture?: (url: string, scene: Scene) => unknown, textureUrl?: string): ParticleSystem;
-/** Adds a blank preset effect to the hidden gallery catalog (not in the renderer yet). */
-export declare function createGalleryDefaultEntry(scene: Scene, catalogRoot: TransformNode, existing: GalleryEntry[], options?: CreateGalleryDefaultOptions): GalleryEntry;
+/** Creates a preset effect as a new scene entry (systems not registered with the renderer yet). */
+export declare function createSceneDefaultEntry(scene: Scene, existing: SceneEntry[], options?: CreateSceneDefaultOptions): SceneEntry;

package/dist/core/defaultEffect.js

@@ -1,6 +1,7 @@
 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 { uniqueEntryName } from './sceneEntries';
 /** Creates a simple cone burst preset for new editor effects. */
 export function createDefaultEffect(scene, resolveTexture, textureUrl) {
     const system = new ParticleSystem({
@@ -22,22 +23,12 @@ export function createDefaultEffect(scene, resolveTexture, textureUrl) {
     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, catalogRoot, existing, options = {}) {
-    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`;
+/** Creates a preset effect as a new scene entry (systems not registered with the renderer yet). */
+export function createSceneDefaultEntry(scene, existing, options = {}) {
+    const name = uniqueEntryName(existing.length === 0 ? 'Effect' : 'New Effect', existing);
     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 };
+    return { name, path: `_created/${name}.json`, assetId: null, root, systems: [system] };
 }

package/dist/core/effectTree.d.ts

@@ -1,5 +1,5 @@
-import type { ParticleSystem } from 'babylon.quarks';
 import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import type { ParticleSystem } from 'babylon.quarks';
 /** A node in the editor's effect hierarchy: a Group (organizational) or a ParticleEmitter. */
 export interface EffectTreeNode {
     node: TransformNode;