babylon.quarks-editor 0.19.0 → 0.20.0

package/src/core/projectStore.ts

@@ -0,0 +1,81 @@
+/** One editor project: a library of effect assets plus the scene built from them. */
+export interface ProjectMeta {
+    id: string;
+    name: string;
+    createdAt: number;
+    updatedAt: number;
+    assetCount: number;
+    /** Approximate bytes the project takes in storage (JSON + texture files). */
+    sizeBytes: number;
+}
+
+/** An effect asset as the store keeps it. `json` is a self-contained Quarks effect. */
+export interface StoredAsset {
+    /** Relative path inside the project (`Fire/Explosion.json`) — the asset's key. */
+    path: string;
+    name: string;
+    json: unknown;
+    missingFiles: string[];
+}
+
+/** One effect instance in a saved scene. */
+export interface StoredSceneEntry {
+    name: string;
+    /** Path of the asset it was made from, if any. */
+    assetPath: string | null;
+    /** The instance's own (possibly edited) effect, root transform included. */
+    json: unknown;
+    visible: boolean;
+}
+
+export interface StoredScene {
+    entries: StoredSceneEntry[];
+    savedAt: number;
+}
+
+export interface StorageEstimate {
+    /** Bytes the whole site uses (all projects), when the browser reports it. */
+    usage: number | null;
+    /** Bytes the browser lets the site use, when it reports it. */
+    quota: number | null;
+    /** True when the browser promised not to evict the data under storage pressure. */
+    persisted: boolean;
+}
+
+/**
+ * Where projects live. The editor only talks to this interface; `IndexedDbProjectStore` keeps
+ * everything in the browser, and an embedding host can supply its own (e.g. on disk).
+ */
+export interface ProjectStore {
+    listProjects(): Promise<ProjectMeta[]>;
+    getProject(id: string): Promise<ProjectMeta | null>;
+    createProject(name: string): Promise<ProjectMeta>;
+    renameProject(id: string, name: string): Promise<void>;
+    duplicateProject(id: string, name: string): Promise<ProjectMeta>;
+    deleteProject(id: string): Promise<void>;
+
+    loadAssets(projectId: string): Promise<StoredAsset[]>;
+    /** Adds or replaces assets by path. */
+    putAssets(projectId: string, assets: StoredAsset[]): Promise<void>;
+    deleteAssets(projectId: string, paths: string[]): Promise<void>;
+
+    loadScene(projectId: string): Promise<StoredScene | null>;
+    saveScene(projectId: string, scene: StoredScene): Promise<void>;
+
+    estimate(): Promise<StorageEstimate>;
+    /** Asks the browser to keep the data even under storage pressure; resolves to the result. */
+    requestPersistence(): Promise<boolean>;
+}
+
+export function formatBytes(bytes: number | null | undefined): string {
+    if (bytes == null) return '—';
+    if (bytes < 1024) return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}

package/src/core/sceneEntries.ts

@@ -0,0 +1,96 @@
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {Scene} from '@babylonjs/core/scene';
+import type {BatchedRenderer, ParticleEmitter, ParticleSystem} from 'babylon.quarks';
+import {QuarksUtil} from 'babylon.quarks';
+import type {EffectAsset} from './assets';
+import {EffectBinding} from './binding';
+import {disposeLoadedEffect, parseEffectFromJson} from './loadEffect';
+
+/**
+ * One effect instance placed in the scene. Every instance is live (its systems are registered
+ * with the renderer) and independent: dropping the same asset three times gives three entries
+ * that are edited separately.
+ */
+export interface SceneEntry {
+    name: string;
+    /** Path of the asset it came from, or a synthetic `_created/…` path for new effects. */
+    path: string;
+    /** Asset this instance was made from, if any. */
+    assetId: number | null;
+    root: TransformNode;
+    systems: ParticleSystem[];
+}
+
+/** `name`, or `name (2)`, `name (3)`… when an entry already uses it. */
+export function uniqueEntryName(name: string, existing: SceneEntry[]): string {
+    const taken = new Set(existing.map((entry) => entry.name));
+    if (!taken.has(name)) {
+        return name;
+    }
+    let n = 2;
+    while (taken.has(`${name} (${n})`)) {
+        n++;
+    }
+    return `${name} (${n})`;
+}
+
+function isPlaceholderName(name: string): boolean {
+    return !name || name === 'Effect' || name === 'Object3D' || name === 'Group';
+}
+
+/**
+ * Parses an asset into a new scene instance with its systems registered (paused). Returns null
+ * when the JSON holds no particle systems.
+ */
+export function instantiateSceneEntry(
+    scene: Scene,
+    renderer: BatchedRenderer,
+    asset: EffectAsset,
+    existing: SceneEntry[]
+): SceneEntry | null {
+    const {root, systems} = parseEffectFromJson(scene, renderer, asset.json, {
+        registerRenderer: true,
+        autoplay: false,
+    });
+    if (systems.length === 0) {
+        disposeLoadedEffect(root, systems, renderer, true);
+        return null;
+    }
+    const name = uniqueEntryName(isPlaceholderName(root.name) ? asset.name : root.name, existing);
+    root.name = name;
+    root.parent = null;
+    return {name, path: asset.path, assetId: asset.id, root, systems};
+}
+
+/** Builds an edit binding for one scene entry. */
+export function bindingFromSceneEntry(entry: SceneEntry): EffectBinding {
+    const main = entry.systems.find((s) => !s.onlyUsedByOther) ?? entry.systems[0];
+    return new EffectBinding(
+        main,
+        entry.systems.filter((s) => s !== main),
+        entry.root
+    );
+}
+
+/**
+ * Unregisters and disposes one scene entry — including systems the inspector added after the
+ * entry was created, which only the live emitter tree knows about.
+ */
+export function disposeSceneEntry(entry: SceneEntry, renderer: BatchedRenderer): void {
+    const systems = new Set<ParticleSystem>(entry.systems);
+    QuarksUtil.runOnAllParticleEmitters(entry.root, (emitter: ParticleEmitter) => {
+        systems.add(emitter.system as ParticleSystem);
+    });
+    disposeLoadedEffect(entry.root, [...systems], renderer, true);
+}
+
+/** Number of scene instances per asset id. */
+export function countInstancesByAsset(entries: SceneEntry[]): Map<number, number> {
+    const counts = new Map<number, number>();
+    for (const entry of entries) {
+        if (entry.assetId != null) {
+            counts.set(entry.assetId, (counts.get(entry.assetId) ?? 0) + 1);
+        }
+    }
+    return counts;
+}

