babylon.quarks-editor 0.17.7

package/src/core/binding.ts

@@ -0,0 +1,105 @@
+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);
+    }
+}

package/src/core/collision.ts

@@ -0,0 +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;
+}

package/src/core/colors.ts

@@ -0,0 +1,84 @@
+import {ColorOverLife, Gradient, Vector3, Vector4} from 'babylon.quarks';
+import type {Behavior} from 'babylon.quarks';
+
+/** One RGBA stop of the editable gradient (all channels 0..1, pos 0..1). */
+export interface GradientStop {
+    pos: number;
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+
+export const DEFAULT_GRADIENT_STOPS: GradientStop[] = [
+    {pos: 0, r: 1, g: 0.85, b: 0.4, a: 1},
+    {pos: 1, r: 1, g: 0.25, b: 0.05, a: 0},
+];
+
+export function buildGradient(stops: GradientStop[]): Gradient {
+    const sorted = [...stops].sort((a, b) => a.pos - b.pos);
+    return new Gradient(
+        sorted.map((s) => [new Vector3(s.r, s.g, s.b), s.pos] as [Vector3, number]),
+        sorted.map((s) => [s.a, s.pos] as [number, number])
+    );
+}
+
+export function buildColorOverLife(stops: GradientStop[]): ColorOverLife {
+    return new ColorOverLife(buildGradient(stops));
+}
+
+export function rgbaToVector4(stop: {r: number; g: number; b: number; a: number}): Vector4 {
+    return new Vector4(stop.r, stop.g, stop.b, stop.a);
+}
+
+export function stopToCss(stop: GradientStop): string {
+    const c = (v: number) => Math.round(v * 255);
+    return `rgba(${c(stop.r)}, ${c(stop.g)}, ${c(stop.b)}, ${stop.a.toFixed(2)})`;
+}
+
+export function stopsToCssGradient(stops: GradientStop[]): string {
+    const sorted = [...stops].sort((a, b) => a.pos - b.pos);
+    const parts = sorted.map((s) => `${stopToCss(s)} ${(s.pos * 100).toFixed(1)}%`);
+    return `linear-gradient(90deg, ${parts.join(', ')})`;
+}
+
+export function hexToRgb(hex: string): {r: number; g: number; b: number} {
+    const value = hex.replace('#', '');
+    return {
+        r: parseInt(value.slice(0, 2), 16) / 255,
+        g: parseInt(value.slice(2, 4), 16) / 255,
+        b: parseInt(value.slice(4, 6), 16) / 255,
+    };
+}
+
+export function rgbToHex(r: number, g: number, b: number): string {
+    const c = (v: number) =>
+        Math.round(Math.min(1, Math.max(0, v)) * 255)
+            .toString(16)
+            .padStart(2, '0');
+    return `#${c(r)}${c(g)}${c(b)}`;
+}
+
+/** Reads RGBA stops back from a Gradient (union of color/alpha key positions). */
+export function readGradientStops(gradient: Gradient): GradientStop[] {
+    const positions = new Set<number>();
+    for (const [, pos] of gradient.color.keys) {
+        positions.add(Math.round(pos * 1000) / 1000);
+    }
+    for (const [, pos] of gradient.alpha.keys) {
+        positions.add(Math.round(pos * 1000) / 1000);
+    }
+    const color = new Vector3();
+    return [...positions]
+        .sort((a, b) => a - b)
+        .map((pos) => {
+            gradient.color.genValue(color, pos);
+            const alpha = gradient.alpha.genValue(0, pos);
+            return {pos, r: color.x, g: color.y, b: color.z, a: alpha};
+        });
+}
+
+/** Finds a behavior of the given quarks type string (e.g. 'ColorOverLife'). */
+export function findBehavior<T extends Behavior>(behaviors: Behavior[], type: string): T | undefined {
+    return behaviors.find((b) => (b as {type?: string}).type === type) as T | undefined;
+}

package/src/core/effectTree.ts

@@ -0,0 +1,143 @@
+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';
+
+/** A node in the editor's effect hierarchy: a Group (organizational) or a ParticleEmitter. */
+export interface EffectTreeNode {
+    node: TransformNode;
+    name: string;
+    /** Present when the node is a ParticleEmitter. */
+    system?: ParticleSystem;
+    depth: number;
+    children: EffectTreeNode[];
+}
+
+/** Walks a loaded root TransformNode into the editor tree (groups + emitters). */
+export function buildEffectTree(root: TransformNode, depth = 0): EffectTreeNode {
+    const system = root instanceof ParticleEmitter ? (root.system as ParticleSystem) : undefined;
+    const treeNode: EffectTreeNode = {
+        node: root,
+        name: root.name || (system ? 'emitter' : 'group'),
+        system,
+        depth,
+        children: [],
+    };
+    for (const child of root.getChildren()) {
+        if (child instanceof TransformNode) {
+            treeNode.children.push(buildEffectTree(child, depth + 1));
+        }
+    }
+    return treeNode;
+}
+
+/** Flattens the tree into the systems it contains, in display order. */
+export function collectSystems(tree: EffectTreeNode): ParticleSystem[] {
+    const out: ParticleSystem[] = [];
+    const walk = (node: EffectTreeNode) => {
+        if (node.system) {
+            out.push(node.system);
+        }
+        node.children.forEach(walk);
+    };
+    walk(tree);
+    return out;
+}
+
+interface SerializeMeta {
+    textures: {[k: string]: {url?: string; name?: string}};
+    materials: {[k: string]: {[key: string]: unknown}};
+    geometries: {[k: string]: unknown};
+}
+
+function localMatrix(node: TransformNode): number[] {
+    const rotation = node.rotationQuaternion ?? Quaternion.FromEulerVector(node.rotation);
+    return Matrix.Compose(node.scaling, rotation, node.position).asArray().slice();
+}
+
+function serializeNode(tree: EffectTreeNode, meta: SerializeMeta, fallbackUuid: string): Record<string, unknown> {
+    // Emitter nodes must serialize with the ParticleEmitter's own `.uuid` — that is exactly
+    // what EmitSubParticleSystem.toJSON writes as its target reference, so the two match and
+    // QuarksLoader.linkReferences can re-resolve sub-emitters on reimport.
+    const uuid = tree.system
+        ? (tree.node as unknown as {uuid: string}).uuid
+        : ((tree.node as {_quarksUUID?: string})._quarksUUID ?? fallbackUuid);
+    const children = tree.children.map((child, i) => serializeNode(child, meta, `${fallbackUuid}-${i}`));
+    const base = {
+        uuid,
+        name: tree.name,
+        layers: 1,
+        matrix: localMatrix(tree.node),
+        children: children.length > 0 ? children : undefined,
+    };
+    if (tree.system) {
+        return {...base, type: 'ParticleEmitter', ps: tree.system.toJSON(meta as never, {useUrlForImage: true} as never)};
+    }
+    return {...base, type: 'Group'};
+}
+
+/**
+ * Serializes an effect tree into the Quarks JSON envelope understood by QuarksLoader,
+ * preserving the group/emitter hierarchy (not flattened).
+ */
+export function serializeEffectTree(root: TransformNode, name = 'effect'): string {
+    const meta: SerializeMeta = {textures: {}, materials: {}, geometries: {}};
+    const object = serializeNode(buildEffectTree(root), meta, `${name}-node`);
+    return finishEnvelope(object, meta);
+}
+
+/**
+ * Serializes several effect roots as children of a synthetic group — used when an effect
+ * spans multiple top-level trees (e.g. a demo running several loaded effects at once).
+ */
+export function serializeEffectForest(roots: TransformNode[], name = 'effect'): string {
+    if (roots.length === 1) {
+        return serializeEffectTree(roots[0], name);
+    }
+    const meta: SerializeMeta = {textures: {}, materials: {}, geometries: {}};
+    const children = roots.map((root, i) => serializeNode(buildEffectTree(root), meta, `${name}-node-${i}`));
+    const object = {
+        uuid: `${name}-root`,
+        name,
+        type: 'Group',
+        layers: 1,
+        matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+        children,
+    };
+    return finishEnvelope(object, meta);
+}
+
+/** Flattens accumulated meta and wraps the serialized object into the Quarks envelope. */
+function finishEnvelope(object: Record<string, unknown>, meta: SerializeMeta): string {
+    // toJSON stashes live Texture instances and material records in meta; flatten them into
+    // the serializable images/textures/materials arrays QuarksLoader expects.
+    const images: Array<{uuid: string; url: string}> = [];
+    const textures: Array<{uuid: string; image?: string}> = [];
+    for (const [uuid, tex] of Object.entries(meta.textures)) {
+        const url = tex?.url ?? tex?.name;
+        if (url) {
+            const imageUuid = `${uuid}-image`;
+            images.push({uuid: imageUuid, url});
+            textures.push({uuid, image: imageUuid});
+        } else {
+            textures.push({uuid});
+        }
+    }
+    const materials = Object.values(meta.materials).map((material) => {
+        const {sourceMaterial: _sourceMaterial, ...serializable} = material;
+        return serializable;
+    });
+
+    return JSON.stringify(
+        {
+            metadata: {version: 4.5, type: 'Object3D', generator: 'babylon.quarks-editor'},
+            geometries: Object.values(meta.geometries),
+            materials,
+            textures,
+            images,
+            object,
+        },
+        null,
+        2
+    );
+}

package/src/core/groups.ts

@@ -0,0 +1,29 @@
+import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+
+/**
+ * Groups the given nodes under a new organizational TransformNode. Each node's world
+ * transform is preserved via `setParent` — grouping never moves anything visually, it only
+ * changes the hierarchy so the group can be repositioned/organized as one unit afterwards.
+ */
+export function groupNodes(nodes: TransformNode[], name = 'Group'): TransformNode {
+    const scene = nodes[0].getScene();
+    const group = new TransformNode(name, scene);
+    group.setParent(nodes[0].parent);
+    for (const node of nodes) {
+        node.setParent(group);
+    }
+    return group;
+}
+
+/**
+ * Dissolves a group, reparenting its children onto the group's own parent and disposing the
+ * (now childless) group node. World transform of each child is preserved.
+ */
+export function ungroupNode(group: TransformNode): void {
+    const parent = group.parent;
+    const children = group.getChildren().filter((c): c is TransformNode => c instanceof TransformNode);
+    for (const child of children) {
+        child.setParent(parent);
+    }
+    group.dispose(true, false);
+}

package/src/core/history.ts

@@ -0,0 +1,77 @@
+import type {EffectBinding} from './binding';
+
+const COALESCE_MS = 400;
+const MAX_DEPTH = 50;
+
+/**
+ * Snapshot-based undo/redo over serialized effect JSON. Owned by the host (not the
+ * binding) so history survives rebinding when a restore rebuilds the systems.
+ *
+ * Wire-up: call attach() whenever a binding is (re)mounted; on undo()/redo() feed the
+ * returned JSON back through the host's import path and attach the new binding.
+ */
+export class EffectHistory {
+    private undoStack: string[] = [];
+    private redoStack: string[] = [];
+    private lastCaptureTime = 0;
+    private binding: EffectBinding | null = null;
+
+    /** Points the history at the active binding and hooks snapshot capture. */
+    attach(binding: EffectBinding): void {
+        this.binding = binding;
+        binding.onBeforeChange = () => this.capture();
+    }
+
+    get canUndo(): boolean {
+        return this.undoStack.length > 0;
+    }
+
+    get canRedo(): boolean {
+        return this.redoStack.length > 0;
+    }
+
+    clear(): void {
+        this.undoStack = [];
+        this.redoStack = [];
+        this.lastCaptureTime = 0;
+    }
+
+    /** Pushes an undo snapshot; rapid consecutive edits are coalesced into one step. */
+    capture(): void {
+        if (!this.binding) {
+            return;
+        }
+        const now = Date.now();
+        if (now - this.lastCaptureTime < COALESCE_MS && this.undoStack.length > 0) {
+            return;
+        }
+        this.lastCaptureTime = now;
+        this.undoStack.push(this.binding.exportJSON());
+        if (this.undoStack.length > MAX_DEPTH) {
+            this.undoStack.shift();
+        }
+        this.redoStack = [];
+    }
+
+    /** Returns the previous effect state as parsed JSON, or null when nothing to undo. */
+    undo(): unknown | null {
+        if (!this.binding || this.undoStack.length === 0) {
+            return null;
+        }
+        const snapshot = this.undoStack.pop()!;
+        this.redoStack.push(this.binding.exportJSON());
+        this.lastCaptureTime = 0;
+        return JSON.parse(snapshot);
+    }
+
+    /** Returns the next effect state as parsed JSON, or null when nothing to redo. */
+    redo(): unknown | null {
+        if (!this.binding || this.redoStack.length === 0) {
+            return null;
+        }
+        const snapshot = this.redoStack.pop()!;
+        this.undoStack.push(this.binding.exportJSON());
+        this.lastCaptureTime = 0;
+        return JSON.parse(snapshot);
+    }
+}

package/src/core/loadEffect.ts

@@ -0,0 +1,102 @@
+import {ParticleEmitter, QuarksLoader, QuarksUtil} from 'babylon.quarks';
+import type {BatchedRenderer, ParticleSystem} from 'babylon.quarks';
+import type {Scene} from '@babylonjs/core/scene';
+import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {Node} from '@babylonjs/core/node';
+
+/** `ParticleEmitter`'s constructor default (see babylon.quarks/src/ParticleEmitter.ts) — the
+ * name every emitter gets when the source JSON didn't give it one of its own. */
+const DEFAULT_EMITTER_NAME = 'particleEmitter';
+
+function hasMeaningfulName(node: TransformNode): boolean {
+    return !!node.name && node.name !== DEFAULT_EMITTER_NAME;
+}
+
+function groupChildren(node: TransformNode): TransformNode[] {
+    return node.getChildren().filter((c): c is TransformNode => c instanceof TransformNode);
+}
+
+/** Reparents `only` onto `parent`, transferring the outgoing node's name if `only` doesn't
+ * already have a meaningful one of its own, then disposes the now-empty wrapper. World
+ * transform is preserved via `setParent`. */
+function collapseInto(wrapper: TransformNode, only: TransformNode, parent: Node | null): void {
+    if (!hasMeaningfulName(only) && hasMeaningfulName(wrapper)) {
+        only.name = wrapper.name;
+    }
+    only.setParent(parent);
+    wrapper.dispose(true, false);
+}
+
+/**
+ * Collapses redundant organizational groups left over by importers — Unity's
+ * one-GameObject-per-component convention turns every visual layer into its own Group, so a
+ * single particle system becomes "Sparks" > unnamed emitter, and a component quarks doesn't
+ * understand (e.g. a Light) becomes an empty Group with nothing under it. Recurses
+ * bottom-up so nested wrapper chains collapse all the way down. The tree root itself is
+ * handled separately by `promoteIfSingleChildRoot`, since collapsing it means returning a
+ * different node as the effect's root.
+ */
+function flattenRedundantGroups(node: TransformNode): void {
+    for (const child of node.getChildren()) {
+        if (child instanceof TransformNode) {
+            flattenRedundantGroups(child);
+        }
+    }
+    if (node instanceof ParticleEmitter || !node.parent) {
+        return;
+    }
+    const children = groupChildren(node);
+    if (children.length === 0) {
+        node.dispose(true, false);
+        return;
+    }
+    if (children.length !== 1) {
+        return;
+    }
+    const only = children[0];
+    if (only instanceof ParticleEmitter && only.getChildren().length > 0) {
+        return;
+    }
+    collapseInto(node, only, node.parent);
+}
+
+/** If the tree root itself only ever wraps a single child (after `flattenRedundantGroups`
+ * has settled everything below it), that wrapper adds a tree level with nothing to organize —
+ * promote the child to be the new root instead. Loops in case that child is, in turn, also a
+ * single-child wrapper. */
+function promoteIfSingleChildRoot(root: TransformNode): TransformNode {
+    let current = root;
+    while (!(current instanceof ParticleEmitter)) {
+        const children = groupChildren(current);
+        if (children.length !== 1) {
+            break;
+        }
+        const only = children[0];
+        const parent = current.parent;
+        collapseInto(current, only, parent);
+        current = only;
+    }
+    return current;
+}
+
+/** Parses a Quarks JSON export, registers all systems with the renderer and starts playback. */
+export function loadEffectFromJson(
+    scene: Scene,
+    renderer: BatchedRenderer,
+    json: unknown,
+    baseUrl = ''
+): {root: TransformNode; systems: ParticleSystem[]} {
+    const loader = new QuarksLoader(scene, {baseUrl});
+    let root = loader.parse(json as never, baseUrl);
+    flattenRedundantGroups(root);
+    root = promoteIfSingleChildRoot(root);
+    const systems: ParticleSystem[] = [];
+    QuarksUtil.runOnAllParticleEmitters(root, (emitter: ParticleEmitter) => {
+        const system = emitter.system as ParticleSystem;
+        renderer.addSystem(system);
+        systems.push(system);
+    });
+    QuarksUtil.restart(root);
+    QuarksUtil.play(root);
+    return {root, systems};
+}

package/src/core/scrub.ts

@@ -0,0 +1,28 @@
+import type {BatchedRenderer} from 'babylon.quarks';
+import type {EffectBinding} from './binding';
+
+const WIDE_STEP_THRESHOLD = 8;
+
+/**
+ * Approximate timeline scrub: replays every system from t=0 up to `time` using the existing
+ * simulation loop. Not frame-exact (spawn/burst randomization is unseeded), but reuses
+ * `EffectBinding.restart()` and `BatchedRenderer.update()` verbatim — no new engine primitive.
+ *
+ * `ParticleSystem.update()` clamps its own `delta` to 0.1s per call, so a single big step
+ * can't reach `time` directly; must step through in small increments instead.
+ */
+export function scrubTo(binding: EffectBinding, renderer: BatchedRenderer, time: number): void {
+    binding.restart();
+    if (time <= 0) {
+        return;
+    }
+    const fixedStep = time > WIDE_STEP_THRESHOLD ? 1 / 30 : 1 / 60;
+    const steps = Math.floor(time / fixedStep);
+    for (let i = 0; i < steps; i++) {
+        renderer.update(fixedStep);
+    }
+    const remainder = time - steps * fixedStep;
+    if (remainder > 0) {
+        renderer.update(remainder);
+    }
+}