@needle-tools/engine 3.37.3-alpha → 3.37.5-alpha

package/src/engine-components/ParticleSystem.ts

@@ -35,6 +35,7 @@ export enum SubEmitterType {
     Manual = 4,
 }
 
+/** @internal */
 export class ParticleSystemRenderer extends Behaviour {
 
     @serializable()
@@ -88,7 +89,7 @@ export class ParticleSystemRenderer extends Behaviour {
                     // don't modify the assigned material
                     material = material.clone();
                     material.side = BackSide;
-                    if(trailEnabled) this.trailMaterial = material;
+                    if (trailEnabled) this.trailMaterial = material;
                     else this.particleMaterial = material;
                 }
             }
@@ -642,6 +643,11 @@ class ParticlesEmissionState implements EmissionState {
     waitEmiting: number = 0;
 }
 
+/**
+ * The ParticleSystem component efficiently handles the rendering of particles.    
+ * 
+ * You can add custom behaviours to the particle system to fully customize the behaviour of the particles. See {@link ParticleSystemBaseBehaviour} and {@link ParticleSystem.addBehaviour} for more information.
+ */
 export class ParticleSystem extends Behaviour implements IParticleSystem {
 
     play(includeChildren: boolean = false) {
@@ -838,8 +844,23 @@ export class ParticleSystem extends Behaviour implements IParticleSystem {
         return this._isUsedAsSubsystem;
     }
 
-    /** Add a custom quarks behaviour to the particle system. You can add a quarks.Behaviour type.
-     * @link https://github.com/Alchemist0823/three.quarks
+    /** Add a custom quarks behaviour to the particle system.   
+     * You can add a quarks.Behaviour type or derive from {@link ParticleSystemBaseBehaviour}  
+     * @link https://github.com/Alchemist0823/three.quarks    
+     * @example
+     * ```typescript
+     * class MyBehaviour extends ParticleSystemBaseBehaviour {
+     *    initialize(particle: Particle) {
+     *       // initialize the particle
+     *   }
+     *    update(particle: Particle, delta: number) {  
+     *        // do something with the particle
+     *   }
+     * }
+     * 
+     * const system = gameObject.getComponent(ParticleSystem);
+     * system.addBehaviour(new MyBehaviour());
+     * ```
     */
     addBehaviour(particleSystemBehaviour: Behavior | ParticleSystemBaseBehaviour): boolean {
         if (!this._particleSystem) {
@@ -852,6 +873,19 @@ export class ParticleSystem extends Behaviour implements IParticleSystem {
         this._particleSystem.addBehavior(particleSystemBehaviour);
         return true;
     }
+    /** Remove a custom quarks behaviour from the particle system. **/
+    removeBehaviour(particleSystemBehaviour: Behavior | ParticleSystemBaseBehaviour): boolean {
+        if (!this._particleSystem) {
+            return false;
+        }
+        const behaviours = this._particleSystem.behaviors;
+        const index = behaviours.indexOf(particleSystemBehaviour);
+        if (index !== -1) {
+            behaviours.splice(index, 1);
+            return true;
+        }
+        return true;
+    }
     /** Removes all behaviours from the particle system  
      * **Note:** this will also remove the default behaviours like SizeBehaviour, ColorBehaviour etc.
      */
@@ -919,6 +953,7 @@ export class ParticleSystem extends Behaviour implements IParticleSystem {
     }
     private _subEmitterSystems?: SubEmitterSystem[];
 
+    /** @internal */
     onAfterDeserialize(_) {
         // doing this here to get a chance to resolve the subemitter guid
         if (this._subEmitterSystems && Array.isArray(this._subEmitterSystems)) {
@@ -928,6 +963,7 @@ export class ParticleSystem extends Behaviour implements IParticleSystem {
         }
     }
 
+    /** @internal */
     awake(): void {
         this._worldPositionFrame = -1;
 
@@ -976,11 +1012,13 @@ export class ParticleSystem extends Behaviour implements IParticleSystem {
         }
     }
 
+    /** @internal */
     start() {
         this.addSubParticleSystems();
         this.updateLayers();
     }
 
+    /** @internal */
     onDestroy(): void {
         this._container?.removeFromParent();
         this._batchSystem?.removeFromParent();
@@ -988,6 +1026,7 @@ export class ParticleSystem extends Behaviour implements IParticleSystem {
         this._particleSystem?.dispose();
     }
 
+    /** @internal */
     onEnable() {
         if (!this.main) return;
         if (this.inheritVelocity)
@@ -1004,6 +1043,7 @@ export class ParticleSystem extends Behaviour implements IParticleSystem {
             this._batchSystem.visible = false;
     }
 
+    /** @internal */
     onBeforeRender() {
         if (!this.main) return;
         if (this._didPreWarm === false && this.main?.prewarm === true) {
@@ -1143,7 +1183,7 @@ export class ParticleSystem extends Behaviour implements IParticleSystem {
 }
 
 
-
+/** @internal */
 export class SubEmitterSystem {
 
     particleSystem?: ParticleSystem;

package/src/engine-components/RigidBody.ts

@@ -167,8 +167,11 @@ export class Rigidbody extends Behaviour implements IRigidbody {
     @serializable()
     useGravity: boolean = true;
 
-    @serializable()
-    centerOfMass: Vector3 = new Vector3();
+    /**
+     * The center of mass is the point around which the mass of the rigid-body is evenly distributed. It is used to compute the torque applied to the rigid-body when forces are applied to it.
+     */
+    @serializable(Vector3)
+    centerOfMass: Vector3 = new Vector3(0, 0, 0);
 
     /**
      * Constraints are used to lock the position or rotation of an object in a specific axis.

package/src/engine-components/SceneSwitcher.ts

@@ -43,7 +43,23 @@ export type LoadSceneEvent = {
     index: number;
 }
 
-/** The ISceneEventListener is called by the SceneSwitcher when a scene is loaded or unloaded. It must be added to the root object of your scene */
+/** 
+ * The ISceneEventListener is called by the {@link SceneSwitcher} when a scene is loaded or unloaded.   
+ * It must be added to the root object of your scene (that is being loaded) or on the same object as the SceneSwitcher  
+ * It can be used to e.g. smooth the transition between scenes or to load additional content when a scene is loaded.  
+ * @example 
+ * ```ts
+ * import { ISceneEventListener } from "@needle-tools/engine";
+ * 
+ * // Add this component to the root object of a scene loaded by a SceneSwitcher or to the same object as the SceneSwitcher
+ * export class MySceneListener implements ISceneEventListener {
+ *   async sceneOpened(sceneSwitcher: SceneSwitcher) {
+ *    console.log("Scene opened", sceneSwitcher.currentlyLoadedScene?.uri); 
+ *  }
+ * }
+ * ```
+ * 
+ **/
 export interface ISceneEventListener {
     /** Called when the scene is loaded and added */
     sceneOpened?(sceneSwitcher: SceneSwitcher): Promise<void>
@@ -60,6 +76,9 @@ export interface ISceneEventListener {
  * - [Needle Website](https://needle.tools)
  * - [Songs Of Cultures](https://app.songsofcultures.com)
  * 
+ * ### Interfaces
+ * Use the {@link ISceneEventListener} interface to listen to scene open and closing events with the ability to modify transitions and stall the scene loading process.
+ * 
  * ### Events
  * - `loadscene-start`: Called when a scene starts loading
  * - `loadscene-finished`: Called when a scene finished loading
@@ -438,7 +457,8 @@ export class SceneSwitcher extends Behaviour {
     }
 
     private _currentlyLoadingScene?: AssetReference;
-    async __internalSwitchScene(scene: AssetReference): Promise<boolean> {
+    /** @internal */
+    private async __internalSwitchScene(scene: AssetReference): Promise<boolean> {
 
         if (this._currentScene) {
             if (debug) console.log("UNLOAD", scene.uri)
@@ -591,15 +611,25 @@ export class SceneSwitcher extends Behaviour {
             await this._loadingScenePromise;
             if (this._isCurrentlyLoading && this.loadingScene?.asset) {
                 if (debug) console.log("Add loading scene", this.loadingScene.uri, this.loadingScene.asset)
-                const obj = this.loadingScene.asset as any as Object3D;
-                GameObject.add(obj, this.gameObject);
-                const sceneListener = this.tryGetSceneEventListener(obj);
+                const loadingScene = this.loadingScene.asset as any as Object3D;
+                GameObject.add(loadingScene, this.gameObject);
+                const sceneListener = this.tryGetSceneEventListener(loadingScene);
                 if (sceneListener?.sceneOpened) {
                     const res = sceneListener.sceneOpened(this);
                     if (res instanceof Promise) await res;
                 }
             }
         }
+        // Invoke the event on a loading listener on the same object as the scene switcher
+        if (this._isCurrentlyLoading) {
+            const listener = this.tryGetSceneEventListener(this.gameObject);
+            if (listener) {
+                if (listener.sceneOpened) {
+                    const res = listener.sceneOpened(this);
+                    if (res instanceof Promise) await res;
+                }
+            }
+        }
     }
     private async onEndLoading() {
         this._isCurrentlyLoading = false;
@@ -614,6 +644,16 @@ export class SceneSwitcher extends Behaviour {
             }
             GameObject.remove(obj);
         }
+        // Invoke the event on a loading listener on the same object as the scene switcher
+        if (!this._isCurrentlyLoading) {
+            const listener = this.tryGetSceneEventListener(this.gameObject);
+            if (listener) {
+                if (listener.sceneClosing) {
+                    const res = listener.sceneClosing();
+                    if (res instanceof Promise) await res;
+                }
+            }
+        }
     }
 
     private tryGetSceneEventListener(obj: Object3D, level: number = 0): ISceneEventListener | null {

package/src/engine-components/SyncedTransform.ts

@@ -282,22 +282,14 @@ export class SyncedTransform extends Behaviour {
         this.lastWorldRotation.copy(wr);
 
 
-        // if (this._model.isOwned === false && this.autoOwnership) {
-        //     this.requestOwnership();
-        // }
-
         if (!this._model) return;
-        // only run if we are the owner
+        
         if (!this._model || this._model.hasOwnership === undefined || !this._model.hasOwnership) {
-            if (this.rb) {
-                this.rb.isKinematic = this._model.isOwned ?? false;
-                this.rb.setVelocity(0, 0, 0);
-            }
+            // if we're not the owner of this synced transform then don't send any data
             return;
         }
 
         // local user is owner:
-
         if (this.rb) {
             if (this._wasKinematic !== undefined) {
                 if (debug)
@@ -305,13 +297,8 @@ export class SyncedTransform extends Behaviour {
                 this.rb.isKinematic = this._wasKinematic;
             }
 
-            // hacky reset if too far off
-            if (this.gameObject.position.distanceTo(new Vector3(0, 0, 0)) > 1000) {
-                if (debug)
-                    console.log("RESET", this.name)
-                this.gameObject.position.set(0, 1, 0);
-                this.rb.setVelocity(0, 0, 0);
-            }
+            // TODO: if the SyncedTransform has a dynamic rigidbody we should probably synchronize the Rigidbody's properties (velocity etc)
+            // Or the Rigidbody should be synchronized separately in which case the SyncedTransform should be passive
         }
 
         const updateInterval = 10;