babylon.quarks-editor 0.17.7

package/src/core/shapes.ts

@@ -0,0 +1,133 @@
+import {
+    CircleEmitter,
+    ConeEmitter,
+    DonutEmitter,
+    GridEmitter,
+    HemisphereEmitter,
+    MeshSurfaceEmitter,
+    PointEmitter,
+    RectangleEmitter,
+    SphereEmitter,
+} from 'babylon.quarks';
+import type {EmitterShape} from 'babylon.quarks';
+import {EmitterMode} from 'babylon.quarks';
+import type {Mesh} from '@babylonjs/core/Meshes/mesh';
+
+export type ShapeType = 'point' | 'sphere' | 'hemisphere' | 'cone' | 'circle' | 'donut' | 'rectangle' | 'grid' | 'mesh_surface';
+
+export const SHAPE_TYPES: Array<{value: ShapeType; label: string}> = [
+    {value: 'cone', label: 'Cone'},
+    {value: 'sphere', label: 'Sphere'},
+    {value: 'hemisphere', label: 'Hemisphere'},
+    {value: 'circle', label: 'Circle'},
+    {value: 'donut', label: 'Donut'},
+    {value: 'rectangle', label: 'Rectangle'},
+    {value: 'grid', label: 'Grid'},
+    {value: 'mesh_surface', label: 'Mesh surface'},
+    {value: 'point', label: 'Point'},
+];
+
+export interface ShapeParams {
+    radius: number;
+    arc: number;
+    thickness: number;
+    angle: number;
+    donutRadius: number;
+    width: number;
+    height: number;
+    mode: EmitterMode;
+    spread: number;
+    column: number;
+    row: number;
+    mesh?: Mesh;
+}
+
+export const DEFAULT_SHAPE_PARAMS: ShapeParams = {
+    radius: 0.3,
+    arc: Math.PI * 2,
+    thickness: 1,
+    angle: 0.5,
+    donutRadius: 0.1,
+    width: 1,
+    height: 1,
+    mode: EmitterMode.Random,
+    spread: 0,
+    column: 10,
+    row: 10,
+    mesh: undefined,
+};
+
+export function getShapeType(shape: EmitterShape): ShapeType {
+    const type = (shape as {type?: string}).type ?? 'point';
+    return (SHAPE_TYPES.some((s) => s.value === type) ? type : 'point') as ShapeType;
+}
+
+export function readShapeParams(shape: EmitterShape): ShapeParams {
+    const anyShape = shape as unknown as {[key: string]: unknown};
+    const num = (key: string, fallback: number) => (typeof anyShape[key] === 'number' ? (anyShape[key] as number) : fallback);
+    return {
+        radius: num('radius', DEFAULT_SHAPE_PARAMS.radius),
+        mode: num('mode', DEFAULT_SHAPE_PARAMS.mode) as EmitterMode,
+        spread: num('spread', DEFAULT_SHAPE_PARAMS.spread),
+        arc: num('arc', DEFAULT_SHAPE_PARAMS.arc),
+        thickness: num('thickness', DEFAULT_SHAPE_PARAMS.thickness),
+        angle: num('angle', DEFAULT_SHAPE_PARAMS.angle),
+        donutRadius: num('donutRadius', DEFAULT_SHAPE_PARAMS.donutRadius),
+        width: num('width', DEFAULT_SHAPE_PARAMS.width),
+        height: num('height', DEFAULT_SHAPE_PARAMS.height),
+        column: num('column', DEFAULT_SHAPE_PARAMS.column),
+        row: num('row', DEFAULT_SHAPE_PARAMS.row),
+        mesh: anyShape.mesh as Mesh | undefined,
+    };
+}
+
+/** Which parameters are relevant per shape type (drives the UI). `mesh_surface`'s mesh
+ * reference isn't a NumberField, so it's handled separately by the Shape module. */
+export const SHAPE_PARAM_KEYS: {[K in ShapeType]: Array<keyof ShapeParams>} = {
+    point: [],
+    sphere: ['radius', 'arc', 'thickness'],
+    hemisphere: ['radius', 'arc', 'thickness'],
+    cone: ['radius', 'arc', 'thickness', 'angle'],
+    circle: ['radius', 'arc', 'thickness'],
+    donut: ['radius', 'arc', 'thickness', 'donutRadius'],
+    rectangle: ['width', 'height'],
+    grid: ['width', 'height', 'column', 'row'],
+    mesh_surface: [],
+};
+
+export function createShape(type: ShapeType, params: ShapeParams): EmitterShape {
+    switch (type) {
+        case 'point':
+            return new PointEmitter();
+        case 'sphere':
+            return new SphereEmitter({radius: params.radius, arc: params.arc, thickness: params.thickness, mode: params.mode, spread: params.spread});
+        case 'hemisphere':
+            return new HemisphereEmitter({radius: params.radius, arc: params.arc, thickness: params.thickness, mode: params.mode, spread: params.spread});
+        case 'cone':
+            return new ConeEmitter({
+                radius: params.radius,
+                arc: params.arc,
+                thickness: params.thickness,
+                angle: params.angle,
+                mode: params.mode,
+                spread: params.spread,
+            });
+        case 'circle':
+            return new CircleEmitter({radius: params.radius, arc: params.arc, thickness: params.thickness, mode: params.mode, spread: params.spread});
+        case 'donut':
+            return new DonutEmitter({
+                radius: params.radius,
+                arc: params.arc,
+                thickness: params.thickness,
+                donutRadius: params.donutRadius,
+                mode: params.mode,
+                spread: params.spread,
+            });
+        case 'rectangle':
+            return new RectangleEmitter({width: params.width, height: params.height, mode: params.mode, spread: params.spread});
+        case 'grid':
+            return new GridEmitter({width: params.width, height: params.height, column: params.column, row: params.row});
+        case 'mesh_surface':
+            return new MeshSurfaceEmitter(params.mesh);
+    }
+}

