@needle-tools/engine 4.4.0-ci.1 → 4.4.2

package/lib/engine/engine_context.js

@@ -229,26 +229,43 @@ export class Context {
             return window.innerHeight;
         return this.domElement.clientHeight;
     }
-    /** the X position of the Needle Engine element on the website */
+    /** the X position of the `<needle-engine>` element on the website */
     get domX() {
         this.calculateBoundingClientRect();
         return this._domX;
     }
-    /** the Y position of the Needlee Engine element on the website */
+    /** the Y position of the `<needle-engine>` element on the website */
     get domY() {
         this.calculateBoundingClientRect();
         return this._domY;
     }
+    /**
+     * Is a XR session currently active and presenting?
+     * @returns true if the xr renderer is currently presenting
+     */
     get isInXR() { return this.renderer?.xr?.isPresenting || false; }
     /** shorthand for `NeedleXRSession.active`
      * Automatically set by NeedleXRSession when a XR session is active
      * @returns the active XR session or null if no session is active
      * */
     xr = null;
+    /**
+     * Shorthand for `this.xr?.mode`. AR or VR
+     * @returns the current XR session mode (immersive-vr or immersive-ar)
+     */
     get xrSessionMode() { return this.xr?.mode; }
+    /** Shorthand for `this.xrSessionMode === "immersive-vr"`
+     * @returns true if a webxr VR session is currently active.
+     */
     get isInVR() { return this.xrSessionMode === "immersive-vr"; }
+    /**
+     * Shorthand for `this.xrSessionMode === "immersive-ar"`
+     * @returns true if a webxr AR session is currently active.
+     */
     get isInAR() { return this.xrSessionMode === "immersive-ar"; }
-    /** If a XR session is active and in pass through mode (immersive-ar on e.g. Quest) */
+    /** If a XR session is active and in pass through mode (immersive-ar on e.g. Quest)
+     * @returns true if the XR session is in pass through mode
+     */
     get isInPassThrough() { return this.xr ? this.xr.isPassThrough : false; }
     /** access the raw `XRSession` object (shorthand for `context.renderer.xr.getSession()`). For more control use `NeedleXRSession.active` */
     get xrSession() { return this.renderer?.xr?.getSession(); }
