Needle Engine 3.37.5-alpha

Files changed (3) hide show

src/engine-components/OrbitControls.ts +29 -11
src/engine-components/ParticleSystem.ts +44 -4
src/engine-components/SceneSwitcher.ts +45 -5

src/engine-components/OrbitControls.ts CHANGED Viewed

@@ -185,12 +185,14 @@
     targetElement: HTMLElement | null = null;
+    /** @internal */
     awake(): void {
         this._didStart = false;
         this._didSetTarget = false;
         this._startedListeningToKeyEvents = false;
     }
+    /** @internal */
     start() {
         this._didStart = true;
         this._eventSystem = EventSystem.get(this.context) ?? undefined;
@@ -200,11 +202,13 @@
         }
     }
+    /** @internal */
     onDestroy() {
         this._controls?.dispose();
         this._eventSystem?.removeEventListener(EventSystemEvents.AfterHandleInput, this._afterHandleInputFn!);
     }
+    /** @internal */
     onEnable() {
         this._enableTime = this.context.time.time;
         const cameraComponent = GameObject.getComponent(this.gameObject, Camera);
@@ -266,6 +270,7 @@
         // }
     }
+    /** @internal */
     onDisable() {
         if (this._camera?.cam) {
             setCameraController(this._camera.cam, this, false);
@@ -299,10 +304,16 @@
     }
+    /** @internal */
     onBeforeRender() {
         if (!this._controls) return;
-        if (this._cameraObject !== this.context.mainCamera) return;
+        if (this._cameraObject !== this.context.mainCamera) {
+            this._controls.enabled = false;
+            return;
+        }
+        this._controls.enabled = true;
         this.__handleSetTargetWhenBecomingActiveTheFirstTime();
         if (this.context.input.getPointerDown(1) || this.context.input.getPointerDown(2) || this.context.input.mouseWheelChanged || (this.context.input.getPointerPressed(0) && this.context.input.getPointerPositionDelta(0)?.length() || 0 > .1)) {
@@ -448,6 +459,7 @@
     /** Moves the camera to position smoothly.
      * @param position The position in local space of the controllerObject to move the camera to. If null the camera will stop lerping to the target.
+     * @param immediateOrDuration If true the camera will move immediately to the new position, otherwise it will lerp. If a number is passed in it will be used as the duration of the lerp.
     */
     public setCameraTargetPosition(position?: Object3D | Vector3 | null, immediateOrDuration: boolean | number = false) {
         if (!position) return;
@@ -477,8 +489,11 @@
         this._cameraLerpActive = false;
     }
-    /** Moves the camera look-at target to a position smoothly. */
-    public setLookTargetPosition(position: Object3D | Vector3 | null = null, immediateOrDuration: boolean = false) {
+    /** Moves the camera look-at target to a position smoothly.
+     * @param position The position in world space to move the camera target to. If null the camera will stop lerping to the target.
+     * @param immediateOrDuration If true the camera target will move immediately to the new position, otherwise it will lerp. If a number is passed in it will be used as the duration of the lerp.
+    */
+    public setLookTargetPosition(position: Object3D | Vector3 | null = null, immediateOrDuration: boolean | number = false) {
         if (!this._controls) return;
         if (!position) return
         if (position instanceof Object3D) {
@@ -506,7 +521,10 @@
         this._lookTargetLerpActive = false;
     }
-    /** Sets the look at target from an assigned lookAtConstraint source by index */
+    /** Sets the look at target from an assigned lookAtConstraint source by index
+     * @param index The index of the source to use
+     * @param t The interpolation factor between the current look at target and the new target
+    */
     private setLookTargetFromConstraint(index: number = 0, t: number = 1): boolean {
         if (!this._controls) return false;
         const sources = this.lookAtConstraint?.sources;
@@ -546,12 +564,12 @@
                 this.setLookTargetPosition(hit.point);
-                if (this.context.mainCamera) {
-                    const pos = getWorldPosition(this.context.mainCamera);
-                    const cameraTarget = pos.clone().sub(this.controls.target).add(this._lookTargetEndPosition);
-                    this._cameraObject?.parent?.worldToLocal(cameraTarget);
-                    this.setCameraTargetPosition(cameraTarget);
-                }
+                // if (this.context.mainCamera) {
+                //     const pos = getWorldPosition(this.context.mainCamera);
+                //     const cameraTarget = pos.clone().sub(this.controls.target).add(this._lookTargetEndPosition);
+                //     this._cameraObject?.parent?.worldToLocal(cameraTarget);
+                //     this.setCameraTargetPosition(cameraTarget);
+                // }
                 break;
             }
         }

src/engine-components/ParticleSystem.ts CHANGED Viewed

@@ -35,6 +35,7 @@
     Manual = 4,
 }
+/** @internal */
 export class ParticleSystemRenderer extends Behaviour {
     @serializable()
@@ -88,7 +89,7 @@
                     // 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 @@
     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 @@
         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 @@
         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 @@
     }
     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 @@
         }
     }
+    /** @internal */
     awake(): void {
         this._worldPositionFrame = -1;
@@ -976,11 +1012,13 @@
         }
     }
+    /** @internal */
     start() {
         this.addSubParticleSystems();
         this.updateLayers();
     }
+    /** @internal */
     onDestroy(): void {
         this._container?.removeFromParent();
         this._batchSystem?.removeFromParent();
@@ -988,6 +1026,7 @@
         this._particleSystem?.dispose();
     }
+    /** @internal */
     onEnable() {
         if (!this.main) return;
         if (this.inheritVelocity)
@@ -1004,6 +1043,7 @@
             this._batchSystem.visible = false;
     }
+    /** @internal */
     onBeforeRender() {
         if (!this.main) return;
         if (this._didPreWarm === false && this.main?.prewarm === true) {
@@ -1143,7 +1183,7 @@
 }
+/** @internal */
 export class SubEmitterSystem {
     particleSystem?: ParticleSystem;

src/engine-components/SceneSwitcher.ts CHANGED Viewed

@@ -43,7 +43,23 @@
     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 @@
  * - [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 @@
     }
     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 @@
             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 @@
             }
             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 {