package/src/core/systems.ts

@@ -0,0 +1,98 @@
+import {
+    ConeEmitter,
+    ConstantColor,
+    ConstantValue,
+    IntervalValue,
+    ParticleSystem,
+    RenderMode,
+    Vector4,
+} from 'babylon.quarks';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {EffectBinding} from './binding';
+
+export interface ChildSystemOptions {
+    name?: string;
+    /** One-shot burst (sub-emitter target) instead of a looping stream. */
+    oneShot?: boolean;
+    /** Attach point override — defaults to `parent.emitter`. Lets a new system land as a
+     * sibling under a group node instead of nesting under an existing system. */
+    parentNode?: TransformNode;
+}
+
+/**
+ * Creates a child system sharing the parent's scene/texture/blending, parented to the
+ * parent emitter (or `options.parentNode` when given) — the Unity pattern where an effect is
+ * a hierarchy of systems and groups.
+ */
+export function createChildSystem(parent: ParticleSystem, options: ChildSystemOptions = {}): ParticleSystem {
+    const oneShot = options.oneShot ?? false;
+    const child = new ParticleSystem({
+        scene: parent.emitter.getScene(),
+        duration: oneShot ? 1 : parent.duration,
+        looping: !oneShot,
+        startLife: new IntervalValue(0.3, oneShot ? 0.6 : 1.2),
+        startSpeed: new IntervalValue(1, 3),
+        startSize: new IntervalValue(0.05, 0.2),
+        startColor: new ConstantColor(new Vector4(1, 0.9, 0.6, 1)),
+        emissionOverTime: new ConstantValue(oneShot ? 0 : 30),
+        emissionBursts: oneShot ? [{time: 0, count: new ConstantValue(8), cycle: 1, interval: 0.01, probability: 1}] : [],
+        shape: new ConeEmitter({radius: 0.1, angle: Math.PI / 3}),
+        renderMode: RenderMode.BillBoard,
+        texture: parent.texture ?? undefined,
+        transparent: true,
+        blendMode: parent.blending,
+        worldSpace: true,
+    });
+    child.emitter.name = options.name ?? (oneShot ? 'sub-emitter' : 'child-system');
+    if (oneShot) {
+        child.onlyUsedByOther = true;
+    }
+    child.emitter.parent = options.parentNode ?? parent.emitter;
+    return child;
+}
+
+/**
+ * Strips EmitSubParticleSystem behaviors that point at any of the removed systems, so
+ * deleting a sub-emitter target never leaves a dangling reference (which crashes the next
+ * update with `reading 'duration'` on the disposed emitter).
+ */
+export function unlinkSubEmitterReferences(systems: ParticleSystem[], removed: ParticleSystem[]): void {
+    const removedEmitters = new Set(removed.map((system) => system.emitter));
+    for (const system of systems) {
+        const behaviors = system.behaviors as Array<{type?: string; subParticleSystem?: unknown}>;
+        for (let i = behaviors.length - 1; i >= 0; i--) {
+            const behavior = behaviors[i];
+            if (behavior.type === 'EmitSubParticleSystem' && removedEmitters.has(behavior.subParticleSystem as never)) {
+                behaviors.splice(i, 1);
+            }
+        }
+    }
+}
+
+/** Disposes the given systems, first unlinking any sub-emitter behaviors that target them. */
+export function removeSystems(binding: EffectBinding, targets: ParticleSystem[], onSelect: (system: ParticleSystem) => void): void {
+    // binding.system is "removable" too as long as some other top-level system can take over
+    // as the new main — being main vs. sub is an internal bookkeeping detail, not something
+    // that should make one arbitrary track un-deletable in the UI.
+    if (targets.includes(binding.system)) {
+        const replacement = binding.subSystems.find((s) => !targets.includes(s) && !s.onlyUsedByOther);
+        if (replacement) {
+            binding.promoteToMain(replacement);
+        }
+    }
+    const removable = targets.filter((system) => binding.subSystems.includes(system));
+    if (removable.length === 0) {
+        return;
+    }
+    binding.apply(() => {
+        unlinkSubEmitterReferences([binding.system, ...binding.subSystems], removable);
+        for (const system of removable) {
+            system._renderer?.deleteSystem(system);
+            system.dispose();
+        }
+    });
+    for (const system of removable) {
+        binding.removeSubSystem(system);
+    }
+    onSelect(binding.system);
+}

