@needle-tools/engine 4.9.0 → 4.9.2

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

@@ -181,7 +181,7 @@ export class Animation extends Behaviour implements IAnimationComponent {
         }
     }
     get animations(): AnimationClip[] {
-        return this.gameObject.animations || this._tempAnimationsArray || [];
+        return this.gameObject?.animations || this._tempAnimationsArray || [];
     }
 
     private mixer: AnimationMixer | undefined = undefined;

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;
@@ -353,6 +355,10 @@ export class Renderer extends Behaviour implements IRenderer {
 
     //@ts-ignore
     get sharedMaterials(): SharedMaterialArray {
+
+        // @ts-ignore during deserialization code might access this property *before* the setter and then create an empty array
+        if(!this.__didAwake) return null;
+
         if (!this._sharedMaterials || !this._sharedMaterials.is(this)) {
             if (!this._originalMaterials) this._originalMaterials = [];
             this._sharedMaterials = new SharedMaterialArray(this, this._originalMaterials);

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);
             }
         }