babylon.quarks 0.27.0 → 0.28.0

package/src/effectDocumentJSON.ts

@@ -0,0 +1,261 @@
+import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import type {
+    MeshLighting,
+    MeshRim,
+    ParticleErosionOptions,
+    ParticleGradientMap,
+    ParticleUVDistortionOptions,
+    TextureUV,
+} from './batchSettings';
+import type {QuarksEffectJSON, QuarksNodeJSON, QuarksTextureJSON} from './QuarksSerializer';
+import type {ParticleMaterialSource} from './system/materialResolve';
+
+// The parts of an effect document `QuarksLoader` reads: what `serializeEffect` writes, and the
+// three.js object format three.quarks files use. Every field a file may leave out is optional; the
+// loader checks what it reads, so a field of the wrong kind warns or is skipped, never throws.
+
+/** Mesh data as typed arrays, the form a loaded geometry takes. */
+export interface GeometryArrays {
+    /** `x, y, z` per vertex. */
+    positions: Float32Array;
+    /** Three per triangle. */
+    indices: Uint32Array | Uint16Array;
+    /** First UV set, `u, v` per vertex. */
+    uvs?: Float32Array;
+    /** Second UV set, `u, v` per vertex. */
+    uvs2?: Float32Array;
+    /** `x, y, z` per vertex. */
+    normals?: Float32Array;
+}
+
+/** A three.js `BufferAttribute`, inline or as a view into an interleaved buffer. */
+export interface BufferAttributeJSON {
+    /** The values, when the attribute holds its own. */
+    array?: number[];
+    /** Components per vertex. */
+    itemSize?: number;
+    /** The typed array type, e.g. `'Float32Array'` or `'Uint16Array'`. */
+    type?: string;
+    /** Set when the attribute reads an interleaved buffer. */
+    isInterleavedBufferAttribute?: boolean;
+    /** The interleaved buffer's uuid. */
+    data?: string;
+    /** Where the attribute starts in each interleaved vertex. */
+    offset?: number;
+}
+
+/** A three.js interleaved buffer: a stride over one of the geometry's array buffers. */
+export interface InterleavedBufferJSON {
+    /** The array buffer's uuid. */
+    buffer: string;
+    /** Floats per vertex. */
+    stride: number;
+}
+
+/** The vertex attributes of a three.js `BufferGeometry` that quarks reads. */
+export interface BufferGeometryAttributesJSON {
+    /** Positions, `x, y, z` per vertex. */
+    position?: BufferAttributeJSON;
+    /** The first UV set. */
+    uv?: BufferAttributeJSON;
+    /** The second UV set, as three.js r151 on names it. */
+    uv1?: BufferAttributeJSON;
+    /** The second UV set, as three.js before r151 names it. */
+    uv2?: BufferAttributeJSON;
+    /** Normals, `x, y, z` per vertex. */
+    normal?: BufferAttributeJSON;
+}
+
+/** The index of a three.js `BufferGeometry`. */
+export interface BufferIndexJSON {
+    /** `'Uint16Array'` or `'Uint32Array'`; 32-bit when absent. */
+    type?: string;
+    /** Three per triangle. */
+    array: number[];
+}
+
+/** The `data` of a three.js `BufferGeometry`. */
+export interface BufferGeometryDataJSON {
+    /** The vertex attributes. */
+    attributes?: BufferGeometryAttributesJSON;
+    /** The triangle indices. */
+    index?: BufferIndexJSON;
+    /** Interleaved buffers by uuid. */
+    interleavedBuffers?: {[uuid: string]: InterleavedBufferJSON};
+    /** The bytes of the interleaved buffers by uuid, as 32-bit words. */
+    arrayBuffers?: {[uuid: string]: number[] | ArrayBuffer};
+}
+
+/** A three.js `BufferGeometry`. */
+export interface BufferGeometryJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Always `'BufferGeometry'`. */
+    type: 'BufferGeometry';
+    /** The vertex data. */
+    data?: BufferGeometryDataJSON;
+}
+
+/** A three.js `PlaneGeometry`: a quad in XY. */
+export interface PlaneGeometryJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Always `'PlaneGeometry'`. */
+    type: 'PlaneGeometry';
+    /** Default 1. */
+    width?: number;
+    /** Default 1. */
+    height?: number;
+}
+
+/** A three.js `SphereGeometry`. */
+export interface SphereGeometryJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Always `'SphereGeometry'`. */
+    type: 'SphereGeometry';
+    /** Default 0.5. */
+    radius?: number;
+    /** Default 16, at least 3. */
+    widthSegments?: number;
+    /** Default 8, at least 2. */
+    heightSegments?: number;
+    /** Default 0. */
+    phiStart?: number;
+    /** Default 2π. */
+    phiLength?: number;
+    /** Default 0. */
+    thetaStart?: number;
+    /** Default π. */
+    thetaLength?: number;
+}
+
+/**
+ * Quarks' own mesh data, inline (see `QuarksGeometryJSON`) or in its own file at `url`, which
+ * `QuarksLoader.resolveResources` inlines before parsing.
+ */
+export interface QuarksGeometryEntryJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Always `'QuarksGeometry'`. */
+    type: 'QuarksGeometry';
+    /** The file that holds the data, until it is inlined. */
+    url?: string;
+    /** `x, y, z` per vertex. */
+    positions?: number[];
+    /** Three per triangle. */
+    indices?: number[];
+    /** First UV set. */
+    uvs?: number[];
+    /** Second UV set. */
+    uvs2?: number[];
+    /** `x, y, z` per vertex. */
+    normals?: number[];
+}
+
+/** A geometry entry of an effect document. */
+export type EffectGeometryJSON = QuarksGeometryEntryJSON | BufferGeometryJSON | PlaneGeometryJSON | SphereGeometryJSON;
+
+/** An image entry of an effect document. */
+export interface EffectImageJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** Relative to the file's base url, absolute, or a `data:` url; absent for an image with no file. */
+    url?: string;
+}
+
+/**
+ * A texture slot of a {@link QuarksMaterialJSON}: a texture uuid in a file, the texture itself once
+ * a loader resolved it, or null for a texture that could not be made.
+ */
+export type MaterialTextureRef = string | BaseTexture | null;
+
+/** The gradient mapping of a {@link QuarksMaterialJSON}; see `ParticleSystem.gradientMap`. */
+export interface GradientMapJSON extends Omit<Partial<ParticleGradientMap>, 'ramp'> {
+    /** The ramp texture. */
+    ramp?: MaterialTextureRef;
+}
+
+/** The erosion of a {@link QuarksMaterialJSON}; see `ParticleSystem.erosion`. */
+export type ErosionJSON = Omit<ParticleErosionOptions, 'mask'> & {
+    /** The mask texture. */
+    mask?: MaterialTextureRef;
+};
+
+/** The UV distortion of a {@link QuarksMaterialJSON}; see `ParticleSystem.uvDistortion`. */
+export type UVDistortionJSON = Omit<ParticleUVDistortionOptions, 'map'> & {
+    /** The distortion texture. */
+    map?: MaterialTextureRef;
+};
+
+/**
+ * A material entry of an effect document: what a particle system's material writes (`type`
+ * `'QuarksMaterial'`), or a three.js material, whose `map` and `blending` the loader reads too.
+ */
+export interface QuarksMaterialJSON {
+    /** Unique within the file. */
+    uuid: string;
+    /** `'QuarksMaterial'`, or the three.js material type. */
+    type?: string;
+    /** Whether the particles blend. Default true. */
+    transparent?: boolean;
+    /** A Babylon alpha mode constant. */
+    alphaMode?: number;
+    /** A three.js blending code (1 normal, 2 additive, 3 subtractive, 4 multiply), read without `alphaMode`. */
+    blending?: number;
+    /** A three.js side code; 2 draws both faces. */
+    side?: number;
+    /** Default true. */
+    depthTest?: boolean;
+    /** Default false. */
+    depthWrite?: boolean;
+    /** Default 0. */
+    alphaTest?: number;
+    /** The particle texture. */
+    texture?: MaterialTextureRef;
+    /** A three.js material's texture, read when there is no `texture`. */
+    map?: string;
+    /** A 3×2 environment atlas for reflections. */
+    reflectionAtlas?: MaterialTextureRef;
+    /** How strong the reflection is. */
+    reflectionLevel?: number;
+    /** Mesh particle lighting; `'fixed'` when absent. */
+    lighting?: MeshLighting;
+    /** Mesh particle rim. */
+    rim?: Partial<MeshRim>;
+    /** The particle texture's UV transform. */
+    mapUV?: Partial<TextureUV>;
+    /** Gradient mapping. */
+    gradientMap?: GradientMapJSON;
+    /** Erosion. */
+    erosion?: ErosionJSON;
+    /** UV distortion. */
+    uvDistortion?: UVDistortionJSON;
+    /** While writing: the material the system read its settings from. Never written to a file. */
+    sourceMaterial?: ParticleMaterialSource;
+}
+
+/**
+ * A geometry as an effect's resources hold it: an entry of the document, or, once loaded, its
+ * typed arrays.
+ */
+export type GeometryEntry = EffectGeometryJSON | GeometryArrays;
+
+/**
+ * An effect document as `QuarksLoader` reads it: what `serializeEffect` writes
+ * (`QuarksEffectJSON`), or a three.quarks / three.js object file. Only `object` is required.
+ */
+export interface EffectDocumentJSON {
+    /** What wrote the file. */
+    metadata?: Partial<QuarksEffectJSON['metadata']>;
+    /** Meshes the nodes and particle systems use. */
+    geometries?: EffectGeometryJSON[];
+    /** Materials, referred to by uuid. */
+    materials?: QuarksMaterialJSON[];
+    /** Textures, referred to by uuid. */
+    textures?: QuarksTextureJSON[];
+    /** Image files the textures load. */
+    images?: EffectImageJSON[];
+    /** The effect's root node. */
+    object: QuarksNodeJSON;
+}