package/src/core/textureExport.ts

@@ -0,0 +1,63 @@
+import type {Texture} from '@babylonjs/core/Materials/Textures/texture';
+
+const bakedUrls = new WeakMap<Texture, string>();
+
+/**
+ * Babylon's glTF loader gives embedded (base64-in-buffer) images a placeholder `data:` url
+ * (e.g. `data:leave.glb#image0`) that only works as an in-memory cache key paired with the
+ * pixel buffer it loaded alongside — it has no real payload, so a fresh Scene/Engine (e.g.
+ * after "Open in editor" navigates to a new page) can't refetch or reconstruct it from that
+ * string. Real data URIs always carry a comma-delimited payload; this placeholder never does.
+ */
+function isPortableUrl(url: string | null | undefined): boolean {
+    if (!url) {
+        return false;
+    }
+    return !url.startsWith('data:') || url.includes(',');
+}
+
+/**
+ * Ensures a texture's `.url` can be reloaded in a different Scene/Engine, baking its live
+ * GPU pixels into a real base64 PNG data URI when it currently only carries Babylon's
+ * internal placeholder url (see isPortableUrl). No-ops for textures that already have a
+ * fetchable or real `data:` url. Call before serializing a scene that will be reloaded
+ * elsewhere — e.g. the demo viewer's "Open in editor" handoff, which navigates to a new page.
+ */
+export async function ensurePortableTextureUrl(texture: Texture): Promise<void> {
+    if (isPortableUrl(texture.url)) {
+        return;
+    }
+    const cached = bakedUrls.get(texture);
+    if (cached) {
+        texture.url = cached;
+        return;
+    }
+    const dataUrl = await bakeTextureToDataUrl(texture);
+    if (dataUrl) {
+        bakedUrls.set(texture, dataUrl);
+        texture.url = dataUrl;
+    }
+}
+
+async function bakeTextureToDataUrl(texture: Texture): Promise<string | undefined> {
+    const size = texture.getSize();
+    if (!size.width || !size.height) {
+        return undefined;
+    }
+    const pixels = await texture.readPixels();
+    if (!(pixels instanceof Uint8Array || pixels instanceof Uint8ClampedArray)) {
+        return undefined;
+    }
+    const canvas = document.createElement('canvas');
+    canvas.width = size.width;
+    canvas.height = size.height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        return undefined;
+    }
+    // Copy (rather than wrap) so the result is backed by a plain ArrayBuffer — ImageData
+    // rejects the SharedArrayBuffer-compatible view type `readPixels` may hand back.
+    const bytes = new Uint8ClampedArray(pixels);
+    ctx.putImageData(new ImageData(bytes, size.width, size.height), 0, 0);
+    return canvas.toDataURL('image/png');
+}

package/src/core/timeline.ts

