babylon.quarks-editor 0.27.0 → 0.29.0

package/dist/core/effectTree.d.ts

@@ -1,12 +1,17 @@
 import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
 import type { ParticleSystem } from 'babylon.quarks';
 /** A node in the editor's effect hierarchy: a Group (organizational) or a ParticleEmitter. */
+/** One node of an effect's tree: a group, or an emitter with its system. */
 export interface EffectTreeNode {
+    /** The node. */
     node: TransformNode;
+    /** The node's name, or a readable stand-in when it has none. */
     name: string;
     /** Present when the node is a ParticleEmitter. */
     system?: ParticleSystem;
+    /** How deep the node sits; the root is 0. */
     depth: number;
+    /** The node's child groups and emitters. */
     children: EffectTreeNode[];
 }
 /** Walks a loaded root TransformNode into the editor tree (groups + emitters). */

package/dist/core/emitterShapeWireframe.js

@@ -2,6 +2,7 @@ import { Color3 } from '@babylonjs/core/Maths/math.color.js';
 import { Vector3 } from '@babylonjs/core/Maths/math.vector.js';
 import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder.js';
 import { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
+import { ConeEmitFrom } from 'babylon.quarks';
 import { EDITOR_SCENE_NODE_METADATA } from './editorScene.js';
 import './lineShaders.js';
 import { getShapeType, readShapeParams } from './shapes.js';
@@ -103,17 +104,23 @@ function buildEmitterWireframe(system, scene) {
                 lines('wf-cone-spoke-a', [Vector3.Zero(), arcPoint(radius, 0)]);
                 lines('wf-cone-spoke-b', [Vector3.Zero(), arcPoint(radius, arc)]);
             }
-            const preview = Math.max(radius * 2, 1.25);
-            const farRadius = radius + preview * Math.tan(angle);
+            // Emit from Volume draws the volume itself, out to its length; the base a stretch of the
+            // directions.
+            const preview = params.coneEmitFrom === ConeEmitFrom.Volume
+                ? Math.max(Number.isFinite(params.length) ? params.length : 0, 0.001)
+                : Math.max(radius * 2, 1.25);
+            // The rays and the far rim end at the same point, which a near-flat cone keeps in view.
+            const travel = preview / Math.max(Math.cos(angle), 0.05);
+            const farRadius = radius + Math.sin(angle) * travel;
+            const farZ = Math.cos(angle) * travel;
             const spokeCount = Math.max(4, Math.ceil((arc / (Math.PI * 2)) * 12));
             for (let i = 0; i <= spokeCount; i++) {
                 const theta = (i / spokeCount) * arc;
                 const rim = arcPoint(radius, theta);
                 const dir = new Vector3(Math.sin(angle) * Math.cos(theta), Math.sin(angle) * Math.sin(theta), Math.cos(angle));
-                const travel = preview / Math.max(Math.cos(angle), 0.05);
                 lines(`wf-cone-ray-${i}`, [rim, rim.add(dir.scale(travel))], DIRECTION_COLOR);
             }
-            lines('wf-cone-far', xyArc(farRadius, arc, 32, preview), DIRECTION_COLOR);
+            lines('wf-cone-far', xyArc(farRadius, arc, 32, farZ), DIRECTION_COLOR);
             break;
         }
         case 'sphere': {

package/dist/core/galleryPlayback.js

@@ -20,7 +20,8 @@ export function applyGalleryPlayback(entries, previewRootIds, transportPlaying,
             continue;
         }
         for (const system of entry.systems) {
-            system.play();
+            // Undoes the pause above; a finished effect stays finished.
+            system.resume();
         }
     }
 }

package/dist/core/history.d.ts

@@ -1,7 +1,9 @@
 import type { EffectBinding } from './binding.js';
 /** Undo/redo stacks of one effect, kept by the host while another effect is focused. */
 export interface HistoryStacks {
+    /** Snapshots to undo to, oldest first. */
     undo: string[];
+    /** Snapshots to redo to, most recent undo last. */
     redo: string[];
 }
 /**
@@ -18,11 +20,15 @@ export declare class EffectHistory {
     private binding;
     /** Points the history at the active binding and hooks snapshot capture. */
     attach(binding: EffectBinding): void;
+    /** There is a change to undo. */
     get canUndo(): boolean;
