@needle-tools/engine 4.9.0 → 4.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/engine",
-  "version": "4.9.0",
+  "version": "4.9.1",
   "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": {

package/plugins/vite/build.js

@@ -1,4 +1,7 @@
 
+/** 
+ * @returns {import('vite').Plugin}
+ */
 export const needleBuild = (command, config, userSettings) => {
 
     // TODO: need to set this when building a dist

package/src/engine/engine_gameobject.ts

@@ -1,4 +1,4 @@
-import { Bone, Object3D, Quaternion, SkinnedMesh, Vector3 } from "three";
+import { Bone, Euler, Object3D, Quaternion, SkinnedMesh, Vector3 } from "three";
 
 import { $shadowDomOwner } from "../engine-components/ui/Symbols.js";
 import { type AssetReference } from "./engine_addressables.js";
@@ -11,7 +11,7 @@ import { processNewScripts } from "./engine_mainloop_utils.js";
 import { InstantiateIdProvider } from "./engine_networking_instantiate.js";
 import { assign, ISerializable } from "./engine_serialization_core.js";
 import { Context, registerComponent } from "./engine_setup.js";
-import { logHierarchy, setWorldPosition, setWorldQuaternion } from "./engine_three_utils.js";
+import { getTempQuaternion, logHierarchy, setWorldPosition, setWorldQuaternion } from "./engine_three_utils.js";
 import { type Constructor, type GuidsMap, type IComponent as Component, type IComponent, IEventList, type IGameObject as GameObject, type UIDProvider } from "./engine_types.js";
 import { deepClone, getParam, tryFindObject } from "./engine_utils.js";
 import { apply } from "./js-extensions/index.js";
@@ -24,12 +24,12 @@ export type IInstantiateOptions = {
     //** parent guid or object */
     parent?: string | Object3D;
     /** position in local space. Set `keepWorldPosition` to true if this is world space */
-    position?: Vector3;
+    position?: Vector3 | [number, number, number];
     /** for duplicatable parenting */
     keepWorldPosition?: boolean;
     /** rotation in local space. Set `keepWorldPosition` to true if this is world space */
-    rotation?: Quaternion;
-    scale?: Vector3;
+    rotation?: Quaternion | Euler | [number, number, number];
+    scale?: Vector3 | [number, number, number];
     /** if the instantiated object should be visible */
     visible?: boolean;
     context?: Context;
@@ -46,9 +46,9 @@ export class InstantiateOptions implements IInstantiateOptions {
     idProvider?: UIDProvider | undefined;
     parent?: string | undefined | Object3D;
     keepWorldPosition?: boolean
-    position?: Vector3 | undefined;
-    rotation?: Quaternion | undefined;
-    scale?: Vector3 | undefined;
+    position?: Vector3 | [number, number, number] | undefined;
+    rotation?: Quaternion | Euler | [number, number, number] | undefined;
+    scale?: Vector3 | [number, number, number] | undefined;
     visible?: boolean | undefined;
     context?: Context | undefined;
     components?: boolean | undefined;
@@ -58,9 +58,9 @@ export class InstantiateOptions implements IInstantiateOptions {
         clone.idProvider = this.idProvider;
         clone.parent = this.parent;
         clone.keepWorldPosition = this.keepWorldPosition;
-        clone.position = this.position?.clone();
-        clone.rotation = this.rotation?.clone();
-        clone.scale = this.scale?.clone();
+        clone.position = Array.isArray(this.position) ? [...this.position] : this.position?.clone();
+        clone.rotation = Array.isArray(this.rotation) ? [...this.rotation] : this.rotation?.clone();
+        clone.scale = Array.isArray(this.scale) ? [...this.scale] : this.scale?.clone();
         clone.visible = this.visible;
         clone.context = this.context;
         clone.components = this.components;
@@ -72,9 +72,9 @@ export class InstantiateOptions implements IInstantiateOptions {
         this.idProvider = other.idProvider;
         this.parent = other.parent;
         this.keepWorldPosition = other.keepWorldPosition;
-        this.position = other.position?.clone();
-        this.rotation = other.rotation?.clone();
-        this.scale = other.scale?.clone();
+        this.position = Array.isArray(other.position) ? [...other.position] : other.position?.clone();
+        this.rotation = Array.isArray(other.rotation) ? [...other.rotation] : other.rotation?.clone();
+        this.scale = Array.isArray(other.scale) ? [...other.scale] : other.scale?.clone();
         this.visible = other.visible;
         this.context = other.context;
         this.components = other.components;
@@ -287,6 +287,8 @@ declare type ObjectCloneReference = {
 
 
 declare type InstantiateReferenceMap = Record<string, ObjectCloneReference>;
+declare type NewObjectReferenceMap = Record<string, { target: object, key: string }>;
+
 /**
  * Provides access to the instantiated object and its clone
  */
@@ -325,13 +327,13 @@ export function instantiate(instance: AssetReference | GameObject | Object3D, op
     }
 
     const components: Array<Component> = [];
-    const goMapping: InstantiateReferenceMap = {}; // used to resolve references on components to components on other gameobjects to their new counterpart
+    const referencemap: InstantiateReferenceMap = {}; // used to resolve references on components to components on other gameobjects to their new counterpart
     const skinnedMeshes: InstantiateReferenceMap = {}; // used to resolve skinned mesh bones
-    const clone = internalInstantiate(context, instance, options, components, goMapping, skinnedMeshes);
+    const clone = internalInstantiate(context, instance, options, components, referencemap, skinnedMeshes);
 
     if (clone) {
-        resolveReferences(goMapping);
-        resolveAndBindSkinnedMeshBones(skinnedMeshes, goMapping);
+        resolveReferences(clone, referencemap);
+        resolveAndBindSkinnedMeshBones(skinnedMeshes, referencemap);
     }
 
     if (debug) {
@@ -426,19 +428,45 @@ function internalInstantiate(
         parent.add(clone);
     }
 
-    // apply transform
+    // POSITION
     if (opts?.position) {
-        setWorldPosition(clone, opts.position);
+        if (Array.isArray(opts.position)) {
+            const vec = new Vector3();
+            vec.fromArray(opts.position);
+            clone.worldPosition = vec;
+        }
+        else {
+            clone.worldPosition = opts.position;
+        }
     }
     else clone.position.copy(instance.position);
+
+    // ROTATION
     if (opts?.rotation) {
-        setWorldQuaternion(clone, opts.rotation);
+        if (opts.rotation instanceof Quaternion)
+            clone.worldQuaternion = opts.rotation;
+        else if (opts.rotation instanceof Euler)
+            clone.worldQuaternion = getTempQuaternion().setFromEuler(opts.rotation);
+        else if (Array.isArray(opts.rotation)) {
+            const euler = new Euler();
+            euler.fromArray(opts.rotation);
+            clone.worldQuaternion = getTempQuaternion().setFromEuler(euler);
+        }
     }
     else clone.quaternion.copy(instance.quaternion);
+
+    // SCALE
     if (opts?.scale) {
-        clone.scale.copy(opts.scale);
         // TODO MAJOR: replace with worldscale
         // clone.worldScale = opts.scale;
+        if (Array.isArray(opts.scale)) {
+            const vec = new Vector3();
+            vec.fromArray(opts.scale);
+            opts.scale = vec;
+        }
+        else {
+            clone.scale.copy(opts.scale);
+        }
     }
     else clone.scale.copy(instance.scale);
 
@@ -470,17 +498,7 @@ function internalInstantiate(
         for (let i = 0; i < components.length; i++) {
             const comp = components[i];
             const copy = new comp.constructor();
-            assign(copy, comp, undefined, {
-                // onAssign: (source, key, value) => {
-                //     if (typeof value === "object") {
-                //         const serializable = source as ISerializable;
-                //         if (serializable?.$serializedTypes?.[key]) {
-                //             console.debug("TODO CLONE", key, value);
-                //         }
-                //     }
-                //     return value;
-                // }
-            });
+            onAssignComponent(comp, copy, objectsMap);
             // make sure the original guid stays intact
             if (comp[editorGuidKeyName] !== undefined)
                 copy[editorGuidKeyName] = comp[editorGuidKeyName];
@@ -501,7 +519,6 @@ function internalInstantiate(
         opts.parent = undefined;
         opts.visible = undefined;
     }
-
     for (const ch in instance.children) {
         const child = instance.children[ch];
         const newChild = internalInstantiate(context, child as GameObject, opts, componentsList, objectsMap, skinnedMeshesMap);
@@ -510,11 +527,59 @@ function internalInstantiate(
             clone.add(newChild);
         }
     }
-
     return clone;
+}
+
 
+function onAssignComponent(source: any, target: any, _newObjectsMap: InstantiateReferenceMap) {
+    assign(target, source, undefined, {
+        // onAssigned: (target, key, _oldValue, value) => {
+            // if (value !== null && typeof value === "object") {
+            //     const serializable = target as ISerializable;
+            //     if (serializable?.$serializedTypes?.[key]) {
+            //         if (!(value instanceof Object3D)) {
+            //             // let clone = null;
+            //             // if ("clone" in value) {
+            //             //     if (canClone(value)) clone = (value as any).clone();
+            //             // }
+            //             // else {
+            //             //     clone = Object.assign(Object.create(Object.getPrototypeOf(value)), value);
+            //             // }
+            //             // if (clone) {
+            //             //     console.debug(key, { target, value, clone })
+            //             //     target[key] = clone;
+            //             //     findNestedReferences(clone, objectsMap);
+            //             // }
+            //             // else console.debug("Could not clone value for key", key, value);
+            //         }
+            //         else {
+            //             console.log("ASSIGNED", value)
+            //         }
+
+            //         recursiveAssign(target, target[key], newObjectsMap);
+            //     }
+
+            // }
+        // }
+    });
 }
 
+// function findNestedReferences(object: object, map: InstantiateReferenceMap) {
+//     const keys = Object.keys(object);
+//     for (const key of keys) {
+//         const val = (object as any)[key];
+//         if (val instanceof Object3D) {
+//             if ("guid" in val && val.guid) {
+//                 console.log("FOUND ", val.guid, val)
+//                 map[val.guid] = { original: val, clone: null };
+//             }
+//         }
+//         else if (typeof val === "object" && val !== null) {
+//             findNestedReferences(val, map);
+//         }
+//     }
+// }
+
 function resolveAndBindSkinnedMeshBones(
     skinnedMeshes: { [key: string]: ObjectCloneReference },
     newObjectsMap: { [key: string]: ObjectCloneReference }
@@ -599,13 +664,13 @@ function resolveAndBindSkinnedMeshBones(
 
 // }
 
-function resolveReferences(newObjectsMap: InstantiateReferenceMap) {
+function resolveReferences(_newInstance: Object3D, newObjectsMap: InstantiateReferenceMap) {
     // for every object that is newly created we want to update references to their newly created counterparts
     // e.g. a collider instance referencing a rigidbody instance should be updated so that 
     // the cloned collider does not reference the cloned rigidbody (instead of the original rigidbody)
     for (const key in newObjectsMap) {
         const val = newObjectsMap[key];
-        const clone = val.clone as Object3D;
+        const clone = val.clone as Object3D | null;
         // resolve references
         if (clone?.isObject3D && clone?.userData?.components) {
             for (let i = 0; i < clone.userData.components.length; i++) {
@@ -706,4 +771,6 @@ function postProcessNewInstance(copy: Object3D, key: string, value: IComponent |
             return copy;
         }
     }
-}
+}
+
+// const canClone = (value: any) => value.isVector4 || value.isVector3 || value.isVector2 || value.isQuaternion || value.isEuler || value.isColor === true;

package/src/engine/engine_networking_instantiate.ts

@@ -1,4 +1,4 @@
-import { Object3D, Quaternion, Vector3 } from "three";
+import { Euler, Object3D, Quaternion, Vector3 } from "three";
 // https://github.com/uuidjs/uuid
 // v5 takes string and namespace
 import { v5 } from 'uuid';
@@ -254,12 +254,27 @@ export function syncInstantiate(object: GameObject | Object3D, opts: SyncInstant
             if (opts.deleteOnDisconnect === true)
                 model.deleteStateOnDisconnect = true;
             if (originalOpts) {
-                if (originalOpts.position)
-                    model.position = { x: originalOpts.position.x, y: originalOpts.position.y, z: originalOpts.position.z };
-                if (originalOpts.rotation)
+                if (originalOpts.position) {
+                    if (Array.isArray(originalOpts.position)) {
+                        model.position = { x: originalOpts.position[0], y: originalOpts.position[1], z: originalOpts.position[2] };
+                    }
+                    else model.position = { x: originalOpts.position.x, y: originalOpts.position.y, z: originalOpts.position.z };
+                }
+                if (originalOpts.rotation) {
+                    if (originalOpts.rotation instanceof Euler) {
+                        originalOpts.rotation = new Quaternion().setFromEuler(originalOpts.rotation);
+                    }
+                    else if (originalOpts.rotation instanceof Array) {
+                        originalOpts.rotation = new Quaternion().fromArray(originalOpts.rotation);
+                    }
                     model.rotation = { x: originalOpts.rotation.x, y: originalOpts.rotation.y, z: originalOpts.rotation.z, w: originalOpts.rotation.w };
-                if (originalOpts.scale)
-                    model.scale = { x: originalOpts.scale.x, y: originalOpts.scale.y, z: originalOpts.scale.z };
+                }
+                if (originalOpts.scale) {
+                    if (Array.isArray(originalOpts.scale)) {
+                        model.scale = { x: originalOpts.scale[0], y: originalOpts.scale[1], z: originalOpts.scale[2] };
+                    }
+                    else model.scale = { x: originalOpts.scale.x, y: originalOpts.scale.y, z: originalOpts.scale.z };
+                }
             }
             if (!model.position)
                 model.position = { x: go.position.x, y: go.position.y, z: go.position.z };

package/src/engine/engine_serialization_core.ts

@@ -658,10 +658,10 @@ export const $isAssigningProperties = Symbol("assigned component properties");
  * @param key the key that is being assigned
  * @param value the value that is being assigned
  */
-type OnAssign = (source: object, key: string, value: any) => any;
+type AssignedCallback = (source: object, key: string, oldValue: any, newValue: any) => any;
 
 /** Object.assign behaviour but check if property is writeable (e.g. getter only properties are skipped) */
-export function assign(target: any, source: any, info?: ImplementationInformation, opts?: { onAssign?: OnAssign }) {
+export function assign(target: any, source: any, info?: ImplementationInformation, opts?: { onAssigned?: AssignedCallback }) {
     if (source === undefined || source === null) return;
     if (target === undefined || target === null) return;
 
@@ -699,13 +699,13 @@ export function assign(target: any, source: any, info?: ImplementationInformatio
             // arrow functions are defined as properties on the object
             continue;
         }
-        if (!desc || desc.writable === true) {
-            const value = opts?.onAssign ? opts.onAssign(source, key, source[key]) : source[key];
-            target[key] = value;
-        }
-        else if (desc?.set !== undefined) {
-            const value = opts?.onAssign ? opts.onAssign(source, key, source[key]) : source[key];
-            target[key] = value;
+        if (!desc || desc.writable === true || desc.set !== undefined) {
+            const newValue = source[key];
+            const oldValue = target[key];
+            target[key] = newValue;
+            if (opts?.onAssigned) {
+                opts.onAssigned(target, key, oldValue, newValue);
+            }
         }
     }
     delete target[$isAssigningProperties];

package/src/engine/engine_serialization_decorator.ts

@@ -27,7 +27,8 @@ export const serializable = function <T>(type?: Constructor<T> | null | Array<Co
 
     return function (_target: any, _propertyKey: string | { name: string }) {
         if (!_target) {
-            console.error("Found @serializable decorator without a target");
+            const propertyName = typeof _propertyKey === 'string' ? _propertyKey : _propertyKey.name;
+            console.warn(`@serializable without a target at '${propertyName}'.`);
             return;
         }
         // The _propertyKey parameter is a string in TS4 with experimentalDecorators

package/src/engine-components/Renderer.ts

@@ -1,5 +1,5 @@
 import { getRaycastMesh } from "@needle-tools/gltf-progressive";
-import { AxesHelper, Material, Mesh, Object3D, SkinnedMesh, Texture, Vector4 } from "three";
+import { AxesHelper, Material, Mesh, MeshBasicMaterial, MeshPhysicalMaterial, MeshStandardMaterial, Object3D, RawShaderMaterial, ShaderMaterial, SkinnedMesh, Texture, Vector4 } from "three";
 
 import { showBalloonWarning } from "../engine/debug/index.js";
 import { getComponent, getOrAddComponent } from "../engine/engine_components.js";
@@ -48,6 +48,8 @@ export enum RenderState {
     Front = 2,
 }
 
+type SharedMaterial = (Material & Partial<MeshStandardMaterial> & Partial<MeshPhysicalMaterial> & Partial<ShaderMaterial> & Partial<RawShaderMaterial>);
+
 
 // support sharedMaterials[index] assigning materials directly to the objects
 class SharedMaterialArray implements ISharedMaterials {
@@ -185,7 +187,7 @@ class SharedMaterialArray implements ISharedMaterials {
         this.changed = true;
     }
 
-    private getMaterial(index: number): Material | null {
+    private getMaterial(index: number): SharedMaterial | null {
         index = this.resolveIndex(index);
         if (index < 0) return null;
         const obj = this._targets;
@@ -302,11 +304,11 @@ export class Renderer extends Behaviour implements IRenderer {
         return this._sharedMeshes;
     }
 
-    get sharedMaterial(): Material {
-        return this.sharedMaterials[0];
+    get sharedMaterial(): SharedMaterial {
+        return this.sharedMaterials[0] as SharedMaterial;
     }
 
-    set sharedMaterial(mat: Material) {
+    set sharedMaterial(mat: SharedMaterial) {
         const cur = this.sharedMaterials[0];
         if (cur === mat) return;
         this.sharedMaterials[0] = mat;
@@ -314,12 +316,12 @@ export class Renderer extends Behaviour implements IRenderer {
     }
 
     /**@deprecated please use sharedMaterial */
-    get material(): Material {
-        return this.sharedMaterials[0];
+    get material(): SharedMaterial {
+        return this.sharedMaterials[0] as SharedMaterial;
     }
 
     /**@deprecated please use sharedMaterial */
-    set material(mat: Material) {
+    set material(mat: SharedMaterial) {
         this.sharedMaterial = mat;
     }
 
@@ -329,10 +331,10 @@ export class Renderer extends Behaviour implements IRenderer {
     private _probeAnchorLastFrame?: Object3D;
 
     // this is just available during deserialization
-    private set sharedMaterials(_val: Array<Material | null>) {
+    private set sharedMaterials(_val: Array<SharedMaterial | null>) {
         // TODO: elements in the array might be missing at the moment which leads to problems if an index is serialized
         if (!this._originalMaterials) {
-            this._originalMaterials = _val as Material[];
+            this._originalMaterials = _val as SharedMaterial[];
         }
         else if (_val) {
             let didWarn = false;

package/src/engine-components/web/ScrollFollow.ts

@@ -28,18 +28,36 @@ type ScrollFollowEvent = {
  * The ScrollFollow component allows you to link the scroll position of the page (or a specific element) to one or more target objects.  
  * This can be used to create scroll-based animations, audio playback, or other effects. For example you can link the scroll position to a timeline (PlayableDirector) to create scroll-based storytelling effects or to an Animator component to change the animation state based on scroll.
  * 
+ * Assign {@link target} objects to the component to have them updated based on the current scroll position (check the 'target' property for supported types).
+ * 
  * @link Example at https://scrollytelling-2-z23hmxby7c6x-u30ld.needle.run/
+ * @link Template at https://github.com/needle-engine/scrollytelling-template
+ * 
+ * ## How to use with an Animator
+ * 1. Create an Animator component and set up a float parameter named "scroll".
+ * 2. Create transitions between animation states based on the "scroll" parameter (e.g. from 0 to 1).
+ * 3. Add a ScrollFollow component to the same GameObject or another GameObject in the scene.
+ * 4. Assign the Animator component to the ScrollFollow's target property.
+ * 
+ * ## How to use with a PlayableDirector (timeline)
+ * 1. Create a PlayableDirector component and set up a timeline asset.
+ * 2. Add a ScrollFollow component to the same GameObject or another GameObject in the scene.
+ * 3. Assign the PlayableDirector component to the ScrollFollow's target property.
+ * 4. The timeline will now scrub based on the scroll position of the page.
  */
 export class ScrollFollow extends Behaviour {
 
     /**
-     * Target object(s) to follow the scroll position of the page. If null, the main camera is used.
+     * Target object(s) to follow the scroll position of the page.
      * 
      * Supported target types:
      * - PlayableDirector (timeline), the scroll position will be mapped to the timeline time
      * - Animator, the scroll position will be set to a float parameter named "scroll"
      * - Animation, the scroll position will be mapped to the animation time
      * - AudioSource, the scroll position will be mapped to the audio time
+     * - SplineWalker, the scroll position will be mapped to the position01 property
+     * - Light, the scroll position will be mapped to the intensity property
+     * - Object3D, the object will move vertically based on the scroll position
      * - Any object with a `scroll` property (number or function)
      */
     @serializable([Behaviour, Object3D])
@@ -204,6 +222,7 @@ export class ScrollFollow extends Behaviour {
             }
             const bounds = target["needle:scrollbounds"] as Box3;
             if (bounds) {
+                // TODO: remap position to use upper screen edge and lower edge instead of center
                 target.position.y = -bounds.min.y - value * (bounds.max.y - bounds.min.y);
             }
         }