@@ -0,0 +1,94 @@
+import type {ParticleSystem} from 'babylon.quarks';
+import {ConstantValue, IntervalValue} from 'babylon.quarks';
+import type {FunctionValueGenerator, ValueGenerator} from 'babylon.quarks';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {EffectBinding} from './binding';
+import type {EffectTreeNode} from './effectTree';
+
+const MIN_TIMELINE_SPAN = 4;
+
+export type TimelineRow =
+    | {kind: 'group'; node: TransformNode; name: string; depth: number}
+    | {
+          kind: 'track';
+          node: TransformNode;
+          system: ParticleSystem;
+          name: string;
+          depth: number;
+          isRoot: boolean;
+          removable: boolean;
+          startOffset: number;
+          startOffsetVariable: boolean;
+          duration: number;
+          looping: boolean;
+      };
+
+/**
+ * Reads a representative start-delay value for display without invoking the generator's
+ * stateful `genValue` (IntervalValue caches its sampled slot on first call and returns NaN
+ * on a later call with a fresh memory array, so it can't be safely re-read on every render).
+ */
+export function computeStartOffset(gen: ValueGenerator | FunctionValueGenerator): {value: number; startOffsetVariable: boolean} {
+    if (gen instanceof ConstantValue) {
+        return {value: gen.value, startOffsetVariable: false};
+    }
+    if (gen instanceof IntervalValue) {
+        return {value: Math.min(gen.a, gen.b), startOffsetVariable: false};
+    }
+    return {value: 0, startOffsetVariable: true};
+}
+
+/**
+ * Whether a track can be removed. Sub-systems always can; the designated "main" system can
+ * too as long as another top-level system remains to take over that role — being main vs.
+ * sub is an internal bookkeeping detail (see EffectBinding.promoteToMain), not something that
+ * should make one arbitrary track permanently un-deletable in the UI.
+ */
+function isRemovable(binding: EffectBinding, system: ParticleSystem): boolean {
+    if (binding.subSystems.includes(system)) {
+        return true;
+    }
+    if (system === binding.system) {
+        return binding.subSystems.some((s) => !s.onlyUsedByOther);
+    }
+    return false;
+}
+
+/** Flattens the effect's group/emitter tree into display rows, preserving tree-walk order. */
+export function computeTimelineRows(binding: EffectBinding): TimelineRow[] {
+    const rows: TimelineRow[] = [];
+    const walk = (node: EffectTreeNode) => {
+        if (node.system) {
+            const {value, startOffsetVariable} = computeStartOffset(node.system.startDelay);
+            rows.push({
+                kind: 'track',
+                node: node.node,
+                system: node.system,
+                name: node.name,
+                depth: node.depth,
+                isRoot: node.node === binding.root,
+                removable: isRemovable(binding, node.system),
+                startOffset: value,
+                startOffsetVariable,
+                duration: node.system.duration,
+                looping: node.system.looping,
+            });
+        } else {
+            rows.push({kind: 'group', node: node.node, name: node.name, depth: node.depth});
+        }
+        node.children.forEach(walk);
+    };
+    walk(binding.getTree());
+    return rows;
+}
+
+/** Overall visible timeline span: the furthest track extent, floored at a sane minimum. */
+export function computeTimelineSpan(rows: TimelineRow[]): number {
+    let span = 0;
+    for (const row of rows) {
+        if (row.kind === 'track') {
+            span = Math.max(span, row.startOffset + row.duration);
+        }
+    }
+    return Math.max(span, MIN_TIMELINE_SPAN);
+}

package/src/core/values.ts

