@needle-tools/engine 4.11.0-next.91b9cf1 → 4.11.0-next.cc37c71

package/src/engine-components/Interactable.ts

@@ -10,6 +10,9 @@ export class UsageMarker extends Behaviour
     public usedBy: any = null;
 }
 
-
+/**
+ * An empty component that can be used to mark an object as interactable.
+ * @group Components
+ */
 /** @deprecated */
 export class Interactable extends Behaviour {}

package/src/engine-components/OrbitControls.ts

@@ -255,7 +255,12 @@ export class OrbitControls extends Behaviour implements ICameraController {
      * @default 1
      */
     @serializable()
-    targetLerpDuration = 1;
+    get targetLerpDuration() { return this._lookTargetLerpDuration; }
+    set targetLerpDuration(v) { this._lookTargetLerpDuration = v; }
+    private _lookTargetLerpDuration: number = 1;
+
+    @serializable(Object3D)
+    targetBounds: Object3D | null = null;
 
     /**
      * Rotate the camera left (or right) by the specified angle in radians.   
@@ -326,7 +331,6 @@ export class OrbitControls extends Behaviour implements ICameraController {
     private _lookTargetStartPosition: Vector3 = new Vector3();
     private _lookTargetEndPosition: Vector3 = new Vector3();
     private _lookTargetLerp01: number = 0;
-    private _lookTargetLerpDuration: number = 0;
 
     private _cameraLerpActive: boolean = false;
     private _cameraStartPosition: Vector3 = new Vector3();
@@ -685,10 +689,32 @@ export class OrbitControls extends Behaviour implements ICameraController {
             }
         }
 
+        if (this.targetBounds) {
+            // #region target bounds
+            const targetVector = this._controls.target;
+            const boundsCenter = this.targetBounds.worldPosition;
+            const boundsHalfSize = getTempVector(this.targetBounds.worldScale).multiplyScalar(0.5);
+            const min = getTempVector(boundsCenter).sub(boundsHalfSize);
+            const max = getTempVector(boundsCenter).add(boundsHalfSize);
+            const newTarget = getTempVector(this._controls.target).clamp(min, max);
+            const duration = .1;
+            if (duration <= 0) targetVector.copy(newTarget);
+            else targetVector.lerp(newTarget, this.context.time.deltaTime / duration);
+            if (this._lookTargetLerpActive) {
+                if (duration <= 0) this._lookTargetEndPosition.copy(newTarget);
+                else this._lookTargetEndPosition.lerp(newTarget, this.context.time.deltaTime / (duration * 5));
+            }
+            if (debug) {
+                Gizmos.DrawWireBox(boundsCenter, boundsHalfSize.multiplyScalar(2), 0xffaa00);
+            }
+        }
+
 
         if (this._controls) {
-            if (this.debugLog)
-                this._controls.domElement = this.context.renderer.domElement;
+            if (this.debugLog) this._controls.domElement = this.context.renderer.domElement;
+
+            const viewZoomFactor = 1 / (this.context.focusRectSettings?.zoom || 1);
+
             this._controls.enabled = !this._shouldDisable && this._camera === this.context.mainCameraComponent && !this.context.isInXR && !this._activePointerEvents.some(e => e.used);
             this._controls.keys = this.enableKeys ? defaultKeys : disabledKeys;
             this._controls.autoRotate = this.autoRotate;
@@ -699,6 +725,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
             this._controls.enableDamping = this.enableDamping;
             this._controls.dampingFactor = this.dampingFactor;
             this._controls.enablePan = this.enablePan;
+            this._controls.panSpeed = viewZoomFactor;
             this._controls.enableRotate = this.enableRotate;
             this._controls.minAzimuthAngle = this.minAzimuthAngle;
             this._controls.maxAzimuthAngle = this.maxAzimuthAngle;
@@ -1000,7 +1027,7 @@ export class OrbitControls extends Behaviour implements ICameraController {
     */
     fitCamera(options?: OrbitFitCameraOptions);
     /** @deprecated Use fitCamera(options) */
-    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);    
+    fitCamera(objects?: Object3D | Array<Object3D>, options?: Omit<OrbitFitCameraOptions, "objects">);
     fitCamera(objectsOrOptions?: Object3D | Array<Object3D> | OrbitFitCameraOptions, options?: OrbitFitCameraOptions): void {
 
 

package/src/engine-components/RigidBody.ts

@@ -134,7 +134,12 @@ class TransformWatch {
 }
 
 /**
- * A Rigidbody is used together with a Collider to create physical interactions between objects in the scene. 
+ * A Rigidbody is used together with a Collider to create physical interactions between objects in the scene.   
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation
+ * 
  * @category Physics 
  * @group Components
  */

package/src/engine-components/SeeThrough.ts

@@ -1,11 +1,14 @@
-import { Material, Object3D, Vector3 } from "three";
+import { Material, Object3D, Object3DEventMap, Vector3 } from "three";
 
 import { Gizmos } from "../engine/engine_gizmos.js";
 import { Mathf } from "../engine/engine_math.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { getTempVector } from "../engine/engine_three_utils.js";
 import { getParam } from "../engine/engine_utils.js";
+import { USDObject, USDZExporterContext } from "./api.js";
 import { Behaviour } from "./Component.js";
+import { IUSDExporterExtension } from "./export/usdz/Extension.js";
+import { USDZExporter } from "./export/usdz/USDZExporter.js";
 import { Renderer } from "./Renderer.js";
 
 const debugSeeThrough = getParam("debugseethrough");
@@ -102,6 +105,7 @@ export class SeeThrough extends Behaviour {
     onEnable() {
         this._needsUpdate = true;
         this._renderer = null;
+        SeeThroughUsdzExporterPlugin.components.push(this);
     }
 
     /**  @internal */
@@ -118,6 +122,9 @@ export class SeeThrough extends Behaviour {
             this.rendererMaterials.delete(r);
             this.rendererMaterialsOriginal.delete(r);
         });
+
+        const index = SeeThroughUsdzExporterPlugin.components.indexOf(this);
+        if (index !== -1) SeeThroughUsdzExporterPlugin.components.splice(index, 1);
     }
 
     /**
@@ -253,4 +260,37 @@ export class SeeThrough extends Behaviour {
         });
     }
 
-}
+}
+
+
+;
+class SeeThroughUsdzExporterPlugin implements IUSDExporterExtension {
+
+    static readonly components: SeeThrough[] = [];
+
+    get extensionName() {
+        return "SeeThrough";
+    }
+
+    // onExportObject(object: Object3D<Object3DEventMap>, model: USDObject, context: USDZExporterContext) {
+    //     const component = SeeThroughUsdzExporterPlugin.components.find(c => c.gameObject === object);
+    //     if(!component) return;
+    //     console.log("OH MY GOD SEE THROUGH USDZ EXPORTER", component, model);
+
+    //     model.materialName = "AlphaHashMaterialInstance"; // we could make this unique per object if needed
+
+    //     model.addEventListener("serialize", (writer, context) => {
+    //         writer.appendLine(`# SeeThrough component on ${object.name}`);
+    //     });
+    // }
+
+}
+
+const seeThroughUsdzExporterPlugin = new SeeThroughUsdzExporterPlugin();
+
+USDZExporter.beforeExport.addEventListener(args => {
+    if (SeeThroughUsdzExporterPlugin.components.length === 0) return;
+    if (args.exporter.extensions.includes(seeThroughUsdzExporterPlugin) === false) {
+        args.exporter.extensions.push(seeThroughUsdzExporterPlugin);
+    }
+});

package/src/engine-components/export/usdz/ThreeUSDZExporter.ts

@@ -112,6 +112,10 @@ const PositionIdentity = new Vector3();
 const QuaternionIdentity = new Quaternion();
 const ScaleIdentity = new Vector3(1,1,1);
 
+// #region USDObject
+
+type USDObjectEventType = "serialize" & ({} & string);
+
 class USDObject {
 
 	static USDObject_export_id = 0;
@@ -153,12 +157,13 @@ class USDObject {
 	private set isDynamic( value ) { this._isDynamic = value; }
 	geometry: BufferGeometry | null;
 	material: MeshStandardMaterial | MeshBasicMaterial | Material | MeshPhysicalNodeMaterial | null;
+	// usdMaterial?: USDMaterial;
 	camera: PerspectiveCamera | OrthographicCamera | null;
 	parent: USDObject | null;
 	skinnedMesh: SkinnedMesh | null;
 	children: Array<USDObject | null> = [];
 	animations: AnimationClip[] | null;
-	_eventListeners: {};
+	_eventListeners: Record<USDObjectEventType, Function[]>;
 
 	// these are for tracking which xformops are needed
 	needsTranslate: boolean = false;
@@ -201,7 +206,7 @@ class USDObject {
 		this.camera = camera;
 		this.parent = null;
 		this.children = [];
-		this._eventListeners = {};
+		this._eventListeners = {} as Record<USDObjectEventType, Function[]>;
 		this._isDynamic = false;
 		this.skinnedMesh = skinnedMesh;
 		this.animations = animations;
@@ -287,7 +292,7 @@ class USDObject {
 
 	}
 
-	addEventListener( evt, listener: ( writer: USDWriter, context: USDZExporterContext ) => void ) {
+	addEventListener( evt : USDObjectEventType, listener: ( writer: USDWriter, context: USDZExporterContext ) => void ) {
 
 		if ( ! this._eventListeners[ evt ] ) this._eventListeners[ evt ] = [];
 		this._eventListeners[ evt ].push( listener );
@@ -316,6 +321,67 @@ class USDObject {
 }
 
 
+// #region USDMaterial
+
+// class MaterialInput {
+// 	name: string;
+// }
+
+class USDMaterial {
+
+	static USDMaterial_id = 0;
+
+	readonly material: Material;
+	readonly id: number;
+
+	name: string;
+
+	isOverride: boolean = false;
+	isInstanceable: boolean = false;
+
+	constructor( material: Material ) {
+		this.material = material;
+		this.id = USDMaterial.USDMaterial_id ++;
+		this.name = makeNameSafe( material.name || 'Material_' + this.id );
+	}
+
+	readonly inputs: Record<string, string | number | boolean | number[] | undefined> = {};
+
+	// addInput( name: string, value: "" ) {
+
+
+
+	// }
+
+
+	serialize( writer: USDWriter, _context: USDZExporterContext ) {
+
+		const name = this.name;
+
+		writer.appendLine( `def Material "${this.name}" ${name ?`( displayName = "${makeDisplayNameSafe(name)}" )` : ''}` );
+		writer.beginBlock();
+			
+
+		writer.closeBlock();
+		
+		// def Material "${materialName}" ${material.name ?`(
+		// 	displayName = "${material.name}"
+		// )` : ''}
+		// {
+		// 	token outputs:mtlx:surface.connect = ${materialRoot}/${materialName}/Occlusion.outputs:out>
+
+		// 	def Shader "Occlusion"
+		// 	{
+		// 		uniform token info:id = "${mode}"
+		// 		token outputs:out
+		// 	}
+		// }`;
+	
+	}
+}
+
+// #region USDDocument
+
 class USDDocument extends USDObject {
 
 	stageLength: number;
@@ -448,6 +514,7 @@ ${comments}
 
 }
 
+
 const newLine = '\n';
 const materialRoot = '</StageRoot/Materials';
 
@@ -540,6 +607,8 @@ class USDWriter {
 
 declare type TextureMap = {[name: string]: {texture: Texture, scale?: Vector4}};
 
+// #region USDZExporterContext
+
 class USDZExporterContext {
 	root?: Object3D;
 	exporter: USDZExporter;
@@ -576,6 +645,10 @@ class USDZExporterContext {
 
 	}
 
+	makeNameSafe( str ) {
+		return makeNameSafe( str );
+	}
+
 }
 
 /**[documentation](https://developer.apple.com/documentation/arkit/usdz_schemas_for_ar/preliminary_anchoringapi/preliminary_anchoring_type) */