package/src/effectResources.ts

@@ -3,46 +3,46 @@ import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
 import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import type {Node} from '@babylonjs/core/node';
 
-/** What an effect root owns: the textures it holds a count on, and the materials made for it alone. */
+/** What an effect root holds a count on: the textures it draws with and the materials made for the effect. */
 interface EffectResources {
     textures: Set<BaseTexture>;
-    materials: Material[];
+    materials: Set<Material>;
 }
 
 const owned = new WeakMap<Node, EffectResources>();
-/** How many effect roots hold each texture. */
-const holders = new WeakMap<BaseTexture, number>();
+/** How many effect roots hold each texture and material. */
+const holders = new WeakMap<BaseTexture | Material, number>();
 
 /**
- * Records that `root` uses `textures` and owns `materials`. They are freed when the root is
- * disposed, however that happens: {@link disposeEffect}, `root.dispose()`, a parent's dispose or
- * the scene's.
+ * Records that `root` uses `textures` and the `materials` made for the effect. Each is freed once
+ * the last root holding it is disposed, however that happens: {@link disposeEffect},
+ * `root.dispose()`, a parent's dispose or the scene's.
  */
 export function retainEffectResources(
     root: TransformNode,
     textures: Iterable<BaseTexture>,
-    materials: Material[]
+    materials: Iterable<Material>
 ): void {
     if (owned.has(root)) {
         return;
     }
-    const resources: EffectResources = {textures: new Set(textures), materials};
-    for (const texture of resources.textures) {
-        holders.set(texture, (holders.get(texture) ?? 0) + 1);
+    const resources: EffectResources = {textures: new Set(textures), materials: new Set(materials)};
+    for (const resource of [...resources.textures, ...resources.materials]) {
+        holders.set(resource, (holders.get(resource) ?? 0) + 1);
     }
     owned.set(root, resources);
     root.onDisposeObservable.addOnce(() => releaseEffectResources(root));
 }
 
 /**
- * Gives `copy` a hold on the textures the effect `source` belongs to holds, as a copy of the
- * effect, or of a node in it, draws with them too.
+ * Gives `copy` a hold on the textures and materials the effect `source` belongs to holds, as a
+ * copy of the effect, or of a node in it, draws with them too.
  */
 export function shareEffectResources(source: TransformNode, copy: TransformNode): void {
     for (let node: Node | null = source; node !== null; node = node.parent) {
         const resources = owned.get(node);
         if (resources !== undefined) {
-            retainEffectResources(copy, resources.textures, []);
+            retainEffectResources(copy, resources.textures, resources.materials);
             return;
         }
     }
@@ -54,23 +54,20 @@ function releaseEffectResources(root: Node): void {
         return;
     }
     owned.delete(root);
-    for (const material of resources.materials) {
-        material.dispose();
-    }
-    for (const texture of resources.textures) {
-        const count = (holders.get(texture) ?? 1) - 1;
+    for (const resource of [...resources.materials, ...resources.textures]) {
+        const count = (holders.get(resource) ?? 1) - 1;
         if (count > 0) {
-            holders.set(texture, count);
+            holders.set(resource, count);
         } else {
-            holders.delete(texture);
-            texture.dispose();
+            holders.delete(resource);
+            resource.dispose();
         }
     }
 }
 
 /**
- * Disposes an effect root and its nodes and systems, the materials made for it, and each texture it
- * holds once no other effect root holds it. A root nothing was recorded for is only disposed.
+ * Disposes an effect root and its nodes and systems, and each material and texture it holds once no
+ * other effect root holds it. A root nothing was recorded for is only disposed.
  */
 export function disposeEffect(root: TransformNode): void {
     root.dispose();

package/src/envAtlas.ts

@@ -10,6 +10,8 @@ const atlasesByCube = new WeakMap<BaseTexture, Map<Scene, Texture>>();
 const pendingByCube = new WeakMap<BaseTexture, Map<Scene, Promise<Texture | null>>>();
 /** Atlases this module built, which it disposes; an atlas given to {@link cacheEnvAtlas} stays the caller's. */
 const builtAtlases = new WeakSet<Texture>();
+/** The faces each cube's atlas failed to build from: not tried, or warned about, again. */
+const failedFaces = new WeakMap<BaseTexture, string>();
 /** Atlases whose dispose this module already listens to. */
 const watchedAtlases = new WeakSet<Texture>();
 /** Cubes whose dispose this module already listens to. */
@@ -66,6 +68,7 @@ export function cacheEnvAtlas(cube: BaseTexture, atlas: Texture): void {
  * @param scene - Only the atlas for this scene. Defaults to every scene.
  */
 export function disposeEnvAtlas(cube: BaseTexture, scene?: Scene): void {
+    failedFaces.delete(cube);
     const atlases = atlasesByCube.get(cube);
     if (!atlases) {
         return;
@@ -146,7 +149,9 @@ export const envAtlasBuilder = {
 /**
  * Ensures a 3×2 env atlas exists for a CubeTexture in `scene`. Returns a cached atlas
  * synchronously when available; otherwise starts (or joins) an async build and invokes onReady
- * when the atlas is usable. A cube disposed before its build finishes gets no atlas.
+ * when the atlas is usable. A cube disposed before its build finishes gets no atlas. A build that
+ * fails warns once and is not tried again until the cube's faces change or
+ * {@link disposeEnvAtlas} is called for it; {@link cacheEnvAtlas} still supplies an atlas.
  */
 export function ensureEnvAtlasFromCube(
     cube: BaseTexture,
@@ -178,7 +183,7 @@ export function ensureEnvAtlasFromCube(
         }
 
         const urls = cubeFaceUrls(cube);
-        if (!urls) {
+        if (!urls || failedFaces.get(cube) === urls.join('\n')) {
             return;
         }
 
@@ -206,6 +211,7 @@ export function ensureEnvAtlasFromCube(
             })
             .catch((err) => {
                 settle();
+                failedFaces.set(cube, urls.join('\n'));
                 console.warn('[babylon.quarks] Failed to build env atlas from cubemap faces', err);
                 return null;
             });

package/src/geometryUtil.ts

@@ -1,4 +1,4 @@
-/** Sequential 0..N-1 indices for non-indexed triangle-list BufferGeometry (Three.js drawArrays). */
+/** `indices` when there are some, else `0..N-1`: each three vertices of `positions` one triangle. */
 export function ensureTriangleIndices(
     positions: Float32Array,
     indices?: Uint32Array | Uint16Array

package/src/index.ts

@@ -4,8 +4,29 @@ import {MeshSurfaceEmitterPlugin} from './MeshSurfaceEmitter';
 export * from 'quarks.core';
 export {BatchedRenderer} from './BatchedRenderer';
 export type {AdaptivePerformanceOptions, AdaptivePerformanceState, VFXBatchSettings} from './BatchedRenderer';
+export type {
+    BufferAttributeJSON,
+    BufferGeometryAttributesJSON,
+    BufferGeometryDataJSON,
+    BufferGeometryJSON,
+    BufferIndexJSON,
+    EffectDocumentJSON,
+    EffectGeometryJSON,
+    EffectImageJSON,
+    ErosionJSON,
+    GeometryArrays,
+    GeometryEntry,
+    GradientMapJSON,
+    InterleavedBufferJSON,
+    MaterialTextureRef,
+    PlaneGeometryJSON,
+    QuarksGeometryEntryJSON,
+    QuarksMaterialJSON,
+    SphereGeometryJSON,
+    UVDistortionJSON,
+} from './effectDocumentJSON';
 export {EffectPool} from './EffectPool';
-export type {EffectPoolOptions} from './EffectPool';
+export type {EffectPlacement, EffectPoolOptions} from './EffectPool';
 export {
     cacheEnvAtlas,
     createEnvAtlasFromFaceUrls,
@@ -17,6 +38,7 @@ export {
 export {MeshSurfaceEmitter, MeshSurfaceEmitterPlugin} from './MeshSurfaceEmitter';
 export {quarksNodeId} from './nodeId';
 export {ParticleEmitter} from './ParticleEmitter';
+export type {ParticleEmitterJSON} from './ParticleEmitter';
 export {ParticleSystem} from './ParticleSystem';
 export type {
     BabylonMetaData,
@@ -34,11 +56,12 @@ export type {
     QuarksJSONLoadEntry,
     QuarksLoaderOptions,
     QuarksLoadOptions,
+    QuarksResolveOptions,
     QuarksResourceKind,
     QuarksResourceResolver,
 } from './QuarksLoader';
 export {QuarksPrefab} from './QuarksPrefab';
-export type {AnimationData, QuarksTimelineClip} from './QuarksPrefab';
+export type {AnimationData, AnimationJSON, QuarksPrefabJSON, QuarksTimelineClip} from './QuarksPrefab';
 export {QUARKS_FORMAT_VERSION, serializeEffect} from './QuarksSerializer';
 export type {
     QuarksEffectJSON,
@@ -49,13 +72,23 @@ export type {
     SerializeEffectOptions,
 } from './QuarksSerializer';
 export {QuarksUtil} from './QuarksUtil';
-export {shaderProgram} from './shaderProgram';
-export type {ShaderContext, ShaderDepth, ShaderProgram, ShaderSettings} from './shaderProgram';
+export {blendCategory, shaderProgram} from './shaderProgram';
+export type {
+    BlendCategory,
+    BlendOutput,
+    FogTarget,
+    ShaderContext,
+    ShaderDepth,
+    ShaderProgram,
+    ShaderSettings,
+} from './shaderProgram';
 export type {ShaderSources} from './shaders/shaderLanguageSupport';
 export {shaderVariants} from './shaderVariants';
 export type {ShaderVariant} from './shaderVariants';
 export {decodeSoftDepth, softDepthParams} from './softDepth';
 export type {DepthTextureOptions, SoftDepthEncoding} from './softDepth';
+export type {ParticleMaterialSource} from './system/materialResolve';
+export type {RendererEmitterSettingsJSON, TrailSettingsJSON} from './system/types';
 export {textureSourceUrl} from './textureSource';
 export {
     MAX_TRAIL_TESSELLATION,
@@ -65,6 +98,7 @@ export {
     trailTessellation,
     trailTextureMode,
     trailTextureScale,
+    type TrailOptions,
 } from './trailSettings';
 export {
     defaultMeshLighting,
@@ -99,6 +133,7 @@ export type {
     ParticleGradientMap,
     ParticleUVDistortion,
     ParticleUVDistortionOptions,
+    RenderFace,
     SortMode,
     StoredBatchSettings,
     TextureUV,

package/src/nodeId.ts

@@ -1,5 +1,8 @@
 import {RandomGUID} from '@babylonjs/core/Misc/guid';
 
+/** The id each node is known by in effect files, set when it is loaded or first asked for. */
+const nodeIds = new WeakMap<object, string>();
+
 /**
  * The id an effect file knows a node by: the uuid it was loaded under, or, for a node made in code,
  * a GUID given to it the first time it is asked for and kept from then on. Every link written into
@@ -8,6 +11,26 @@ import {RandomGUID} from '@babylonjs/core/Misc/guid';
  * and a node made in code never takes the id of one loaded from a file.
  */
 export function quarksNodeId(node: object): string {
-    const ided = node as {_quarksUUID?: string};
-    return (ided._quarksUUID ??= RandomGUID());
+    let id = nodeIds.get(node);
+    if (id === undefined) {
+        id = RandomGUID();
+        nodeIds.set(node, id);
+    }
+    return id;
+}
+
+/**
+ * The uuid `node` was loaded under or was given, or undefined for a node no file or save has named.
+ * @internal
+ */
+export function fileNodeId(node: object): string | undefined {
+    return nodeIds.get(node);
+}
+
+/**
+ * Names `node` with `id`, the uuid a file gave it.
+ * @internal
+ */
+export function setQuarksNodeId(node: object, id: string): void {
+    nodeIds.set(node, id);
 }