+    /** There is an undone change to redo. */
     get canRedo(): boolean;
+    /** Forgets every snapshot. */
     clear(): void;
     /** The current stacks, to hand back to `restoreStacks` when this effect is focused again. */
     saveStacks(): HistoryStacks;
+    /** Puts back stacks from `saveStacks`; undefined starts empty. */
     restoreStacks(stacks: HistoryStacks | undefined): void;
     /**
      * Pushes an undo snapshot. A burst of edits — typing a number, dragging a curve handle or a

package/dist/core/history.js

@@ -19,12 +19,15 @@ export class EffectHistory {
         this.binding = binding;
         binding.onBeforeChange = () => this.capture();
     }
+    /** There is a change to undo. */
     get canUndo() {
         return this.undoStack.length > 0;
     }
+    /** There is an undone change to redo. */
     get canRedo() {
         return this.redoStack.length > 0;
     }
+    /** Forgets every snapshot. */
     clear() {
         this.undoStack = [];
         this.redoStack = [];
@@ -34,6 +37,7 @@ export class EffectHistory {
     saveStacks() {
         return { undo: this.undoStack, redo: this.redoStack };
     }
+    /** Puts back stacks from `saveStacks`; undefined starts empty. */
     restoreStacks(stacks) {
         this.undoStack = stacks?.undo ?? [];
         this.redoStack = stacks?.redo ?? [];

package/dist/core/indexedDbProjectStore.d.ts

@@ -11,18 +11,31 @@ export declare class IndexedDbProjectStore implements ProjectStore {
     /** `${projectId}/${hash}` → data URI, so every effect sharing a file gets the same string. */
     private readonly dataUrlByFile;
     private db;
+    /** {@inheritDoc ProjectStore.listProjects} */
     listProjects(): Promise<ProjectMeta[]>;
+    /** {@inheritDoc ProjectStore.getProject} */
     getProject(id: string): Promise<ProjectMeta | null>;
+    /** {@inheritDoc ProjectStore.createProject} */
     createProject(name: string): Promise<ProjectMeta>;
+    /** {@inheritDoc ProjectStore.renameProject} */
     renameProject(id: string, name: string): Promise<void>;
+    /** {@inheritDoc ProjectStore.duplicateProject} */
     duplicateProject(id: string, name: string): Promise<ProjectMeta>;
+    /** {@inheritDoc ProjectStore.deleteProject} */
     deleteProject(id: string): Promise<void>;
+    /** {@inheritDoc ProjectStore.loadAssets} */
     loadAssets(projectId: string): Promise<StoredAsset[]>;
+    /** {@inheritDoc ProjectStore.putAssets} */
     putAssets(projectId: string, assets: StoredAsset[]): Promise<void>;
+    /** {@inheritDoc ProjectStore.deleteAssets} */
     deleteAssets(projectId: string, paths: string[]): Promise<void>;
+    /** {@inheritDoc ProjectStore.loadScene} */
     loadScene(projectId: string): Promise<StoredScene | null>;
+    /** {@inheritDoc ProjectStore.saveScene} */
     saveScene(projectId: string, scene: StoredScene): Promise<void>;
+    /** {@inheritDoc ProjectStore.estimate} */
     estimate(): Promise<StorageEstimate>;
+    /** {@inheritDoc ProjectStore.requestPersistence} */
     requestPersistence(): Promise<boolean>;
     /** Clones `json` with each texture data URI replaced by a `quarks-file:<hash>` reference. */
     private pack;

package/dist/core/indexedDbProjectStore.js

@@ -84,15 +84,18 @@ export class IndexedDbProjectStore {
         return this.dbPromise;
     }
     // ---- projects -------------------------------------------------------------------------
+    /** {@inheritDoc ProjectStore.listProjects} */
     async listProjects() {
         const db = await this.db();
         const all = await request(db.transaction('projects').objectStore('projects').getAll());
         return all.sort((a, b) => b.updatedAt - a.updatedAt);
     }
+    /** {@inheritDoc ProjectStore.getProject} */
     async getProject(id) {
         const db = await this.db();
         return ((await request(db.transaction('projects').objectStore('projects').get(id))) ?? null);
     }
+    /** {@inheritDoc ProjectStore.createProject} */
     async createProject(name) {
         const now = Date.now();
         const meta = { id: newId(), name, createdAt: now, updatedAt: now, assetCount: 0, sizeBytes: 0 };
@@ -102,6 +105,7 @@ export class IndexedDbProjectStore {
         await done(tx);
         return meta;
     }
+    /** {@inheritDoc ProjectStore.renameProject} */
     async renameProject(id, name) {
         const meta = await this.getProject(id);
         if (!meta)
@@ -111,6 +115,7 @@ export class IndexedDbProjectStore {
         tx.objectStore('projects').put({ ...meta, name, updatedAt: Date.now() });
         await done(tx);
     }
+    /** {@inheritDoc ProjectStore.duplicateProject} */
     async duplicateProject(id, name) {
         const source = await this.getProject(id);
         if (!source)
@@ -135,6 +140,7 @@ export class IndexedDbProjectStore {
         await done(tx);
         return meta;
     }
+    /** {@inheritDoc ProjectStore.deleteProject} */
     async deleteProject(id) {
         const db = await this.db();
         const tx = db.transaction(['projects', 'assets', 'files', 'scenes'], 'readwrite');
@@ -152,6 +158,7 @@ export class IndexedDbProjectStore {
         }
     }
     // ---- assets ---------------------------------------------------------------------------
+    /** {@inheritDoc ProjectStore.loadAssets} */
     async loadAssets(projectId) {
         const db = await this.db();
         const records = await request(db.transaction('assets').objectStore('assets').index('projectId').getAll(projectId));
@@ -162,6 +169,7 @@ export class IndexedDbProjectStore {
             missingFiles,
         })));
     }
+    /** {@inheritDoc ProjectStore.putAssets} */
     async putAssets(projectId, assets) {
         const files = new Map();
         const packed = await Promise.all(assets.map(async (asset) => ({ ...asset, projectId, json: await this.pack(asset.json, files) })));
@@ -173,6 +181,7 @@ export class IndexedDbProjectStore {
         await done(tx);
         await this.refresh(projectId);
     }
+    /** {@inheritDoc ProjectStore.deleteAssets} */
     async deleteAssets(projectId, paths) {
         const db = await this.db();
         const tx = db.transaction('assets', 'readwrite');
@@ -182,6 +191,7 @@ export class IndexedDbProjectStore {
         await this.refresh(projectId);
     }
     // ---- scene ----------------------------------------------------------------------------
+    /** {@inheritDoc ProjectStore.loadScene} */
     async loadScene(projectId) {
         const db = await this.db();
         const record = await request(db.transaction('scenes').objectStore('scenes').get(projectId));
@@ -190,6 +200,7 @@ export class IndexedDbProjectStore {
         const entries = await Promise.all(record.entries.map(async (entry) => ({ ...entry, json: await this.unpack(projectId, entry.json) })));
         return { entries, savedAt: record.savedAt };
     }
+    /** {@inheritDoc ProjectStore.saveScene} */
     async saveScene(projectId, scene) {
         const files = new Map();
         const entries = await Promise.all(scene.entries.map(async (entry) => ({ ...entry, json: await this.pack(entry.json, files) })));
@@ -201,12 +212,14 @@ export class IndexedDbProjectStore {
         await this.refresh(projectId);
     }
     // ---- storage ----------------------------------------------------------------------------
+    /** {@inheritDoc ProjectStore.estimate} */
     async estimate() {
         const storage = typeof navigator !== 'undefined' ? navigator.storage : undefined;
         const estimate = storage?.estimate ? await storage.estimate() : undefined;
         const persisted = storage?.persisted ? await storage.persisted() : false;
         return { usage: estimate?.usage ?? null, quota: estimate?.quota ?? null, persisted };
     }
+    /** {@inheritDoc ProjectStore.requestPersistence} */
     async requestPersistence() {
         const storage = typeof navigator !== 'undefined' ? navigator.storage : undefined;
         return storage?.persist ? storage.persist() : false;

package/dist/core/loadEffect.js

@@ -79,6 +79,8 @@ export function parseEffectFromJson(scene, renderer, json, options = {}, baseUrl
     const systems = [];
     QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
         const system = emitter.system;
+        // The editor previews over and over; the stop action is saved, not applied.
+        system.ignoreStopAction = true;
         if (registerRenderer && renderer) {
             renderer.addSystem(system);
         }

package/dist/core/material.d.ts

@@ -1,13 +1,23 @@
+import type { BaseTexture } from '@babylonjs/core/Materials/Textures/baseTexture.js';
+import type { Texture } from '@babylonjs/core/Materials/Textures/texture.js';
 import type { ParticleSystem } from 'babylon.quarks';
+/** Material settings the Renderer module changes; fields left out keep their value. */
 export interface RendererMaterialPatch {
+    /** The blend mode, see `ParticleSystem.blending`. */
     blendMode?: number;
+    /** Draws with alpha blending. */
     transparent?: boolean;
+    /** Tests against the depth buffer. */
     depthTest?: boolean;
+    /** Writes to the depth buffer. */
     depthWrite?: boolean;
+    /** Discards pixels whose alpha is below this. */
     alphaTest?: number;
-    texture?: unknown;
+    /** The main texture, or null for none. */
+    texture?: Texture | null;
     /** A 3×2 cube-face atlas mesh particles reflect, or null for none. */
-    reflectionAtlas?: unknown;
+    reflectionAtlas?: BaseTexture | null;
+    /** How strongly mesh particles reflect the atlas, 0..1. */
     reflectionLevel?: number;
 }
 /** Applies renderer material settings and keeps imported QuarksMaterial JSON in sync for export. */

package/dist/core/playback.d.ts

@@ -2,11 +2,17 @@
 export interface PlaybackState {
     /** When true, all in-scene preview effects simulate. */
     stagePlaying: boolean;
+    /** Root `uniqueId` of the focused effect, whose time the timeline shows. */
     focusRootId: number | null;
+    /** Each effect's timeline time, in seconds, by root `uniqueId`. */
     focusElapsedByRoot: Map<number, number>;
+    /** Effects parked at their end, by root `uniqueId`; Play restarts them. */
     focusFinishedByRoot: Set<number>;
+    /** Playback speed, 1 for real time. */
     speed: number;
+    /** While paused: advance one frame on the next render. */
     stepQueued: boolean;
+    /** The timeline is being scrubbed; the render loop does not simulate. */
     scrubbing: boolean;
 }
 /** Default playback state for a new editor session. */

package/dist/core/projectStore.d.ts

@@ -1,9 +1,14 @@
 /** One editor project: a library of effect assets plus the scene built from them. */
 export interface ProjectMeta {
+    /** The project's key in its store. */
     id: string;
+    /** The project's display name. */
     name: string;
+    /** When the project was created, in milliseconds since the epoch. */
     createdAt: number;
+    /** When the project last changed, in milliseconds since the epoch. */
     updatedAt: number;
+    /** How many effect assets the project holds. */
     assetCount: number;
     /** Approximate bytes the project takes in storage (JSON + texture files). */
     sizeBytes: number;
@@ -12,23 +17,32 @@ export interface ProjectMeta {
 export interface StoredAsset {
     /** Relative path inside the project (`Fire/Explosion.json`) — the asset's key. */
     path: string;
+    /** The asset's display name, its file name without `.json`. */
     name: string;
+    /** The effect, as quarks JSON with its textures inlined. */
     json: unknown;
+    /** Files the effect referenced that were not imported with it. */
     missingFiles: string[];
 }
 /** One effect instance in a saved scene. */
 export interface StoredSceneEntry {
+    /** The instance's name in the Scene list. */
     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;
+    /** Whether the instance was shown. */
     visible: boolean;
 }
+/** A project's saved scene: the effects placed in it, in Scene list order. */
 export interface StoredScene {
+    /** The scene's effect instances. */
     entries: StoredSceneEntry[];
+    /** When it was saved, in milliseconds since the epoch. */
     savedAt: number;
 }
+/** How much storage projects use, as far as the browser tells. */
 export interface StorageEstimate {
     /** Bytes the whole site uses (all projects), when the browser reports it. */
     usage: number | null;
@@ -42,20 +56,32 @@ export interface StorageEstimate {
  * everything in the browser, and an embedding host can supply its own (e.g. on disk).
  */
 export interface ProjectStore {
+    /** Every project, most recently changed first. */
     listProjects(): Promise<ProjectMeta[]>;
+    /** One project, or null when there is none with that id. */
     getProject(id: string): Promise<ProjectMeta | null>;
+    /** Creates an empty project. */
     createProject(name: string): Promise<ProjectMeta>;
+    /** Renames a project. */
     renameProject(id: string, name: string): Promise<void>;
+    /** Copies a project, its assets and its scene, under a new name. */
     duplicateProject(id: string, name: string): Promise<ProjectMeta>;
+    /** Deletes a project, its assets and its scene. */
     deleteProject(id: string): Promise<void>;
+    /** A project's assets. */
     loadAssets(projectId: string): Promise<StoredAsset[]>;
     /** Adds or replaces assets by path. */
     putAssets(projectId: string, assets: StoredAsset[]): Promise<void>;
+    /** Deletes assets by path; paths it does not have are ignored. */
     deleteAssets(projectId: string, paths: string[]): Promise<void>;
+    /** A project's saved scene, or null when it was never saved. */
     loadScene(projectId: string): Promise<StoredScene | null>;
+    /** Replaces a project's saved scene. */
     saveScene(projectId: string, scene: StoredScene): Promise<void>;
+    /** How much storage projects use. */
     estimate(): Promise<StorageEstimate>;
     /** Asks the browser to keep the data even under storage pressure; resolves to the result. */
     requestPersistence(): Promise<boolean>;
 }
+/** A byte count for people: `512 B`, `1.5 KB`, `20 MB`; `—` when unknown. */
 export declare function formatBytes(bytes: number | null | undefined): string;

package/dist/core/projectStore.js

@@ -1,3 +1,4 @@
+/** A byte count for people: `512 B`, `1.5 KB`, `20 MB`; `—` when unknown. */
 export function formatBytes(bytes) {
     if (bytes == null)
         return '—';

package/dist/core/sceneEntries.d.ts

@@ -9,12 +9,15 @@ import { EffectBinding } from './binding.js';
  * that are edited separately.
  */
 export interface SceneEntry {
+    /** The instance's name in the Scene list, unique in the scene. */
     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;
+    /** The instance's root node. */
     root: TransformNode;
+    /** Every particle system of the instance. */
     systems: ParticleSystem[];
 }
 /** `name`, or `name (2)`, `name (3)`… when an entry already uses it. */

package/dist/core/scrub.d.ts

@@ -1,6 +1,6 @@
 import type { BatchedRenderer } from 'babylon.quarks';
 import type { EffectBinding } from './binding.js';
-/** Unpauses every system in the focused effect. */
+/** Unpauses every system in the focused effect; one that has finished stays finished. */
 export declare function playFocus(binding: EffectBinding): void;
 /** Freezes the focused effect at its current simulation state. */
 export declare function pauseFocus(binding: EffectBinding): void;

package/dist/core/scrub.js

@@ -2,10 +2,10 @@ const WIDE_STEP_THRESHOLD = 8;
 function bindingSystems(binding) {
     return [binding.system, ...binding.subSystems];
 }
-/** Unpauses every system in the focused effect. */
+/** Unpauses every system in the focused effect; one that has finished stays finished. */
 export function playFocus(binding) {
     for (const system of bindingSystems(binding)) {
-        system.play();
+        system.resume();
     }
 }
 /** Freezes the focused effect at its current simulation state. */

package/dist/core/shapes.d.ts

@@ -1,37 +1,67 @@
 import type { Mesh } from '@babylonjs/core/Meshes/mesh.js';
 import type { EmitterShape } from 'babylon.quarks';
-import { BoxEmitFrom, EmitterMode } from 'babylon.quarks';
+import { BoxEmitFrom, ConeEmitFrom, EmitterMode, GridSampling } from 'babylon.quarks';
+/** The emitter shapes the Shape module offers, by the `type` they serialise with. */
 export type ShapeType = 'point' | 'sphere' | 'hemisphere' | 'cone' | 'circle' | 'donut' | 'rectangle' | 'grid' | 'box' | 'edge' | 'mesh_surface';
+/** The Shape module's shape list, in menu order, with the label each shows. */
 export declare const SHAPE_TYPES: Array<{
+    /** The shape's type. */
     value: ShapeType;
+    /** Its label in the menu. */
     label: string;
 }>;
+/**
+ * Every shape's settings in one flat record, so switching shapes keeps what the shapes share
+ * (a cone's radius becomes the sphere's). Each shape reads the fields it has.
+ */
 export interface ShapeParams {
+    /** Radius of a sphere, hemisphere, cone, circle or donut. */
     radius: number;
+    /** The part of the circle emitted from, in radians (2π: all of it). */
     arc: number;
+    /** 0 emits from the surface only, 1 from the whole volume. */
     thickness: number;
+    /** A cone's half angle, in radians. */
     angle: number;
+    /** The radius of a donut's tube. */
     donutRadius: number;
+    /** Width of a rectangle, grid or box (X). */
     width: number;
+    /** Height of a rectangle, grid or box (Y). */
     height: number;
+    /** How points around the arc are picked: at random, in a loop, back and forth or in bursts. */
     mode: EmitterMode;
+    /** Snaps the arc position to steps of this fraction; 0 for none. */
     spread: number;
+    /** A grid's column count. */
     column: number;
+    /** A grid's row count. */
     row: number;
     /** Box depth (Z). */
     depth: number;
     /** Where a box emits from: its volume, its faces or its edges. */
     emitFrom: BoxEmitFrom;
+    /** Where a cone emits from: its base or its volume. */
+    coneEmitFrom: ConeEmitFrom;
+    /** Height of a cone's volume (Unity's Length), for Emit from Volume. */
+    length: number;
+    /** How a grid picks its cells: at random or in turn. */
+    sampling: GridSampling;
     /** How fast an edge emitter's loop / ping-pong point travels, in lengths per second. */
     speed: number;
+    /** The mesh a mesh surface emitter emits from. */
     mesh?: Mesh;
 }
+/** The settings a new shape starts from. */
 export declare const DEFAULT_SHAPE_PARAMS: ShapeParams;
+/** The type of a shape, as the Shape module lists it. */
 export declare function getShapeType(shape: EmitterShape): ShapeType;
+/** A shape's settings, the fields it does not have taken from {@link DEFAULT_SHAPE_PARAMS}. */
 export declare function readShapeParams(shape: EmitterShape): ShapeParams;
 /** 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 declare const SHAPE_PARAM_KEYS: {
     [K in ShapeType]: Array<keyof ShapeParams>;
 };
+/** A new shape of `type`, built from the fields of `params` it has. */
 export declare function createShape(type: ShapeType, params: ShapeParams): EmitterShape;

package/dist/core/shapes.js

@@ -1,4 +1,5 @@
-import { BoxEmitFrom, BoxEmitter, CircleEmitter, ConeEmitter, ConstantValue, DonutEmitter, EdgeEmitter, EmitterMode, GridEmitter, HemisphereEmitter, MeshSurfaceEmitter, PointEmitter, RectangleEmitter, SphereEmitter, } from 'babylon.quarks';
+import { BoxEmitFrom, BoxEmitter, CircleEmitter, ConeEmitFrom, ConeEmitter, ConstantValue, DonutEmitter, EdgeEmitter, EmitterMode, GridEmitter, GridSampling, HemisphereEmitter, MeshSurfaceEmitter, PointEmitter, RectangleEmitter, SphereEmitter, } from 'babylon.quarks';
+/** The Shape module's shape list, in menu order, with the label each shows. */
 export const SHAPE_TYPES = [
     { value: 'cone', label: 'Cone' },
     { value: 'sphere', label: 'Sphere' },
@@ -12,6 +13,7 @@ export const SHAPE_TYPES = [
     { value: 'mesh_surface', label: 'Mesh surface' },
     { value: 'point', label: 'Point' },
 ];
+/** The settings a new shape starts from. */
 export const DEFAULT_SHAPE_PARAMS = {
     radius: 0.3,
     arc: Math.PI * 2,
@@ -26,13 +28,18 @@ export const DEFAULT_SHAPE_PARAMS = {
     row: 10,
     depth: 1,
     emitFrom: BoxEmitFrom.Volume,
+    coneEmitFrom: ConeEmitFrom.Base,
+    length: 5,
+    sampling: GridSampling.Random,
     speed: 1,
     mesh: undefined,
 };
+/** The type of a shape, as the Shape module lists it. */
 export function getShapeType(shape) {
     const type = shape.type ?? 'point';
     return (SHAPE_TYPES.some((s) => s.value === type) ? type : 'point');
 }
+/** A shape's settings, the fields it does not have taken from {@link DEFAULT_SHAPE_PARAMS}. */
 export function readShapeParams(shape) {
     const anyShape = shape;
     const num = (key, fallback) => typeof anyShape[key] === 'number' ? anyShape[key] : fallback;
@@ -49,7 +56,11 @@ export function readShapeParams(shape) {
         column: num('column', DEFAULT_SHAPE_PARAMS.column),
         row: num('row', DEFAULT_SHAPE_PARAMS.row),
         depth: num('depth', DEFAULT_SHAPE_PARAMS.depth),
-        emitFrom: num('emitFrom', DEFAULT_SHAPE_PARAMS.emitFrom),
+        // A box and a cone both name it emitFrom, with different enums: each keeps its own.
+        emitFrom: shape instanceof BoxEmitter ? shape.emitFrom : DEFAULT_SHAPE_PARAMS.emitFrom,
+        coneEmitFrom: shape instanceof ConeEmitter ? shape.emitFrom : DEFAULT_SHAPE_PARAMS.coneEmitFrom,
+        length: num('length', DEFAULT_SHAPE_PARAMS.length),
+        sampling: num('sampling', DEFAULT_SHAPE_PARAMS.sampling),
         speed: anyShape.speed instanceof ConstantValue ? anyShape.speed.value : DEFAULT_SHAPE_PARAMS.speed,
         mesh: anyShape.mesh,
     };
@@ -60,7 +71,7 @@ export const SHAPE_PARAM_KEYS = {
     point: [],
     sphere: ['radius', 'arc', 'thickness'],
     hemisphere: ['radius', 'arc', 'thickness'],
-    cone: ['radius', 'arc', 'thickness', 'angle'],
+    cone: ['radius', 'arc', 'thickness', 'angle', 'length'],
     circle: ['radius', 'arc', 'thickness'],
     donut: ['radius', 'arc', 'thickness', 'donutRadius'],
     rectangle: ['width', 'height'],
@@ -69,6 +80,7 @@ export const SHAPE_PARAM_KEYS = {
     edge: ['radius', 'speed'],
     mesh_surface: [],
 };
+/** A new shape of `type`, built from the fields of `params` it has. */
 export function createShape(type, params) {
     switch (type) {
         case 'point':
@@ -95,6 +107,8 @@ export function createShape(type, params) {
                 arc: params.arc,
                 thickness: params.thickness,
                 angle: params.angle,
+                emitFrom: params.coneEmitFrom,
+                length: params.length,
                 mode: params.mode,
                 spread: params.spread,
             });
@@ -128,6 +142,7 @@ export function createShape(type, params) {
                 height: params.height,
                 column: params.column,
                 row: params.row,
+                sampling: params.sampling,
             });
         case 'box':
             return new BoxEmitter({

package/dist/core/systems.d.ts

@@ -1,7 +1,9 @@
 import type { TransformNode } from '@babylonjs/core/Meshes/transformNode.js';
 import { ParticleSystem } from 'babylon.quarks';
 import type { EffectBinding } from './binding.js';
+/** How {@link createChildSystem} builds a new system. */
 export interface ChildSystemOptions {
+    /** The new emitter's name. */
     name?: string;
     /** One-shot burst (sub-emitter target) instead of a looping stream. */
     oneShot?: boolean;

package/dist/core/systems.js

@@ -26,6 +26,8 @@ export function createChildSystem(parent, options = {}) {
         worldSpace: true,
     });
     child.emitter.name = options.name ?? (oneShot ? 'sub-emitter' : 'child-system');
+    // The editor previews over and over; the stop action is saved, not applied.
+    child.ignoreStopAction = true;
     if (oneShot) {
         child.onlyUsedByOther = true;
     }
@@ -43,7 +45,9 @@ export function unlinkSubEmitterReferences(systems, removed) {
         const behaviors = system.behaviors;
         for (let i = behaviors.length - 1; i >= 0; i--) {
             const behavior = behaviors[i];
-            if (behavior.type === 'EmitSubParticleSystem' && removedEmitters.has(behavior.subParticleSystem)) {
+            if (behavior.type === 'EmitSubParticleSystem' &&
+                behavior.subParticleSystem &&
+                removedEmitters.has(behavior.subParticleSystem)) {
                 behaviors.splice(i, 1);
             }
         }