@needle-tools/engine 4.11.3 → 4.11.4-next.a568de7

package/src/engine/extensions/NEEDLE_components.ts

@@ -1,13 +1,14 @@
 import { Object3D } from "three";
 import { GLTFExporter } from 'three/examples/jsm/exporters/GLTFExporter.js';
 import { type GLTF, type GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { isDevEnvironment } from "../debug/debug.js";
 
 import { builtinComponentKeyName } from "../engine_constants.js";
 import { debugExtension } from "../engine_default_parameters.js";
 import { getLoader } from "../engine_gltf.js";
 import { type NodeToObjectMap, type ObjectToNodeMap, SerializationContext } from "../engine_serialization_core.js";
 import { apply } from "../js-extensions/index.js";
-import { maskGltfAssociation,resolveReferences } from "./extension_utils.js";
+import { maskGltfAssociation, resolveReferences } from "./extension_utils.js";
 
 export const debug = debugExtension
 const componentsArrayExportKey = "$___Export_Components";
@@ -15,7 +16,7 @@ const componentsArrayExportKey = "$___Export_Components";
 export const EXTENSION_NAME = "NEEDLE_components";
 
 class ExtensionData {
-    [builtinComponentKeyName]?: Array<object | null>
+    [builtinComponentKeyName]?: Array<Record<string, any> | null>
 }
 
 class ExportData {
@@ -35,14 +36,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
     get name(): string {
         return EXTENSION_NAME;
     }
-
-    // import
-    parser?: GLTFParser;
-    nodeToObjectMap: NodeToObjectMap = {};
-    /** The loaded gltf */
-    gltf: GLTF | null = null;
-
-    // export
+    // #region export
     exportContext!: { [nodeIndex: number]: ExportData };
     objectToNodeMap: ObjectToNodeMap = {};
     context!: SerializationContext;
@@ -112,7 +106,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
 
     writeNode(node: Object3D, nodeDef) {
         const nodeIndex = this.writer.json.nodes.length;
-        if (debug) 
+        if (debug)
             console.log(node.name, nodeIndex, node.uuid);
         const context = new ExportData(node, nodeIndex, nodeDef);
         this.exportContext[nodeIndex] = context;
@@ -158,8 +152,13 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
 
 
     // -------------------------------------
-    // LOADING 
-    // called by GLTFLoader
+    // #region import 
+    parser?: GLTFParser;
+    nodeToObjectMap: NodeToObjectMap = {};
+    /** The loaded gltf */
+    gltf: GLTF | null = null;
+
+
     beforeRoot() {
         if (debug)
             console.log("BEGIN LOAD");
@@ -167,7 +166,6 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
         return null;
     }
 
-    // called by GLTFLoader
     async afterRoot(result: GLTF): Promise<void> {
         this.gltf = result;
 
@@ -175,8 +173,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
         const ext = parser?.extensions;
         if (!ext) return;
         const hasExtension = ext[this.name];
-        if (debug)
-            console.log("After root", result, this.parser, ext);
+        if (debug) console.log("After root", result, this.parser, ext);
 
         const loadComponents: Array<Promise<void>> = [];
         if (hasExtension === true) {
@@ -204,7 +201,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
 
                     apply(obj);
 
-                    loadComponents.push(this.createComponents(obj, data));
+                    loadComponents.push(this.createComponents(result, node, obj, data));
                 }
             }
         }
@@ -220,7 +217,7 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
         }
     }
 
