babylon.quarks-editor 0.26.0 → 0.28.0

package/src/core/assets.ts

@@ -7,7 +7,9 @@ import {QuarksLoader} from 'babylon.quarks';
  * fresh, independent copy (see `instantiateSceneEntry`).
  */
 export interface EffectAsset {
+    /** The asset's id in this session; scene entries made from it keep it. */
     id: number;
+    /** The asset's display name, its file name without `.json`. */
     name: string;
     /** Relative path inside the imported folder (preserves subfolders). */
     path: string;
@@ -17,10 +19,15 @@ export interface EffectAsset {
     missingFiles: string[];
 }
 
+/** How far an asset import got. */
 export interface AssetLoadProgress {
+    /** JSON files read so far. */
     done: number;
+    /** JSON files in the import. */
     total: number;
+    /** Effects found so far. */
     loaded: number;
+    /** Files that could not be read. */
     failed: number;
 }
 
@@ -75,6 +82,13 @@ function readAsDataUrl(file: File): Promise<string> {
     });
 }
 
+/** An object with fields of unknown types, as an imported file's JSON may hold anywhere. */
+type JSONRecord = {[key: string]: unknown};
+
+function isRecord(value: unknown): value is JSONRecord {
+    return value !== null && typeof value === 'object';
+}
+
 /** True for a Quarks effect envelope with at least one particle emitter. */
 export function isEffectJson(json: unknown): boolean {
     const object = (json as {object?: unknown} | null)?.object;
@@ -166,7 +180,7 @@ function createFileResolver(effectPath: string, index: ImportedFileIndex, missin
  * {@link QuarksLoader.resolveLinkedResources}, 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: any, effectPath: string, index: ImportedFileIndex): Promise<string[]> {
+async function inlineExternalFiles(json: unknown, effectPath: string, index: ImportedFileIndex): Promise<string[]> {
     const missing: string[] = [];
     // baseUrl is the effect file path so resolveRelativePath can walk from its folder; the
     // File resolver ignores HTTP join and looks up files by path/name instead.
@@ -263,22 +277,23 @@ export function assetIconUrl(asset: EffectAsset): string | null {
     if (cached !== undefined) {
         return cached;
     }
-    const json = asset.json as any;
-    const findMaterial = (node: any): string | undefined => {
-        if (!node || typeof node !== 'object') return undefined;
-        if (node.type === 'ParticleEmitter' && node.ps?.material) return node.ps.material;
+    const json = isRecord(asset.json) ? asset.json : {};
+    const findMaterial = (node: unknown): unknown => {
+        if (!isRecord(node)) return undefined;
+        if (node.type === 'ParticleEmitter' && isRecord(node.ps) && 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: unknown, uuid: unknown) =>
-        (Array.isArray(list) ? list : []).find((item: any) => item?.uuid === uuid) as any;
+    const byUuid = (list: unknown, uuid: unknown): JSONRecord | undefined =>
+        (Array.isArray(list) ? list : []).find((item: unknown) => isRecord(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 material = byUuid(json.materials, findMaterial(json.object));
+    const texture = byUuid(json.textures, material?.map ?? material?.texture);
+    const firstImage: unknown = Array.isArray(json.images) ? json.images[0] : undefined;
+    const image = byUuid(json.images, texture?.image) ?? (isRecord(firstImage) ? firstImage : undefined);
     const url = typeof image?.url === 'string' && image.url ? image.url : null;
     iconCache.set(asset, url);
     return url;

package/src/core/binding.ts

@@ -1,8 +1,9 @@
-import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode.js';
 import type {ParticleSystem} from 'babylon.quarks';
-import type {EffectTreeNode} from './effectTree';
-import {buildEffectTree, serializeEffectTree} from './effectTree';
+import type {EffectTreeNode} from './effectTree.js';
+import {buildEffectTree, serializeEffectTree} from './effectTree.js';
 
+/** Called after every change made through an {@link EffectBinding}. */
 export type EditorListener = () => void;
 
 /**
@@ -32,6 +33,7 @@ export class EffectBinding {
         return buildEffectTree(this.root);
     }
 
+    /** Calls `listener` after every change; returns the call that stops it. */
     subscribe(listener: EditorListener): () => void {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
@@ -42,17 +44,23 @@ export class EffectBinding {
         return this.revision;
     }
 
+    /**
+     * Changes the main system through `mutate`: takes an undo snapshot first, then notifies
+     * subscribers. Every inspector edit goes through here.
+     */
     apply(mutate: (system: ParticleSystem) => void): void {
         this.onBeforeChange?.();
         mutate(this.system);
         this.notify();
     }
 
+    /** Adds a system to the effect's sub systems. */
     addSubSystem(sub: ParticleSystem): void {
         this.subSystems.push(sub);
         this.notify();
     }
 
+    /** Removes a system from the effect's sub systems; a system it does not have is ignored. */
     removeSubSystem(sub: ParticleSystem): void {
         const index = this.subSystems.indexOf(sub);
         if (index >= 0) {
@@ -92,6 +100,7 @@ export class EffectBinding {
         }
     }
 
+    /** Restarts every system of the effect from time 0. */
     restart(): void {
         // onlyUsedByOther systems skip self-emission in update(); play() only unpauses sim.
         for (const system of [this.system, ...this.subSystems]) {

package/src/core/collision.ts

@@ -8,8 +8,12 @@ import {Vector3, getPhysicsResolver, setPhysicsResolver} from 'babylon.quarks';
  * which is exactly what ApplyCollision.update reflects the velocity against.
  */
 export class GroundPlaneResolver {
+    /** @param y - Height of the ground plane. */
     constructor(public y = 0) {}
 
+    /**
+     * True when `position` is at or below the plane, with the plane's normal written to `normal`.
+     */
     resolve(position: Vector3, normal: Vector3): boolean {
         if (position.y <= this.y) {
             normal.set(0, 1, 0);

package/src/core/colors.ts

@@ -3,18 +3,25 @@ import {ColorOverLife, Gradient, Vector3, Vector4} from 'babylon.quarks';
 
 /** One RGBA stop of the editable gradient (all channels 0..1, pos 0..1). */
 export interface GradientStop {
+    /** Where the stop sits over the particle's life, 0..1. */
     pos: number;
+    /** Red, 0..1. */
     r: number;
+    /** Green, 0..1. */
     g: number;
+    /** Blue, 0..1. */
     b: number;
+    /** Alpha, 0..1. */
     a: number;
 }
 
+/** The gradient a new Color over Lifetime starts with: warm yellow fading out through red. */
 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},
 ];
 
+/** A quarks gradient through `stops`, sorted by position; colour and alpha share the stops. */
 export function buildGradient(stops: GradientStop[]): Gradient {
     const sorted = [...stops].sort((a, b) => a.pos - b.pos);
     return new Gradient(
@@ -23,26 +30,38 @@ export function buildGradient(stops: GradientStop[]): Gradient {
     );
 }
 
+/** A Color over Lifetime behavior through `stops`. */
 export function buildColorOverLife(stops: GradientStop[]): ColorOverLife {
     return new ColorOverLife(buildGradient(stops));
 }
 
+/** An RGBA colour as a quarks `Vector4`. */
 export function rgbaToVector4(stop: {r: number; g: number; b: number; a: number}): Vector4 {
     return new Vector4(stop.r, stop.g, stop.b, stop.a);
 }
 
+/** A stop's colour as CSS `rgba()`. */
 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)})`;
 }
 
+/** The stops as a left-to-right CSS `linear-gradient`, for a gradient preview. */
 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} {
+/** A `#rrggbb` colour as channels 0..1. */
+export function hexToRgb(hex: string): {
+    /** Red, 0..1. */
+    r: number;
+    /** Green, 0..1. */
+    g: number;
+    /** Blue, 0..1. */
+    b: number;
+} {
     const value = hex.replace('#', '');
     return {
         r: parseInt(value.slice(0, 2), 16) / 255,
@@ -51,6 +70,7 @@ export function hexToRgb(hex: string): {r: number; g: number; b: number} {
     };
 }
 
+/** Channels 0..1, clamped, as a `#rrggbb` colour. */
 export function rgbToHex(r: number, g: number, b: number): string {
     const c = (v: number) =>
         Math.round(Math.min(1, Math.max(0, v)) * 255)

package/src/core/defaultEffect.ts

@@ -1,5 +1,6 @@
-import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
-import type {Scene} from '@babylonjs/core/scene';
+import type {Texture} from '@babylonjs/core/Materials/Textures/texture.js';
+import {TransformNode} from '@babylonjs/core/Meshes/transformNode.js';
+import type {Scene} from '@babylonjs/core/scene.js';
 import {
     ColorOverLife,
     ConeEmitter,
@@ -10,18 +11,18 @@ import {
     RenderMode,
     Vector4,
 } from 'babylon.quarks';
-import {DEFAULT_GRADIENT_STOPS, buildGradient} from './colors';
-import {uniqueEntryName, type SceneEntry} from './sceneEntries';
+import {DEFAULT_GRADIENT_STOPS, buildGradient} from './colors.js';
+import {uniqueEntryName, type SceneEntry} from './sceneEntries.js';
 
 export interface CreateSceneDefaultOptions {
-    resolveTexture?: (url: string, scene: Scene) => unknown;
+    resolveTexture?: (url: string, scene: Scene) => Texture | null | undefined;
     textureUrl?: string;
 }
 
 /** Creates a simple cone burst preset for new editor effects. */
 export function createDefaultEffect(
     scene: Scene,
-    resolveTexture?: (url: string, scene: Scene) => unknown,
+    resolveTexture?: (url: string, scene: Scene) => Texture | null | undefined,
     textureUrl?: string
 ): ParticleSystem {
     const system = new ParticleSystem({
@@ -35,7 +36,7 @@ export function createDefaultEffect(
         emissionOverTime: new ConstantValue(80),
         shape: new ConeEmitter({radius: 0.3, angle: 0.25}),
         renderMode: RenderMode.BillBoard,
-        texture: (textureUrl && resolveTexture ? resolveTexture(textureUrl, scene) : undefined) as never,
+        texture: textureUrl && resolveTexture ? resolveTexture(textureUrl, scene) : undefined,
         transparent: true,
         blendMode: 1,
     });

package/src/core/editorScene.ts

@@ -1,4 +1,4 @@
-import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode.js';
 
 /** Marks meshes/nodes created only for editor interaction or overlays (not part of the effect). */
 export const EDITOR_SCENE_NODE_METADATA = {quarksEditorSceneNode: true as const};