@@ -597,6 +670,8 @@ class USDZExporterOptions {
 	exportInvisible: boolean = false;
 }
 
+// #region USDZExporter
+
 class USDZExporter {
 	debug: boolean;
 	pruneUnusedNodes: boolean;
@@ -698,13 +773,7 @@ class USDZExporter {
 		}
 
 		Progress.report('export-usdz', { message: "Parsing document", autoStep: 10 });
-		await parseDocument( context, () => {
-			// injected after stageRoot.
-			// TODO property use context/writer instead of string concat
-			Progress.report('export-usdz', "Building materials");
-			const result = buildMaterials( materials, textures, options.quickLookCompatible );
-			return result;
-		} );
+		await parseDocument( context, options );
 
 		Progress.report("export-usdz", "Invoking onAfterSerialize");
 		await invokeAll( context, 'onAfterSerialize' );
@@ -726,7 +795,7 @@ class USDZExporter {
 		const final = header + '\n' + context.output;
 
 		// full output file
-		if ( this.debug ) console.log( final );
+		if ( this.debug ) console.debug( final );
 
 		files[ modelFileName ] = fflate.strToU8( final );
 		context.output = '';
@@ -822,6 +891,9 @@ class USDZExporter {
 
 }
 
+// #endregion
+
+// #region traverse 
 function traverse( object: Object3D, parentModel: USDObject, context: USDZExporterContext, keepObject?: (object: Object3D) => boolean ) {
 
 	if (!context.exportInvisible && !object.visible) return;
@@ -919,6 +991,8 @@ function traverse( object: Object3D, parentModel: USDObject, context: USDZExport
 
 }
 
+// #endregion
+
 function logUsdHierarchy( object: USDObject, prefix: string, ...extraLogObjects: any[] ) { 
 
 	const item = {};
@@ -1020,7 +1094,8 @@ function prune ( object: USDObject, options : {
 	return canBePruned;
 }
 
-async function parseDocument( context: USDZExporterContext, afterStageRoot: () => string ) {
+// #region parseDocument
+async function parseDocument( context: USDZExporterContext, options: USDZExporterOptions ) {
 
 	Progress.start("export-usdz-resources", "export-usdz");
 	const resources: Array<() => void> = [];
@@ -1086,14 +1161,21 @@ async function parseDocument( context: USDZExporterContext, afterStageRoot: () =
 
 	writer.closeBlock();
 	writer.closeBlock();
-	writer.appendLine(afterStageRoot());
+	
+	// TODO property use context/writer instead of string concat
+	Progress.report('export-usdz', "Building materials");
+	const result = buildMaterials( context.materials, context.textures, options.quickLookCompatible );
+	writer.appendLine(result);
+
 	writer.closeBlock();
 
 	Progress.report("export-usdz", "write to string")
 	context.output += writer.toString();
 
 }
+// #endregion
 
+// #region addResources
 function addResources( object: USDObject | null, context: USDZExporterContext, resources: Array<() => void>) {
 
 	if ( !object ) return;
@@ -1132,7 +1214,7 @@ function addResources( object: USDObject | null, context: USDZExporterContext, r
 
 	if ( material ) {
 		
-		if ( ! ( material.uuid in context.materials ) ) {
+		if ( context.materials.get( material.uuid ) === undefined ) {
 
 			context.materials[ material.uuid ] = material;
 
@@ -1169,6 +1251,10 @@ async function invokeAll( context: USDZExporterContext, name: string, writer: US
 	}
 
 }
+
+// #endregion
+
+// #region GPU utils
 let _renderer: WebGLRenderer | null = null;
 let renderTarget: WebGLRenderTarget | null = null;
 let fullscreenQuadGeometry: PlaneGeometry | null;
@@ -1431,7 +1517,9 @@ function getPathToSkeleton(bone: Object3D, assumedRoot: Object3D) {
 	return path;
 }
 
-// Xform
+// #endregion
+
+// #region XForm
 
 export function buildXform( model: USDObject | null, writer: USDWriter, context: USDZExporterContext ) {
 
@@ -1635,7 +1723,7 @@ function buildMatrixRow( array, offset ) {
 
 }
 
-// Mesh
+// #region Mesh
 
 function buildMeshObject( geometry: BufferGeometry, bonesArray: Bone[] = [], quickLookCompatible: boolean = true) {
 
@@ -1948,7 +2036,9 @@ function buildVector2Array( attribute: BufferAttribute | InterleavedBufferAttrib
 
 }
 
-// Materials
+// #endregion
+
+// #region Materials
 
 function buildMaterials( materials: Map<string, Material>, textures: TextureMap, quickLookCompatible = false ) {
 
@@ -2103,10 +2193,14 @@ function buildTexture( texture: Texture, mapType: MapType, quickLookCompatible:
 		}`;
 }
 
+
 function buildMaterial( material: MeshBasicMaterial, textures: TextureMap, quickLookCompatible = false ) {
 
 	const materialName = getMaterialName(material);
 
+	// TODO: refactor to USDMaterial class
+	// const usdMaterial = new USDMaterial(material);
+
 	// Special case: occluder material
 	// Supported on iOS 18+ and visionOS 1+
 	const isShadowCatcherMaterial = 
@@ -2330,6 +2424,7 @@ function buildMaterial( material: MeshBasicMaterial, textures: TextureMap, quick
 		}
 	}
 
+
 	return `
 
 		def Material "${materialName}" ${material.name ?`(
@@ -2368,6 +2463,8 @@ ${samplers.join( '\n' )}` : ''}
 		}`;
 }
 
+// #endregion
+
 function buildColor( color ) {
 
 	return `(${color.r}, ${color.g}, ${color.b})`;
@@ -2407,6 +2504,9 @@ const formatsWithAlphaChannel = [
 	36492, // RGBA_BPTC_Format
 ];
 
+
+// #region exports
+
 export { 
 	buildMatrix,
 	decompressGpuTexture,

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

@@ -1,5 +1,5 @@
 
-import { Object3D } from "three"
+import { Object3D, Vector3 } from "three"
 
 import { Mathf } from "../../engine/engine_math.js";
 import { serializeable } from "../../engine/engine_serialization_decorator.js";
@@ -7,7 +7,10 @@ import { Behaviour } from "../Component.js";
 import { SplineContainer } from "./Spline.js";
 
 /**
- * Moves an object along a spline. Use this with a SplineContainer component.
+ * Moves an object along a spline.   
+ * Use this with a SplineContainer component.
+ * 
+ * - Example http://samples.needle.tools/splines
  */
 export class SplineWalker extends Behaviour {
 
@@ -17,18 +20,35 @@ export class SplineWalker extends Behaviour {
     @serializeable(SplineContainer)
     spline: SplineContainer | null = null;
 
-    /** The object to move along the spline. If object is undefined then the spline walker will use the gameObject the component has been added to 
+    /** 
+     * The object to move along the spline.   
+     * If object is undefined then the spline walker will use it's own object (gameObject).  
+     * If object is null the spline walker will not move any object.
      * @default undefined
     */
     @serializeable(Object3D)
     object?: Object3D | null = undefined;
 
-    /** The object to look at while moving along the spline 
+
+
+    /**
+     * If true the object will rotate to look in the direction of the spline while moving along it.
+     * @default true
+     */
+    @serializeable()
+    useLookAt = true;
+
+    /** 
+     * The object to look at while moving along the spline.   
+     * If null the object will look in the direction of the spline.   
+     * This can be disabled by setting useLookAt to false.
      * @default null
     */
     @serializeable(Object3D)
     lookAt: Object3D | null = null;
-    
+
+
+
     /**
      * When clamp is set to true, the position01 value will be clamped between 0 and 1 and the object will not loop the spline.
      * @default false
@@ -36,7 +56,10 @@ export class SplineWalker extends Behaviour {
     @serializeable()
     clamp: boolean = false;
 
-    /** The current position on the spline. The value ranges from 0 (start of the spline curve) to 1 (end of the spline curve)
+    /**   
+     * The current position on the spline. The value ranges from 0 (start of the spline curve) to 1 (end of the spline curve)  
+     * 
+     * When setting this value, the position will be updated in the next frame.
      * @default 0
      */
     // @type float
@@ -46,7 +69,7 @@ export class SplineWalker extends Behaviour {
     }
     set position01(v: number) {
         this._position01 = v;
-        this.updateFromPosition();
+        this._needsUpdate = true;
     }
 
     /** Resets the position to 0 */
@@ -68,25 +91,60 @@ export class SplineWalker extends Behaviour {
     @serializeable()
     duration: number = 10;
 
+    /**
+     * The strength with which the object is pulled to the spline.  
+     * This can be used to create a "rubber band" effect when the object is moved away from the spline by other forces.  
+     * A value of 0 means no pull, a value of 1 means the object is always on the spline.  
+     * @default 1
+     */
+    pullStrength: number = 1;
+
 
     // #region internal
 
     private _position01: number = 0;
+    private _needsUpdate = false;
 
     /** @internal */
     start() {
-        if(this.object === undefined) this.object = this.gameObject;
+        if (this.object === undefined) this.object = this.gameObject;
         this.updateFromPosition();
     }
 
+    /** @internal */
+    onEnable(): void {
+        window.addEventListener("pointerdown", this.onUserInput, { passive: true });
+        window.addEventListener("wheel", this.onUserInput, { passive: true });
+    }
+    /** @internal */
+    onDisable(): void {
+        window.removeEventListener("pointerdown", this.onUserInput);
+        window.removeEventListener("wheel", this.onUserInput);
+    }
+    private onUserInput = () => {
+        if (this.object?.contains(this.context.mainCamera)) {
+            this._needsUpdate = false;
+            this._performedUpdates += 999;
+        }
+    }
+
+    /** @internal */
     update() {
         if (this.autoRun) {
+            this._needsUpdate = true;
             this._position01 += this.context.time.deltaTime / this.duration;
+        }
+
+        if (this._needsUpdate) {
+            this._needsUpdate = false;
             this.updateFromPosition();
         }
     }
 
-
+    /**
+     * Updates the position of the object based on the current position01 value.  
+     * @internal
+     */
     private updateFromPosition() {
         if (!this.spline || !this.spline.curve) return;
         if (!this.object) return;
@@ -96,11 +154,38 @@ export class SplineWalker extends Behaviour {
 
         const t = this._position01 >= 1 ? 1 : this._position01 % 1;
         const pt = this.spline.getPointAt(t);
-        this.object.worldPosition = pt;
-        if (!this.lookAt) {
-            const tan = this.spline.getTangentAt(t);
-            this.object.lookAt(pt.add(tan));
+
+        if (this.pullStrength >= 1) {
+            this.object.worldPosition = pt;
+        }
+        else {
+            if (this._position01 !== this._lastPosition01) {
+                this._performedUpdates = 0;
+            }
+            this._requiredUpdates = Math.round(100 / this.pullStrength);
+            if (this._performedUpdates < this._requiredUpdates) {
+                const wp = this.object.worldPosition;
+                this._performedUpdates++;
+                const pull = Mathf.clamp01(this.pullStrength);
+                const newPosition = this.object.worldPosition = wp.lerp(pt, pull * (this.context.time.deltaTime / .3));
+                this._lastPositionVector.copy(newPosition);
+                this._needsUpdate = true;
+            }
         }
-        else this.object.lookAt(this.lookAt.worldPosition);
+
+        if (this.useLookAt) {
+            if (!this.lookAt) {
+                const tan = this.spline.getTangentAt(t);
+                this.object.lookAt(pt.add(tan));
+            }
+            else this.object.lookAt(this.lookAt.worldPosition);
+        }
+
+        this._lastPosition01 = this._position01;
     }
+
+    private _lastPosition01 = 0;
+    private _requiredUpdates: number = 0;
+    private _performedUpdates: number = 0;
+    private _lastPositionVector = new Vector3();
 }