-    private async createComponents(obj: Object3D, data: ExtensionData) {
+    private async createComponents(result: GLTF, node: Node, obj: Object3D, data: ExtensionData) {
         if (!data) return;
         const componentData = data[builtinComponentKeyName];
         if (componentData) {
@@ -228,20 +225,42 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
             if (debug)
                 console.log(obj.name, componentData);
             for (const i in componentData) {
-                const serializedData = componentData[i];
-                if (debug)
-                    console.log("Serialized data", JSON.parse(JSON.stringify(serializedData)));
+                const data = componentData[i];
+
+                if (debug) console.log("Serialized data", JSON.parse(JSON.stringify(data)));
+
+                // Fix for https://linear.app/needle/issue/NE-6779/blender-export-has-missing-sharedmaterials
+                if (data?.name === "MeshRenderer" || data?.name === "SkinnedMeshRenderer") {
+                    if (!data.sharedMaterials) {
+                        let success = false;
+                        if ("mesh" in node) {
+                            const meshIndex = node.mesh;
+                            if (typeof meshIndex === "number" && result.parser) {
+                                const meshDef = result.parser.json.meshes?.[meshIndex];
+                                if (meshDef?.primitives) {
+                                    data.sharedMaterials =  meshDef.primitives.map(prim => {
+                                        return "/materials/" + (prim.material ?? 0);
+                                    });
+                                    success = true;
+                                }
+                            }
+                        }
+                        if(!success && (debug || isDevEnvironment())) {
+                            console.warn(`[NEEDLE_components] Component '${data.name}' on object '${obj.name}' is not added to a mesh or failed to retrieve materials from glTF.`);
+                        }
+                    }
+                }
 
-                if (serializedData && this.parser) {
+                if (data && this.parser) {
                     tasks.push(
-                        resolveReferences(this.parser, serializedData)
-                            .catch(e => console.error(`Error while resolving references (see console for details)\n`, e, obj, serializedData))
+                        resolveReferences(this.parser, data)
+                            .catch(e => console.error(`Error while resolving references (see console for details)\n`, e, obj, data))
                     );
                 }
 
                 obj.userData = obj.userData || {};
                 obj.userData[builtinComponentKeyName] = obj.userData[builtinComponentKeyName] || [];
-                obj.userData[builtinComponentKeyName].push(serializedData);
+                obj.userData[builtinComponentKeyName].push(data);
             }
             await Promise.all(tasks).catch((e) => {
                 console.error("Error while loading components", e);
@@ -266,4 +285,6 @@ export class NEEDLE_components implements GLTFLoaderPlugin {
     //     // console.log(components);
     //     return null;
     // }
-}
+}
+
+

package/src/engine/webcomponents/buttons.ts

@@ -1,6 +1,6 @@
 import { isDevEnvironment, showBalloonWarning } from "../debug/debug.js";
 import { IContext } from "../engine_types.js";
-import { generateQRCode, isMobileDevice } from "../engine_utils.js";
+import { generateQRCode } from "../engine_utils_qrcode.js";
 import { onXRSessionEnd, onXRSessionStart } from "../xr/events.js";
 import { getIconElement } from "./icons.js";
 

package/src/engine-components/Animation.ts

@@ -58,7 +58,7 @@ declare type AnimationIdentifier = AnimationClip | number | string | undefined;
 class Vec2 { x!: number; y!: number }
 
 /**
- * Animation component to play animations on a GameObject
+ * Animation component to play animations on a GameObject.
  * @category Animation and Sequencing
  * @group Components
  */

package/src/engine-components/AnimationCurve.ts

@@ -27,7 +27,10 @@ export class Keyframe {
 }
 
 /**
- * AnimationCurve is a representation of a curve that can be used to animate values over time.  
+ * AnimationCurve is a representation of a curve that can be used to animate values over time. 
+ * 
+ * @category Animation
+ * @group Utilities 
  */
 export class AnimationCurve {
 

package/src/engine-components/Animator.ts

@@ -39,8 +39,9 @@ export declare class PlayOptions {
 
 /** 
  * The Animator component plays and manages animations on a GameObject. 
- * It works with an AnimatorController to handle state transitions and animation blending.
- * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.
+ * It works with an {@link AnimatorController} to handle state transitions and animation blending.
+ * A new AnimatorController can be created from code via `AnimatorController.createFromClips`.  
+ * 
  * @category Animation and Sequencing
  * @group Components
 */

package/src/engine-components/AnimatorController.ts

@@ -51,6 +51,9 @@ declare type CreateAnimatorControllerOptions = {
  * 
  * Use the static method {@link AnimatorController.createFromClips} to create
  * an animator controller from a set of animation clips.
+ * 
+ * @category Animation and Sequencing
+ * @group Utilities
  */
 export class AnimatorController {
 

package/src/engine-components/LookAtConstraint.ts

@@ -2,9 +2,14 @@ import { Object3D, Vector3 } from "three";
 
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
+import type { OrbitControls } from "./OrbitControls.js";
 
 /**
- * A LookAtConstraint is used by OrbitControls to make the camera look at a target.
+ * A LookAtConstraint is used by OrbitControls to make the camera look at a target.  
+ * This component is used by {@link OrbitControls} internally.
+ * 
+ * @category Camera Controls
+ * @group Components
  */
 export class LookAtConstraint extends Behaviour {
 

package/src/engine-components/NeedleMenu.ts

@@ -9,6 +9,7 @@ import { Behaviour } from './Component.js';
  * 
  * Controls display options, button visibility, and menu positioning.
  * From code, you can access the menu via {@link Context.menu}. 
+ * 
  * @category User Interface
  * @group Components
  **/

package/src/engine-components/NestedGltf.ts

@@ -10,6 +10,9 @@ const debug = getParam("debugnestedgltf");
 
 /** The nested gltf is a component that is used to load a gltf file when the component becomes active (start)  
  * It will load the gltf file and instantiate it as a child of the parent of the GameObject that has this component
+ * 
+ * @category Asset Management
+ * @group Components
  */
 export class NestedGltf extends Behaviour {
 

package/src/engine-components/ReflectionProbe.ts

@@ -15,6 +15,10 @@ const $reflectionProbeKey = Symbol("reflectionProbeKey");
 const $originalMaterial = Symbol("original material");
 
 /**
+ * A ReflectionProbe provides reflection data to materials within its defined area.
+ * 
+ * - Sample: http://samples.needle.tools/reflection-probes
+ * 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/Renderer.ts

@@ -69,7 +69,7 @@ class SharedMaterialArray implements ISharedMaterials {
     set changed(value: boolean) {
         if (value === true) {
             if (debugRenderer)
-                console.warn("SharedMaterials have changed: " + this._renderer.name, this);
+                console.warn("SharedMaterials have changed: " + this._renderer.name);
         }
         this._changed = value;
     }
@@ -358,11 +358,15 @@ export class Renderer extends Behaviour implements IRenderer {
     //@ts-ignore
     get sharedMaterials(): SharedMaterialArray {
 
-        // @ts-ignore (original materials will be set during deserialization)
-        if (this._originalMaterials === undefined) return null;
-
-        // @ts-ignore during deserialization code might access this property *before* the setter and then create an empty array
-        if (this.__isDeserializing === true) return null;
+        if (this._originalMaterials === undefined) {
+            if (!this.__didAwake) {
+                // @ts-ignore (original materials will be set during deserialization)
+                return null;
+            }
+            else {
+                this._originalMaterials = [];
+            }
+        }
 
         if (!this._sharedMaterials || !this._sharedMaterials.is(this)) {
             if (!this._originalMaterials) this._originalMaterials = [];
@@ -454,6 +458,7 @@ export class Renderer extends Behaviour implements IRenderer {
             this.context.addBeforeRenderListener(this.gameObject, this.onBeforeRenderThree);
         }
 
+        this._lightmaps = undefined;
         this.applyLightmapping();
 
         if (showWireframe) {
@@ -468,8 +473,8 @@ export class Renderer extends Behaviour implements IRenderer {
     }
 
     private applyLightmapping() {
-        if (this.lightmapIndex >= 0) {
-            const type = this.gameObject.type;
+        if (this.lightmapIndex >= 0 && !this._lightmaps) {
+            // const type = this.gameObject.type;
 
             // use the override lightmap if its not undefined
             const tex = this._lightmapTextureOverride !== undefined
@@ -477,45 +482,12 @@ export class Renderer extends Behaviour implements IRenderer {
                 : this.context.lightmaps.tryGetLightmap(this.sourceId, this.lightmapIndex);
             if (tex) {
                 if (!this._lightmaps) this._lightmaps = [];
-
-
                 const rm = new RendererLightmap(this);
                 rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
                 this._lightmaps.push(rm);
-
-                // if (type === "Mesh") {
-                //     const mat = this.gameObject["material"];
-                //     if (!mat?.isMeshBasicMaterial) {
-                //         if (this._lightmaps.length <= 0) {
-                //         }
-                //         const rm = this._lightmaps[0];
-                //         rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
-                //     }
-                //     else {
-                //         if (mat)
-                //             console.warn("Lightmapping is not supported on MeshBasicMaterial", mat.name)
-                //     }
-                // }
-                // // for multi materials we need to loop through children 
-                // // and then we add a lightmap renderer component to each of them
-                // else if (this.isMultiMaterialObject(this.gameObject) && this.sharedMaterials.length > 0) {
-                //     for (let i = 0; i < this.gameObject.children.length; i++) {
-                //         const child = this.gameObject.children[i];
-                //         if (!child["material"]?.isMeshBasicMaterial) {
-                //             let rm: RendererLightmap | undefined = undefined;
-                //             if (i >= this._lightmaps.length) {
-                //                 rm = new RendererLightmap(child as Mesh, this.context);
-                //                 this._lightmaps.push(rm);
-                //             }
-                //             else
-                //                 rm = this._lightmaps[i];
-                //             rm.init(this.lightmapIndex, this.lightmapScaleOffset, tex);
-                //         }
-                //     }
-                // }
             }
             else {
-                if (debugRenderer) console.warn("Lightmap not found", this.sourceId, this.lightmapIndex);
+                if (debugRenderer) console.warn(`[Renderer] No lightmaps found ${this.name} (${this.sourceId}, ${this.lightmapIndex})`);
             }
         }
 

package/src/engine-components/RendererLightmap.ts

@@ -9,9 +9,17 @@ const debug = getParam("debuglightmaps");
 
 declare type MaterialWithLightmap = Material & { lightMap?: Texture | null };
 
-// this component is automatically added by the Renderer if the object has lightmap uvs AND we have a lightmap
-// for multimaterial objects GLTF exports a "Group" with the renderer component
-// and every child mesh is a material from unity
+let cloningCounter = 0;
+
+const $lightmapVersion = Symbol("lightmap-material-version");
+
+
+/**
+ * This component is automatically added by the {@link Renderer} component if the object has lightmap uvs AND we have a lightmap.
+ * 
+ * @category Rendering
+ * @group Components
+ */
 export class RendererLightmap {
 
     get lightmap(): Texture | null {
@@ -33,6 +41,8 @@ export class RendererLightmap {
     private lightmapScaleOffset: Vector4 = new Vector4(1, 1, 0, 0);
 
     private readonly renderer: Renderer;
+    private readonly clonedMaterials = new Array<Material>();
+
     private get context(): Context { return this.renderer.context; }
     private get gameObject() { return this.renderer.gameObject; }
     private lightmapTexture: Texture | null = null;
@@ -85,8 +95,7 @@ export class RendererLightmap {
 
             const mat = this.renderer.sharedMaterials[i];
             if (!mat) continue;
-
-            const newMat = this.ensureLightmapMaterial(mat);
+            const newMat = this.ensureLightmapMaterial(mat, i);
             if (mat !== newMat) {
                 this.renderer.sharedMaterials[i] = newMat;
             }
@@ -114,23 +123,28 @@ export class RendererLightmap {
         }
     }
 
-    private ensureLightmapMaterial(material: Material) {
+    private ensureLightmapMaterial(material: Material, index: number) {
         if (!material.userData) material.userData = {};
         // if (material instanceof MeshPhysicalMaterial) {
         //     return material;
         // }
         // check if the material version has changed and only then clone the material
-        if (material["NEEDLE:lightmap-material-version"] != material.version) {
-            if (material["NEEDLE:lightmap-material-version"] == undefined) {
-                if (debug) console.warn("Cloning material for lightmap " + material.name);
-                const mat: Material = material.clone();
-                if (!mat.name?.includes("(lightmap)")) mat.name = material.name + " (lightmap)";
-                material = mat;
-                material.onBeforeCompile = this.onBeforeCompile;
-            }
-            else {
-                // we need to clone the material
+        if (this.clonedMaterials[index] !== material) {
+            if (debug) {
+                ++cloningCounter;
+                if (cloningCounter++ < 1000) {
+                    console.warn(`Cloning material for lightmap ${this.renderer.name}: '${material.name}'`);
+                }
+                else if (cloningCounter === 1000) {
+                    console.warn(`Further material cloning for lightmaps suppressed to avoid flooding the console.`);
+                }
             }
+            const mat: Material = material.clone();
+            if (!mat.name?.includes("(lightmap)")) mat.name = material.name + " (lightmap)";
+            material = mat;
+            material.onBeforeCompile = this.onBeforeCompile;
+            this.clonedMaterials[index] = material;
+
         }
         return material;
     }
@@ -140,22 +154,22 @@ export class RendererLightmap {
         if (material instanceof MeshPhysicalMaterial && material.transmission > 0) {
             return;
         }
-        const hasChanged = material.lightMap !== this.lightmapTexture || material["NEEDLE:lightmap-material-version"] !== material.version;
+        const hasChanged = material.lightMap !== this.lightmapTexture || material[$lightmapVersion] !== material.version;
         if (!hasChanged) {
             return;
         }
 
-        if (debug) console.log("Assigning lightmap", material.name, material.version, material);
+        if (debug) console.log(`Assigning lightmap texture ${this.renderer.name}: '${material.name}' (${material.version} ${material[$lightmapVersion]})`);
 
         // assign the lightmap
         material.lightMap = this.lightmapTexture;
         material.needsUpdate = true;
         // store the version of the material
-        material["NEEDLE:lightmap-material-version"] = material.version;
+        material[$lightmapVersion] = material.version;
     }
 
     private onBeforeCompile = (shader: WebGLProgramParametersWithUniforms, _) => {
-        if (debug) console.log("Lightmaps, before compile\n", shader)
+        if (debug === "verbose") console.log("Lightmaps, before compile\n", shader)
         this.lightmapScaleOffsetUniform.value = this.lightmapScaleOffset;
         this.lightmapUniform.value = this.lightmapTexture;
         shader.uniforms.lightmapScaleOffset = this.lightmapScaleOffsetUniform;

package/src/engine-components/SeeThrough.ts

@@ -39,6 +39,9 @@ let i = 0;
  * Requires a Renderer component on the same object or a child object.
  * 
  * - Example https://see-through-walls-z23hmxbz1kjfjn.needle.run/
+ * 
+ * @category Rendering
+ * @group Components
  */
 export class SeeThrough extends Behaviour {
 

package/src/engine-components/Skybox.ts

@@ -120,6 +120,9 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreationStart, () => {
  * ```ts
  * skybox.setSkybox("https://example.com/skybox.hdr");
  * ```
+ * 
+ * @category Rendering
+ * @group Components
  */
 export class RemoteSkybox extends Behaviour {
 

package/src/engine-components/SpriteRenderer.ts

@@ -9,6 +9,9 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debugspriterenderer");
 const showWireframe = getParam("wireframe");
 
+/**
+ * @internal
+ */
 class SpriteUtils {
 
     static cache: { [key: string]: BufferGeometry } = {};
@@ -82,7 +85,7 @@ function updateTextureIfNecessary(tex: Texture) {
 }
 
 /**
- * A sprite is a mesh that represents a 2D image
+ * A sprite is a mesh that represents a 2D image. Used by the {@link SpriteRenderer} to render 2D images in the scene.
  * @category Rendering
  * @group Components
  */
@@ -152,6 +155,9 @@ export class Sprite {
 
 const $spriteTexOwner = Symbol("spriteOwner");
 
+/**
+ * @category Sprites
+ */
 export class SpriteSheet {
 
     @serializable(Sprite)
@@ -162,6 +168,11 @@ export class SpriteSheet {
     }
 }
 
+/**
+ * Used by the {@link SpriteRenderer} to hold the sprite sheet and the currently active sprite index.
+ * 
+ * @category Sprites
+ */
 export class SpriteData {
 
     static create() {
@@ -246,7 +257,12 @@ export class SpriteData {
 }
 
 /**
- * The sprite renderer renders a sprite on a GameObject using an assigned spritesheet ({@link SpriteData}).  
+ * The sprite renderer renders a sprite on a GameObject using an assigned spritesheet ({@link SpriteData}).   
+ * 
+ * - Example: https://engine.needle.tools/samples/spritesheet-animation
+ * 
+ * @category Sprites
+ * @group Components
  */
 export class SpriteRenderer extends Behaviour {
 

package/src/engine-components/splines/Spline.ts

@@ -36,6 +36,9 @@ export class SplineData {
  * The spline is defined by an array of knots (SplineData) which define position, rotation and tangents.  
  * 
  * You can create a SplineContainer from an array of points using the static method 'createFromPoints'.
+ * 
+ * @category Splines
+ * @group Components
  */
 export class SplineContainer extends Behaviour {
 

package/src/engine-components/splines/SplineUtils.ts

@@ -3,7 +3,9 @@ import { Vector3 } from "three";
 import { Mathf } from "../../engine/engine_math.js";
 import { SplineContainer, SplineData } from "./Spline.js";
 
-
+/**
+ * @category Splines
+ */
 export namespace SplineUtils {
 
     /**

package/src/engine-components/splines/SplineWalker.ts

@@ -11,6 +11,9 @@ import { SplineContainer } from "./Spline.js";
  * Use this with a SplineContainer component.
  * 
  * - Example http://samples.needle.tools/splines
+ * 
+ * @category Splines
+ * @group Components
  */
 export class SplineWalker extends Behaviour {
 

package/src/engine-components/timeline/PlayableDirector.ts

@@ -114,8 +114,7 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     awake(): void {
-        if (debug)
-            console.log(this, this.playableAsset);
+        if (debug) console.log(`[Timeline] Awake '${this.name}'`, this);
 
         this.rebuildGraph();
 
@@ -134,6 +133,8 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     onEnable() {
+        if (debug) console.log("[Timeline] OnEnable", this.name, this.playOnAwake);
+
         for (const track of this._audioTracks) {
             track.onEnable?.();
         }
@@ -162,6 +163,8 @@ export class PlayableDirector extends Behaviour {
 
     /** @internal */
     onDisable(): void {
+        if (debug) console.log("[Timeline] OnDisable", this.name);
+
         this.stop();
         for (const track of this._audioTracks) {
             track.onDisable?.();
@@ -360,14 +363,17 @@ export class PlayableDirector extends Behaviour {
     private readonly _controlTracks: Array<Tracks.ControlTrackHandler> = [];
     private readonly _customTracks: Array<Tracks.TrackHandler> = [];
 
-    private readonly _allTracks: Array<Array<Tracks.TrackHandler>> = [
-        this._animationTracks,
-        this._audioTracks,
-        this._signalTracks,
-        this._markerTracks,
-        this._controlTracks,
-        this._customTracks
-    ];
+    private readonly _tracksArray: Array<Array<Tracks.TrackHandler>> = [];
+    private get _allTracks(): Array<Array<Tracks.TrackHandler>> {
+        this._tracksArray.length = 0;
+        this._tracksArray.push(this._animationTracks);
+        this._tracksArray.push(this._audioTracks);
+        this._tracksArray.push(this._signalTracks);
+        this._tracksArray.push(this._markerTracks);
+        this._tracksArray.push(this._controlTracks);
+        this._tracksArray.push(this._customTracks);
+        return this._tracksArray;
+    }
 
     /** should be called after evaluate if the director was playing */
     private invokePauseChangedMethodsOnTracks() {