@@ -259,32 +276,77 @@ export class Context {
     /** @returns the current WebXR camera while the WebXRManager is active (shorthand for `context.renderer.xr.getCamera()`) */
     get xrCamera() { return this.renderer.xr.isPresenting ? this.renderer?.xr?.getCamera() : undefined; }
     _xrFrame = null;
+    /**
+     * The AR overlay element is used to display 2D HTML elements while a AR session is active.
+     */
     get arOverlayElement() {
         const el = this.domElement;
         if (typeof el.getAROverlayContainer === "function")
             return el.getAROverlayContainer();
         return this.domElement;
     }
-    /** Current event of the update cycle */
+    /**
+     * Current event of the update cycle (e.g. `FrameEvent.EarlyUpdate` or `FrameEvent.OnBeforeRender`)
+     */
     get currentFrameEvent() {
         return this._currentFrameEvent;
     }
     _currentFrameEvent = FrameEvent.Undefined;
+    /**
+     * The scene contains all objects in the hierarchy and is automatically rendered by the context every frane.
+     */
     scene;
+    /**
+     * The renderer is used to render the scene. It is automatically created when the context is created.
+     */
     renderer;
+    /**
+     * The effect composer can be used to render postprocessing effects. If assigned then it will automatically render the scene every frame.
+     */
     composer = null;
-    // all scripts
+    /**
+     * @internal All known components. Don't use directly
+     */
     scripts = [];
+    /**
+     * @internal All paused components. Don't use directly
+     */
     scripts_pausedChanged = [];
-    // scripts with update event
+    /**
+     * @internal All components that have a early update event. Don't use directly
+     */
     scripts_earlyUpdate = [];
+    /**
+     * @internal All components that have a update event. Don't use directly
+     */
     scripts_update = [];
+    /**
+     * @internal All components that have a late update event. Don't use directly
+     */
     scripts_lateUpdate = [];
+    /**
+     * @internal All components that have a onBeforeRender event. Don't use directly
+     */
     scripts_onBeforeRender = [];
+    /**
+     * @internal All components that have a onAfterRender event. Don't use directly
+     */
     scripts_onAfterRender = [];
+    /**
+     * @internal All components that have coroutines. Don't use directly
+     */
     scripts_WithCorroutines = [];
+    /**
+     * @internal Components with immersive-vr event methods. Don't use directly
+     */
     scripts_immersive_vr = [];
+    /**
+     * @internal Components with immersive-ar event methods. Don't use directly
+     */
     scripts_immersive_ar = [];
+    /**
+     * @internal Coroutine data
+     */
     coroutines = {};
     /** callbacks called once after the context has been created */
     post_setup_callbacks = [];
@@ -296,14 +358,25 @@ export class Context {
     post_render_callbacks = [];
     /** called every frame befroe update (this list is emptied every frame) */
     pre_update_oneshot_callbacks = [];
+    /** @internal */
     new_scripts = [];
+    /** @internal */
     new_script_start = [];
+    /** @internal */
     new_scripts_pre_setup_callbacks = [];
+    /** @internal */
     new_scripts_post_setup_callbacks = [];
+    /** @internal */
     new_scripts_xr = [];
-    /** The main camera component of the scene - this camera is used for rendering */
+    /**
+     * The **main camera component** of the scene - this camera is used for rendering.
+     * Use `setCurrentCamera` for updating the main camera.
+     */
     mainCameraComponent = undefined;
-    /** The main camera of the scene - this camera is used for rendering */
+    /**
+     * The main camera of the scene - this camera is used for rendering
+     * Use `setCurrentCamera` for updating the main camera.
+     */
     get mainCamera() {
         if (this._mainCamera) {
             return this._mainCamera;
@@ -325,11 +398,13 @@ export class Context {
     }
     _mainCamera = null;
     _fallbackCamera = null;
+    /** access application state (e.g. if all audio should be muted) */
     application;
     /** access animation mixer used by components in the scene */
     animations;
     /** access timings (current frame number, deltaTime, timeScale, ...) */
     time;
+    /** access input data (e.g. click or touch events) */
     input;
     /** access physics related methods (e.g. raycasting). To access the phyiscs engine use `context.physics.engine` */
     physics;
@@ -339,6 +414,7 @@ export class Context {
      * @deprecated AssetDataBase is deprecated
      */
     assets;
+    /** The main light in the scene */
     mainLight = null;
     /** @deprecated Use sceneLighting */
     get rendererData() { return this.sceneLighting; }
@@ -347,9 +423,11 @@ export class Context {
     lightmaps;
     players;
     lodsManager;
+    /** Access the needle menu to add or remove buttons to the menu element */
     menu;
+    /** @returns true if the context is fully created and ready */
     get isCreated() { return this._isCreated; }
-    _sizeChanged = false;
+    _needsUpdateSize = false;
     _isCreated = false;
     _isCreating = false;
     _isVisible = false;
@@ -385,10 +463,10 @@ export class Context {
         this.menu = new NeedleMenu(this);
         this.lodsManager = new LODsManager(this);
         this.animations = new AnimationsRegistry(this);
-        const resizeCallback = () => this._sizeChanged = true;
+        const resizeCallback = () => this._needsUpdateSize = true;
         window.addEventListener('resize', resizeCallback);
         this._disposeCallbacks.push(() => window.removeEventListener('resize', resizeCallback));
-        const resizeObserver = new ResizeObserver(_ => this._sizeChanged = true);
+        const resizeObserver = new ResizeObserver(_ => this._needsUpdateSize = true);
         resizeObserver.observe(this.domElement);
         this._disposeCallbacks.push(() => resizeObserver.disconnect());
         this._intersectionObserver = new IntersectionObserver(entries => {
@@ -397,7 +475,12 @@ export class Context {
         this._disposeCallbacks.push(() => this._intersectionObserver?.disconnect());
         ContextRegistry.register(this);
     }
-    /** calling this function will dispose the current renderer and create a new one */
+    /**
+     * Calling this function will dispose the current renderer and create a new one which will then be assigned to the context. It can be used to create a new renderer with custom WebGLRendererParameters.
+     * **Note**: Instead you can also modify the static `Context.DefaultWebGlRendererParameters` before the context is created.
+     * **Note**: This method is recommended because it re-uses an potentially already existing canvas element. This is necessary to keep input event handlers from working (e.g. components like OrbitControls subscribe to input events on the canvas)
+     * @returns {WebGLRenderer} the newly created renderer
+     */
     createNewRenderer(params) {
         this.renderer?.dispose();
         params = { ...Context.DefaultWebGLRendererParameters, ...params };
@@ -435,6 +518,7 @@ export class Context {
         // this.renderer.toneMapping = AgXToneMapping;
         this.lodsManager.setRenderer(this.renderer);
         this.input.bindEvents();
+        return this.renderer;
     }
     _intersectionObserver = null;
     internalOnUpdateVisible() {
@@ -443,13 +527,29 @@ export class Context {
     }
     _disposeCallbacks = [];
     /** will request a renderer size update the next render call (will call updateSize the next update) */
-    requestSizeUpdate() { this._sizeChanged = true; }
+    requestSizeUpdate() { this._needsUpdateSize = true; }
     /** Clamps the renderer max resolution. If undefined the max resolution is not clamped. Default is undefined */
     maxRenderResolution;
-    /** update the renderer and canvas size */
+    /** Control the renderer devicePixelRatio.
+     * **Options**
+     * - `auto` - Needle Engine automatically sets the pixel ratio to the current window.devicePixelRatio.
+     * - `manual` - Needle Engine will not change the renderer pixel ratio. You can set it manually.
+     * - `number` - Needle Engine will set the pixel ratio to the given number. The change will be applied to the renderer and the composer (if used) at the end of the current frame.
+     */
+    get devicePixelRatio() { return this._devicePixelRatio; }
+    set devicePixelRatio(val) {
+        if (val !== this._devicePixelRatio) {
+            this._devicePixelRatio = val;
+            this._needsUpdateSize = true;
+        }
+    }
+    _devicePixelRatio = "auto";
+    /**
+     * Update the renderer and canvas size. This is also automatically called when a DOM size change is detected.
+     */
     updateSize(force = false) {
         if (force || (!this.isManagedExternally && this.renderer.xr?.isPresenting === false)) {
-            this._sizeChanged = false;
+            this._needsUpdateSize = false;
             const scaleFactor = this.resolutionScaleFactor;
             let width = this.domWidth * scaleFactor;
             let height = this.domHeight * scaleFactor;
@@ -462,19 +562,29 @@ export class Context {
             const camera = this.mainCamera;
             this.updateAspect(camera);
             this.renderer.setSize(width, height, true);
-            this.renderer.setPixelRatio(window.devicePixelRatio);
             // avoid setting pixel values here since this can cause pingpong updates
             // e.g. when system scale is set to 125%
             // https://github.com/needle-tools/needle-engine-support/issues/69
             this.renderer.domElement.style.width = "100%";
             this.renderer.domElement.style.height = "100%";
+            const devicePixelRatio = typeof this.devicePixelRatio === "number"
+                ? this.devicePixelRatio
+                : this.devicePixelRatio === "auto"
+                    ? window.devicePixelRatio
+                    : undefined;
+            if (devicePixelRatio !== undefined) {
+                this.renderer.setPixelRatio(devicePixelRatio);
+            }
             if (this.composer) {
                 this.composer.setSize?.call(this.composer, width, height);
-                if ("setPixelRatio" in this.composer && typeof this.composer.setPixelRatio === "function")
+                if (devicePixelRatio !== undefined && "setPixelRatio" in this.composer && typeof this.composer.setPixelRatio === "function")
                     this.composer.setPixelRatio?.call(this.composer, window.devicePixelRatio);
             }
         }
     }
+    /**
+     * Update the camera aspect ratio or orthorgraphic camera size. This is automatically called when a DOM size change is detected.
+     */
     updateAspect(camera, width, height) {
         if (!camera)
             return;
@@ -520,6 +630,7 @@ export class Context {
     async onCreate(opts) {
         return this.create(opts);
     }
+    /** @internal */
     async create(opts) {
         try {
             this._isCreating = true;
@@ -542,7 +653,11 @@ export class Context {
     onError(error) {
         this.domElement.dispatchEvent(new CustomEvent("error", { detail: error }));
     }
-    /** Will destroy all scenes and objects in the scene
+    /**
+     * Clears the context and destroys all scenes and objects in the scene.
+     * The ContextCleared event is called at the end.
+     * This is automatically called when e.g. the `src` attribute changes on `<needle-engine>`
+     * or when the web component is removed from the DOM
      */
     clear() {
         ContextRegistry.dispatchCallback(ContextEvent.ContextClearing, this);
@@ -566,6 +681,9 @@ export class Context {
         // if a user wants to see the background they can still call setClearAlpha(0) and clear manually
         ContextRegistry.dispatchCallback(ContextEvent.ContextCleared, this);
     }
+    /**
+     * Dispose all allocated resources and clears the scene. This is automatically called e.g. when the `<needle-engine>` component is removed from the DOM.
+     */
     dispose() {
         this.internalOnDestroy();
     }
@@ -611,6 +729,7 @@ export class Context {
             Context.Current = null;
         }
     }
+    /** @internal Automatically called by components when you call `startCoroutine`. Use `startCoroutine` instead  */
     registerCoroutineUpdate(script, coroutine, evt) {
         if (typeof coroutine?.next !== "function") {
             console.error("Registered invalid coroutine function from " + script.name + "\nCoroutine functions must be generators: \"*myCoroutine() {...}\"\nStart a coroutine from a component by calling \"this.startCoroutine(myCoroutine())\"");
@@ -621,6 +740,7 @@ export class Context {
         this.coroutines[evt].push({ comp: script, main: coroutine });
         return coroutine;
     }
+    /** @internal Automatically called by components. */
     unregisterCoroutineUpdate(coroutine, evt) {
         if (!this.coroutines[evt])
             return;
@@ -628,6 +748,7 @@ export class Context {
         if (idx >= 0)
             this.coroutines[evt].splice(idx, 1);
     }
+    /** @internal Automatically called */
     stopAllCoroutinesFrom(script) {
         for (const evt in this.coroutines) {
             const rout = this.coroutines[evt];
@@ -640,6 +761,7 @@ export class Context {
         }
     }
     _cameraStack = [];
+    /** Change the main camera */
     setCurrentCamera(cam) {
         if (!cam)
             return;
@@ -659,6 +781,9 @@ export class Context {
             this.updateAspect(camera);
         this.mainCameraComponent?.applyClearFlagsIfIsActiveCamera();
     }
+    /**
+     * Remove the camera from the mainCamera stack (if it has been set before with `setCurrentCamera`)
+     */
     removeCamera(cam) {
         if (!cam)
             return;
@@ -675,7 +800,9 @@ export class Context {
     }
     _onBeforeRenderListeners = new Map();
     _onAfterRenderListeners = new Map();
-    /** use this to subscribe to onBeforeRender events on threejs objects */
+    /** Use to subscribe to onBeforeRender events on threejs objects.
+     * @link https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender
+     */
     addBeforeRenderListener(target, callback) {
         if (!this._onBeforeRenderListeners.has(target.uuid)) {
             this._onBeforeRenderListeners.set(target.uuid, []);
@@ -683,6 +810,9 @@ export class Context {
         }
         this._onBeforeRenderListeners.get(target.uuid).push(callback);
     }
+    /** Remove callback from three `onBeforeRender` event (if it has been added with `addBeforeRenderListener(...)`)
+     * @link https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender
+    */
     removeBeforeRenderListener(target, callback) {
         if (this._onBeforeRenderListeners.has(target.uuid)) {
             const arr = this._onBeforeRenderListeners.get(target.uuid);
@@ -691,7 +821,10 @@ export class Context {
                 arr.splice(idx, 1);
         }
     }
-    /** use this to subscribe to onAfterRender events on threejs objects */
+    /**
+     * Subscribe to onAfterRender events on threejs objects
+     * @link https://threejs.org/docs/#api/en/core/Object3D.onAfterRender
+    */
     addAfterRenderListener(target, callback) {
         if (!this._onAfterRenderListeners.has(target.uuid)) {
             this._onAfterRenderListeners.set(target.uuid, []);
@@ -699,6 +832,10 @@ export class Context {
         }
         this._onAfterRenderListeners.get(target.uuid)?.push(callback);
     }
+    /**
+     * Remove from onAfterRender events on threejs objects
+     * @link https://threejs.org/docs/#api/en/core/Object3D.onAfterRender
+    */
     removeAfterRenderListener(target, callback) {
         if (this._onAfterRenderListeners.has(target.uuid)) {
             const arr = this._onAfterRenderListeners.get(target.uuid);
@@ -722,6 +859,7 @@ export class Context {
     _requireColorTexture = false;
     _renderTarget;
     _isRendering = false;
+    /** @returns true while the WebGL renderer is rendering (between onBeforeRender and onAfterRender events) */
     get isRendering() { return this._isRendering; }
     setRequireDepth(val) {
         this._requireDepthTexture = val;
@@ -735,7 +873,7 @@ export class Context {
     get opaqueColorTexture() {
         return this._renderTarget?.texture || null;
     }
-    /** returns true if the dom element is visible on screen */
+    /** @returns true if the `<needle-engine>` DOM element is visible on screen (`context.domElement`) */
     get isVisibleToUser() {
         if (this.isInXR)
             return true;
@@ -907,7 +1045,7 @@ export class Context {
             // this.composer.addPass(renderPass);
             // this.composer.setSize(this.domWidth, this.domHeight);
         }
-        this._sizeChanged = true;
+        this._needsUpdateSize = true;
         if (this._stats) {
             this._stats.showPanel(0);
             this._stats.dom.style.position = "absolute"; // (default is fixed)
@@ -1074,11 +1212,11 @@ export class Context {
             frame = null;
         if (isDevEnvironment() || debug || looputils.hasNewScripts()) {
             try {
-                performance.mark('update.start');
+                //performance.mark('update.start');
                 this.internalStep(timestamp, frame);
                 this._renderlooperrors = 0;
-                performance.mark('update.end');
-                performance.measure('NE Frame', 'update.start', 'update.end');
+                //performance.mark('update.end');
+                //performance.measure('NE Frame', 'update.start', 'update.end');
             }
             catch (err) {
                 this._renderlooperrors += 1;
@@ -1230,7 +1368,7 @@ export class Context {
             }
             this.executeCoroutines(FrameEvent.OnBeforeRender);
             invokeLifecycleFunctions(this, FrameEvent.OnBeforeRender);
-            if (this._sizeChanged)
+            if (this._needsUpdateSize)
                 this.updateSize();
             if (this.pre_render_callbacks) {
                 for (const i in this.pre_render_callbacks) {