@@ -0,0 +1,113 @@
+import {Bezier, ConstantValue, IntervalValue, PiecewiseBezier} from 'babylon.quarks';
+import type {FunctionValueGenerator, ValueGenerator} from 'babylon.quarks';
+
+export type ScalarGenerator = ValueGenerator | FunctionValueGenerator;
+export type ScalarMode = 'constant' | 'random' | 'curve';
+
+/** Editable snapshot of a scalar value generator. */
+export interface ScalarValueState {
+    mode: ScalarMode;
+    /** Constant value (mode: constant). */
+    value: number;
+    /** Random range (mode: random). */
+    min: number;
+    max: number;
+    /** Cubic bezier control values over normalized lifetime (mode: curve). */
+    curve: [number, number, number, number];
+}
+
+export function readScalar(generator: ScalarGenerator | undefined): ScalarValueState {
+    const state: ScalarValueState = {mode: 'constant', value: 1, min: 0.5, max: 1.5, curve: [0, 1, 1, 0]};
+    if (generator instanceof ConstantValue) {
+        state.mode = 'constant';
+        state.value = generator.value;
+        state.min = generator.value * 0.5;
+        state.max = generator.value * 1.5;
+    } else if (generator instanceof IntervalValue) {
+        state.mode = 'random';
+        state.min = generator.a;
+        state.max = generator.b;
+        state.value = (generator.a + generator.b) / 2;
+    } else if (generator instanceof PiecewiseBezier) {
+        state.mode = 'curve';
+        const first = generator.functions[0]?.[0];
+        if (first) {
+            state.curve = [first.p[0], first.p[1], first.p[2], first.p[3]];
+            state.value = first.p[0];
+        }
+    }
+    return state;
+}
+
+export function buildScalar(state: ScalarValueState): ScalarGenerator {
+    switch (state.mode) {
+        case 'constant':
+            return new ConstantValue(state.value);
+        case 'random':
+            return new IntervalValue(Math.min(state.min, state.max), Math.max(state.min, state.max));
+        case 'curve':
+            return new PiecewiseBezier([[new Bezier(...state.curve), 0]]);
+    }
+}
+
+/** One segment of a piecewise bezier curve: start x (0..1) + four control values. */
+export interface CurvePiece {
+    start: number;
+    p: [number, number, number, number];
+}
+
+/** Reads pieces from a PiecewiseBezier (or synthesizes one segment for other generators). */
+export function readPieces(generator: ScalarGenerator | undefined): CurvePiece[] {
+    if (generator instanceof PiecewiseBezier && generator.functions.length > 0) {
+        return generator.functions.map(([bezier, start]) => ({
+            start,
+            p: [bezier.p[0], bezier.p[1], bezier.p[2], bezier.p[3]] as [number, number, number, number],
+        }));
+    }
+    const fallback = readScalar(generator);
+    return [{start: 0, p: fallback.curve}];
+}
+
+export function buildCurve(pieces: CurvePiece[]): PiecewiseBezier {
+    const sorted = [...pieces].sort((a, b) => a.start - b.start);
+    return new PiecewiseBezier(sorted.map((piece) => [new Bezier(...piece.p), piece.start] as [Bezier, number]));
+}
+
+/** Splits the piece containing x into two exact halves using Bezier.split. */
+export function splitPieces(pieces: CurvePiece[], x: number): CurvePiece[] {
+    const sorted = [...pieces].sort((a, b) => a.start - b.start);
+    for (let i = 0; i < sorted.length; i++) {
+        const end = i + 1 < sorted.length ? sorted[i + 1].start : 1;
+        if (x > sorted[i].start + 0.02 && x < end - 0.02) {
+            const t = (x - sorted[i].start) / (end - sorted[i].start);
+            const {left, right} = new Bezier(...sorted[i].p).split(t);
+            sorted.splice(
+                i,
+                1,
+                {start: sorted[i].start, p: [left.p[0], left.p[1], left.p[2], left.p[3]]},
+                {start: x, p: [right.p[0], right.p[1], right.p[2], right.p[3]]}
+            );
+            return sorted;
+        }
+    }
+    return sorted;
+}
+
+/** Removes the boundary at pieces[index].start by merging with the previous piece. */
+export function mergePieces(pieces: CurvePiece[], index: number): CurvePiece[] {
+    if (index <= 0 || index >= pieces.length) {
+        return pieces;
+    }
+    const sorted = [...pieces].sort((a, b) => a.start - b.start);
+    const a = sorted[index - 1];
+    const b = sorted[index];
+    sorted.splice(index - 1, 2, {start: a.start, p: [a.p[0], a.p[1], b.p[2], b.p[3]]});
+    return sorted;
+}
+
+/** Samples a cubic bezier defined by four control values at normalized t. */
+export function sampleCurve(curve: [number, number, number, number], t: number): number {
+    const [p0, p1, p2, p3] = curve;
+    const u = 1 - t;
+    return u * u * u * p0 + 3 * u * u * t * p1 + 3 * u * t * t * p2 + t * t * t * p3;
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+export {EffectBinding} from './core/binding';
+export type {EditorListener} from './core/binding';
+export {EffectHistory} from './core/history';
+export {createChildSystem} from './core/systems';
+export {buildEffectTree, collectSystems, serializeEffectTree, serializeEffectForest} from './core/effectTree';
+export type {EffectTreeNode} from './core/effectTree';
+export type {ChildSystemOptions} from './core/systems';
+export {readScalar, buildScalar, sampleCurve, readPieces, buildCurve, splitPieces, mergePieces} from './core/values';
+export type {ScalarGenerator, ScalarMode, ScalarValueState, CurvePiece} from './core/values';
+export {
+    DEFAULT_GRADIENT_STOPS,
+    buildGradient,
+    buildColorOverLife,
+    rgbaToVector4,
+    stopToCss,
+    stopsToCssGradient,
+    hexToRgb,
+    rgbToHex,
+    findBehavior,
+} from './core/colors';
+export type {GradientStop} from './core/colors';
+export {
+    SHAPE_TYPES,
+    SHAPE_PARAM_KEYS,
+    DEFAULT_SHAPE_PARAMS,
+    getShapeType,
+    readShapeParams,
+    createShape,
+} from './core/shapes';
+export type {ShapeType, ShapeParams} from './core/shapes';
+export {GroundPlaneResolver, ensureGroundResolver} from './core/collision';
+export {ensurePortableTextureUrl} from './core/textureExport';