package/src/core/transport.ts

@@ -0,0 +1,53 @@
+import type {Scene} from '@babylonjs/core/scene';
+import type {BatchedRenderer} from 'babylon.quarks';
+import type {EffectBinding} from './binding';
+import {clearFocusFinished, isFocusFinished, setFocusElapsed, type PlaybackState} from './playback';
+import {playFocus, scrubFocusTo} from './scrub';
+
+/**
+ * Stage Play/Pause shared by the viewport transport bar and the timeline. Pressing Play on a
+ * one-shot focus that already parked at its end replays it from the start.
+ */
+export function toggleStagePlayback(
+    binding: EffectBinding | null,
+    scene: Scene,
+    playback: PlaybackState,
+    stagePlaying: boolean,
+    setStagePlaying: (playing: boolean) => void
+): void {
+    if (stagePlaying) {
+        playback.stagePlaying = false;
+        setStagePlaying(false);
+        return;
+    }
+    if (binding) {
+        const rootId = binding.root.uniqueId;
+        if (isFocusFinished(playback, rootId)) {
+            binding.restart();
+            clearFocusFinished(playback, rootId);
+            setFocusElapsed(playback, rootId, 0);
+            scene.render();
+        }
+    }
+    playback.stagePlaying = true;
+    setStagePlaying(true);
+}
+
+/** Restarts the focused effect only; other visible effects keep playing. */
+export function restartFocusPlayback(
+    binding: EffectBinding,
+    renderer: BatchedRenderer,
+    scene: Scene,
+    playback: PlaybackState
+): void {
+    const rootId = binding.root.uniqueId;
+    scrubFocusTo(binding, renderer, 0);
+    setFocusElapsed(playback, rootId, 0);
+    clearFocusFinished(playback, rootId);
+    if (playback.stagePlaying) {
+        playFocus(binding);
+    }
+    scene.render();
+}
+
+export const PLAYBACK_SPEEDS = [0.1, 0.25, 0.5, 1, 2, 4];

package/src/core/viewportPicker.ts

@@ -4,7 +4,7 @@ import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import type {Scene} from '@babylonjs/core/scene';
 import {EDITOR_SCENE_NODE_METADATA} from './editorScene';
 import {GROUND_RING_RADIUS, GalleryHoverMarker} from './gallerySelectionMarker';
-import type {GalleryEntry} from './loadEffectGallery';
+import type {SceneEntry} from './sceneEntries';
 
 interface PickMetadata {
     quarksEditorPick: true;
@@ -15,7 +15,7 @@ interface PickMetadata {
 const PICK_DIAMETER = GROUND_RING_RADIUS * 2;
 
 /**
- * Viewport pick/hover for in-scene gallery effect roots only (not child emitters).
+ * Viewport pick/hover for visible scene effect roots only (not child emitters).
  * Hover uses the same ground ring as focus selection, in yellow.
  */
 export class GalleryViewportPicker {
@@ -30,8 +30,8 @@ export class GalleryViewportPicker {
         this.hoverMarker = new GalleryHoverMarker(scene);
     }
 
-    /** Rebuilds root pick colliders when the gallery changes. */
-    sync(entries: GalleryEntry[], soloRoot: TransformNode | null, syncKey: string): void {
+    /** Rebuilds root pick colliders when the scene changes. */
+    sync(entries: SceneEntry[], soloRoot: TransformNode | null, syncKey: string): void {
         if (syncKey === this.syncKey) {
             return;
         }
@@ -39,7 +39,7 @@ export class GalleryViewportPicker {
         this.clearHandles();
         if (entries.length > 0) {
             for (const entry of entries) {
-                if (!entry.inScene || entry.root.isDisposed()) {
+                if (entry.root.isDisposed() || !entry.root.isEnabled(false)) {
                     continue;
                 }
                 this.createHandle(entry.root);

package/src/index.ts

@@ -16,8 +16,19 @@ export type {GradientStop} from './core/colors';
 export {buildEffectTree, collectSystems, serializeEffectForest, serializeEffectTree} from './core/effectTree';
 export type {EffectTreeNode} from './core/effectTree';
 export {EffectHistory} from './core/history';
+export type {HistoryStacks} from './core/history';
+export {IndexedDbProjectStore} from './core/indexedDbProjectStore';
 export {applyRendererMaterial, getMaterialLabel} from './core/material';
 export type {RendererMaterialPatch} from './core/material';
+export {formatBytes} from './core/projectStore';
+export type {
+    ProjectMeta,
+    ProjectStore,
+    StorageEstimate,
+    StoredAsset,
+    StoredScene,
+    StoredSceneEntry,
+} from './core/projectStore';
 export {
     DEFAULT_SHAPE_PARAMS,
     SHAPE_PARAM_KEYS,