@needle-tools/engine 4.11.2 → 4.11.3-next.2d2dff8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.11.2",
+  "version": "4.11.3-next.2d2dff8",
   "description": "Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.",
   "main": "dist/needle-engine.min.js",
   "exports": {
@@ -169,4 +169,4 @@
   "module": "lib/needle-engine.js",
   "typings": "lib/needle-engine.d.ts",
   "types": "lib/needle-engine.d.ts"
-}
+}

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/RendererLightmap.ts

@@ -9,9 +9,13 @@ 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
+
+/**
+ * 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 {

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 {
 
@@ -241,6 +244,7 @@ export class SeeThrough extends Behaviour {
 
                 const wasTransparent = mat.transparent;
                 const wasAlphaHash = mat.alphaHash;
+                const previousOpacity = mat.opacity;
 
                 mat.alphaHash = this.useAlphaHash;
 
@@ -253,7 +257,10 @@ export class SeeThrough extends Behaviour {
                     mat.transparent = mat.opacity >= 1 ? false : !this.useAlphaHash;
                 }
 
-                if (wasTransparent != mat.transparent || wasAlphaHash != mat.alphaHash) {
+                if (wasTransparent !== mat.transparent 
+                    || wasAlphaHash !== mat.alphaHash 
+                    || mat.opacity !== previousOpacity // MeshPhysicsMaterial needs that and maybe other materials too...
+                ) {
                     mat.needsUpdate = true;
                 }
             }

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/export/usdz/ThreeUSDZExporter.ts

@@ -42,9 +42,9 @@ import { Progress } from '../../../engine/engine_time_utils.js';
 // import { BehaviorExtension } from '../../api.js';
 import type { IUSDExporterExtension } from './Extension.js';
 import type { AnimationExtension } from './extensions/Animation.js';
+import { BehaviorExtension } from './extensions/behavior/Behaviour.js';
 import type { PhysicsExtension } from './extensions/behavior/PhysicsExtension.js';
 import {buildNodeMaterial} from './extensions/NodeMaterialConverter.js';
-import { BehaviorExtension } from './extensions/behavior/Behaviour.js';
 
 type MeshPhysicalNodeMaterial = import("three/src/materials/nodes/MeshPhysicalNodeMaterial.js").default;
 

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/SignalAsset.ts

@@ -2,15 +2,23 @@ import { serializable } from "../../engine/engine_serialization_decorator.js";
 import { getParam } from "../../engine/engine_utils.js";
 import { Behaviour } from "../Component.js";
 import { EventList } from "../EventList.js";
+import type { PlayableDirector } from "./PlayableDirector.js";
 
 const debug = getParam("debugsignals")
 
 
+/**
+ * Used to reference a signal asset in a SignalReceiver. This is internally used by the {@link SignalReceiverEvent}.
+ */
 export class SignalAsset {
     @serializable()
     guid!: string;
 }
 
+/**
+ * An event that links a signal to a reaction.
+ * Used internally by {@link SignalReceiver}.
+ */
 export class SignalReceiverEvent {
     @serializable(SignalAsset)
     signal!: SignalAsset;
@@ -19,7 +27,10 @@ export class SignalReceiverEvent {
 }
 
 /** SignalReceiver is a component that listens for signals and invokes a reaction when a signal is received. 
- * Signals can be added to a signal track on a timeline
+ * Signals can be added to a signal track on a {@link PlayableDirector}
+ * 
+ * @category Sequencing and Timelines
+ * @group Components
  */
 export class SignalReceiver extends Behaviour {
 
@@ -41,7 +52,7 @@ export class SignalReceiver extends Behaviour {
 
     /** @internal */
     awake(): void {
-        if(debug) console.log("SignalReceiver awake", this);
+        if (debug) console.log("SignalReceiver awake", this);
     }
 
     /** @internal */

package/src/engine-components/ui/Raycaster.ts

@@ -28,6 +28,12 @@ export abstract class Raycaster extends Behaviour {
 }
 
 
+/**
+ * A Raycaster that performs raycasting against its own GameObject.  
+ * 
+ * @category Interaction
+ * @group Components
+ */
 export class ObjectRaycaster extends Raycaster {
     private targets: Object3D[] | null = null;
     private raycastHits: Intersection[] = [];
@@ -65,6 +71,13 @@ export class ObjectRaycaster extends Raycaster {
     }
 }
 
+
+/**
+ * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).  
+ * 
+ * @category UI
+ * @group Components
+ */
 export class GraphicRaycaster extends ObjectRaycaster {
     // eventCamera: Camera | null = null;
     // ignoreReversedGraphics: boolean = false;
@@ -76,6 +89,12 @@ export class GraphicRaycaster extends ObjectRaycaster {
     }
 }
 
+/**
+ * A Raycaster that performs sphere overlap raycasting for spatial grab interactions in XR.  
+ * 
+ * @category XR
+ * @group Components
+ */
 export class SpatialGrabRaycaster extends Raycaster {
 
     /**