Needle Engine 3.39.0-alpha

Files changed (14) hide show

src/engine/debug/debug_console.ts +1 -0
src/engine/debug/debug_overlay.ts +1 -0
src/engine/engine_gizmos.ts +10 -3
src/engine/engine_license.ts +1 -0
src/engine/engine_lods.ts +19 -8
src/engine/engine_math.ts +24 -0
src/engine/engine_scenelighting.ts +7 -1
src/engine/engine_shims.ts +4 -0
src/engine/engine_texture.ts +3 -0
src/engine/engine_three_utils.ts +12 -2
src/engine/engine_time.ts +8 -0
src/engine/engine_utils.ts +39 -13
src/engine-components/OrbitControls.ts +11 -5
src/engine-components/webxr/WebXRImageTracking.ts +8 -4

src/engine/debug/debug_console.ts CHANGED Viewed

@@ -180,6 +180,7 @@
                     text-align: center;
                     background: #ffffff5c;
                     backdrop-filter: blur(16px);
+                    -webkit-backdrop-filter: blur(16px);
                     user-select: none;
                     pointer-events: auto;
                     transition: transform .2s ease-in-out;

src/engine/debug/debug_overlay.ts CHANGED Viewed

@@ -297,6 +297,7 @@
     element.style.maxWidth = "250px";
     element.style.whiteSpace = "pre-wrap";
     element.style["backdrop-filter"] = "blur(10px)";
+    element.style["-webkit-backdrop-filter"] = "blur(10px)";
     element.style.backgroundColor = "rgba(20,20,20,.8)";
     element.style.boxShadow = "inset 0 0 80px rgba(0,0,0,.2), 0 0 5px rgba(0,0,0,.2)";
     element.style.border = "1px solid rgba(160,160,160,.2)";

src/engine/engine_gizmos.ts CHANGED Viewed

@@ -1,9 +1,9 @@
-import { AxesHelper, Box3, BoxGeometry, BufferAttribute, BufferGeometry, Color, type ColorRepresentation, CylinderGeometry, EdgesGeometry, Line, LineBasicMaterial, LineSegments, Matrix4, Mesh, MeshBasicMaterial,Object3D, Quaternion, SphereGeometry, Vector3 } from 'three';
+import { AxesHelper, Box3, BoxGeometry, BufferAttribute, BufferGeometry, Color, type ColorRepresentation, CylinderGeometry, EdgesGeometry, Line, LineBasicMaterial, LineSegments, Matrix4, Mesh, MeshBasicMaterial, Object3D, Quaternion, SphereGeometry, Vector3 } from 'three';
 import ThreeMeshUI, { Inline, Text } from "three-mesh-ui"
 import { type Options } from 'three-mesh-ui/build/types/core/elements/MeshUIBaseElement.js';
 import { isDestroyed } from './engine_gameobject.js';
-import { Context } from './engine_setup.js';
+import { Context, FrameEvent } from './engine_setup.js';
 import { getWorldPosition, lookAtObject, setWorldPositionXYZ } from './engine_three_utils.js';
 import type { Vec3, Vec4 } from './engine_types.js';
 import { getParam } from './engine_utils.js';
@@ -380,7 +380,14 @@
         object.renderOrder = 999999;
         object[$cacheSymbol] = cache;
         this.timedObjectsBuffer.push(object);
-        this.timesBuffer.push(Context.Current.time.realtimeSinceStartup + duration);
+        // Ensure if duration is 0 it is rendered for one frame only
+        if (duration <= 0 && context.currentFrameEvent >= FrameEvent.OnBeforeRender) {
+            this.timesBuffer.push(0);
+        }
+        else {
+            this.timesBuffer.push(Context.Current.time.realtimeSinceStartup + duration);
+        }
         context.scene.add(object);
     }

src/engine/engine_license.ts CHANGED Viewed

@@ -109,6 +109,7 @@
         zIndex: 2147483647;
         line-height: 1.5;
         backdrop-filter: blur(15px);
+        -webkit-backdrop-filter: blur(15px);
         `;
         const expectedStyle = div.style.cssText;

src/engine/engine_lods.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import { LODsManager as _LODsManager, NEEDLE_progressive, NEEDLE_progressive_mesh_model, NEEDLE_progressive_plugin } from "@needle-tools/gltf-progressive";
+import { LOD_Results } from "@needle-tools/gltf-progressive/src/lods_manager.js";
 import { Box3, BufferGeometry, Camera, Mesh, PerspectiveCamera, Scene, Sphere, Vector3, WebGLRenderer } from "three";
 import { findResourceUsers } from "./engine_assetdatabase.js";
@@ -14,13 +15,23 @@
 const _tempSphere: Sphere = new Sphere();
 /**
- * Needle Engine LODs manager. Wrapper around the internal LODs manager.
+ * Needle Engine LODs manager. Wrapper around the internal LODs manager.
+ * It uses the @needle-tools/gltf-progressive package to manage LODs.
+ * @link https://npmjs.com/package/@needle-tools/gltf-progressive
  */
 export class LODsManager implements NEEDLE_progressive_plugin {
     readonly context: Context;
     private _lodsManager?: _LODsManager;
     /**
+     * The internal LODs manager. See @needle-tools/gltf-progressive for more information.
+     * @link https://npmjs.com/package/@needle-tools/gltf-progressive
+     */
+    get manager() {
+        return this._lodsManager;
+    }
+    /**
      * The target triangle density is the desired max amount of triangles on screen when the mesh is filling the screen.
      * @default 200_000
      */
@@ -50,20 +61,21 @@
     /** @internal */
-    onAfterUpdatedLOD(_renderer: WebGLRenderer, _scene: Scene, camera: Camera, mesh: Mesh, level: number): void {
+    onAfterUpdatedLOD(_renderer: WebGLRenderer, _scene: Scene, camera: Camera, mesh: Mesh, level: LOD_Results): void {
         if (debug) this.onRenderDebug(camera, mesh, level);
     }
-    private onRenderDebug(camera: Camera, mesh: Mesh, level: number) {
+    private onRenderDebug(camera: Camera, mesh: Mesh, results: LOD_Results) {
         if (!mesh.geometry) return;
-        if (!NEEDLE_progressive.hasLODLevelAvailable(mesh.geometry)) return;
+        if (!NEEDLE_progressive.hasLODLevelAvailable(mesh.geometry) && !NEEDLE_progressive.hasLODLevelAvailable(mesh.material)) return;
         const state = _LODsManager.getObjectLODState(mesh);
         if (!state) return;
-        const changed = level != state.lastLodLevel;;
+        let level = results.mesh_lod;
+        const changed = results.mesh_lod != state.lastLodLevel_Mesh || results.texture_lod != state.lasLodLevel_Texture;
         if (debug && mesh.geometry.boundingSphere) {
             const bounds = mesh.geometry.boundingSphere;
@@ -105,7 +117,7 @@
                 // Area is squared, so both maxBoxSize and wsMedian are squared here
                 // Here, we're basically reverting the calculations that have happened in the pipeline for debugging.
                 // const surfaceArea = 1 / density * triangleCount * (maxBoxSize * maxBoxSize) * (wsMedian * wsMedian);
-                let text = "LOD " + level;
+                let text = "LOD " + results.mesh_lod + "\nTEX " + results.texture_lod;
                 if (debug == "density") {
                     text +=
                         "\n" + triangleCount + " tris" +
@@ -141,8 +153,7 @@
                 // const size = Math.min(10, radius);
                 const windowScale = this.context.domHeight > 0 ? screen.height / this.context.domHeight : 1;
                 const fieldOfViewScale = (camera as PerspectiveCamera).isPerspectiveCamera ? Math.tan((camera as PerspectiveCamera).fov * Math.PI / 180 / 2) : 1;
-                Gizmos.DrawLabel(pos, text, distance * .01 * windowScale * fieldOfViewScale, undefined, 0xffffff, col);
-                // mesh["LOD_level_label"] = helper;
+                Gizmos.DrawLabel(pos, text, distance * .012 * windowScale * fieldOfViewScale, undefined, 0xffffff, col);
             }
         }

src/engine/engine_math.ts CHANGED Viewed

@@ -148,13 +148,37 @@
     }
 }
+/**
+ * OneEuroFilter is a simple low-pass filter for noisy signals. It uses a one-euro filter to smooth the signal.
+ */
 export class OneEuroFilter {
+    /**
+     * An estimate of the frequency in Hz of the signal (> 0), if timestamps are not available.
+     */
     freq: number;
+    /**
+     * Min cutoff frequency in Hz (> 0). Lower values allow to remove more jitter.
+     */
     minCutOff: number;
+    /**
+     * Parameter to reduce latency (> 0). Higher values make the filter react faster to changes.
+     */
     beta: number;
+    /**
+     * Used to filter the derivates. 1 Hz by default. Change this parameter if you know what you are doing.
+     */
     dCutOff: number;
+    /**
+     * The low-pass filter for the signal.
+     */
     x: LowPassFilter;
+    /**
+     * The low-pass filter for the derivates.
+     */
     dx: LowPassFilter;
+    /**
+     * The last time the filter was called.
+     */
     lasttime: number | null;
     /** Create a new OneEuroFilter

src/engine/engine_scenelighting.ts CHANGED Viewed

@@ -10,13 +10,14 @@
 const debug = getParam("debugenvlight");
+/** @internal */
 export declare type SphericalHarmonicsData = {
     array: number[],
     texture: WebGLCubeRenderTarget | Texture,
     lightProbe?: LightProbe
 }
+/** @internal */
 export enum AmbientMode {
     Skybox = 0,
     Trilight = 1,
@@ -24,11 +25,16 @@
     Custom = 4,
 }
+/** @internal */
 export enum DefaultReflectionMode {
     Skybox = 0,
     Custom = 1,
 }
+/**
+ * The RendererData class is used to manage the lighting settings of a scene.
+ * It is created and used within the Needle Engine Context.
+ */
 export class RendererData {
     private context: Context;

src/engine/engine_shims.ts CHANGED Viewed

@@ -1,5 +1,9 @@
 // REMOVE once we switch to TypeScript 5.x
 // OffscreenCanvas has a convertToBlob method, but TypeScript 4.x doesn't have the proper types for it.
+/** @internal */
 export declare type OffscreenCanvasExt = OffscreenCanvas & {
 	convertToBlob: (options?: any) => Promise<Blob>;
 }

src/engine/engine_texture.ts CHANGED Viewed

@@ -23,6 +23,9 @@
     /**
      * Render the scene to the texture
+     * @param scene The scene to render
+     * @param camera The camera to render from
+     * @param renderer The renderer or effectcomposer to use
      */
     render(scene: Object3D, camera: Camera, renderer: WebGLRenderer | EffectComposer) {
         if (renderer instanceof EffectComposer) {

src/engine/engine_three_utils.ts CHANGED Viewed

@@ -6,7 +6,9 @@
 import { Mathf } from "./engine_math.js"
 import { CircularBuffer } from "./engine_utils.js";
+/**
+ * Slerp between two vectors
+ */
 export function slerp(vec: Vector3, end: Vector3, t: number) {
     const len1 = vec.length();
     const len2 = end.length();
@@ -18,7 +20,6 @@
 const flipYQuat: Quaternion = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI);
 export function lookAtInverse(obj: Object3D, target: Vector3) {
     obj.lookAt(target);
     obj.quaternion.multiply(flipYQuat);
 }
@@ -76,6 +77,15 @@
  * @param y the y value
  * @param z the z value
  * @returns a temporary vector
+ *
+ * @example
+ * ``` javascript
+ * const vec = getTempVector(1, 2, 3);
+ * const vec2 = getTempVector(vec);
+ * const vec3 = getTempVector(new Vector3(1, 2, 3));
+ * const vec4 = getTempVector(new DOMPointReadOnly(1, 2, 3));
+ * const vec5 = getTempVector();
+ * ```
  */
 export function getTempVector(vecOrX?: Vector3 | number | DOMPointReadOnly, y?: number, z?: number) {
     const vec = _tempVecs.get();

src/engine/engine_time.ts CHANGED Viewed

@@ -7,6 +7,10 @@
 let timeScale = 1;
 if (typeof timescaleUrl === "number") timeScale = timescaleUrl;
+/**
+ * Time is a class that provides time-related information.
+ * It is created and used within the Needle Engine Context.
+ */
 export class Time implements ITime {
     /** The time in seconds since the start of Needle Engine. */
@@ -19,6 +23,7 @@
     private set deltaTime(value: number) { this._deltaTime = value; }
     private _deltaTime = 0;
+    /** The time in seconds it took to complete the last frame (Read Only). Timescale is not applied. */
     get deltaTimeUnscaled() { return this._deltaTimeUnscaled; }
     private _deltaTimeUnscaled = 0;
@@ -54,6 +59,9 @@
             this.timeScale = timeScale;
     }
+    /** Step the time. This is called automatically by the Needle Engine Context.
+     * @internal
+     */
     update() {
         this.deltaTime = this.clock.getDelta();
         // clamp delta time because if tab is not active clock.getDelta can get pretty big

src/engine/engine_utils.ts CHANGED Viewed

@@ -8,7 +8,10 @@
 import { type SourceIdentifier } from "./engine_types.js";
 // https://schneidenbach.gitbooks.io/typescript-cookbook/content/nameof-operator.html
+/** @internal */
 export const nameofFactory = <T>() => (name: keyof T) => name;
+/** @internal */
 export function nameof<T>(name: keyof T) {
     return nameofFactory<T>()(name);
 }
@@ -16,12 +19,28 @@
 type ParseNumber<T> = T extends `${infer U extends number}` ? U : never;
 export type EnumToPrimitiveUnion<T> = `${T & string}` | ParseNumber<`${T & number}`>;
+/** @internal */
 export function isDebugMode(): boolean {
     return getParam("debug") ? true : false;
 }
+/**
+ * The circular buffer class can be used to cache objects that don't need to be created every frame.
+ * This structure is used for e.g. Vector3 or Quaternion objects in the engine when calling `getTempVector3` or `getTempQuaternion`.
+ *
+ * @example Create a circular buffer that caches Vector3 objects. Max size is 10.
+ * ```typescript
+ * const buffer = new CircularBuffer(() => new Vector3(), 10);
+ * const vec = buffer.get();
+ * ```
+ *
+ * @example Create a circular buffer that caches Quaternion objects. Max size is 1000.
+ * ```typescript
+ * const buffer = new CircularBuffer(() => new Quaternion(), 1000);
+ * const quat = buffer.get();
+ * ```
+ */
 export class CircularBuffer<T> {
     private _factory: () => T;
     private _cache: T[] = [];
@@ -43,29 +62,36 @@
     }
 }
-let saveParams: boolean = false;
+let showHelp: Param<"help"> = false;
 const requestedParams: Array<string> = new Array();
 if (typeof window !== "undefined") {
     setTimeout(() => {
-        const debugHelp = getParam("debughelp");
-        if (saveParams) {
+        // const debugHelp = getParam("debughelp");
+        if (showHelp) {
             const params = {};
             const url = new URL(window.location.href);
-            const exampleUrlT = new URL(url);
-            exampleUrlT.searchParams.append("help", "");
-            const exampleUrl = url.toString().replace(/=$|=(?=&)/g, '');
+            const exampleUrl = new URL(url);
+            exampleUrl.searchParams.append("console", "");
+            const exampleUrlStr = exampleUrl.toString().replace(/=$|=(?=&)/g, '');
+            // Filter the params we're interested in
             for (const param of requestedParams) {
                 const url2 = new URL(url);
                 url2.searchParams.append(param, "");
+                // Save url with clean parameters (remove trailing = and empty parameters)
                 params[param] = url2.toString().replace(/=$|=(?=&)/g, '');
             }
-            console.log(
-                "🌵 ?help: Debug Options for Needle Engine.\n" +
+            console.log(
+                "🌵 ?help: Debug Options for Needle Engine.\n" +
                 "Append any of these parameters to the URL to enable specific debug options.\n" +
-                `Example: ${exampleUrl} will show an onscreen console window.`);
-            console.group("Available URL parameters:");
+                `Example: ${exampleUrlStr} will show an onscreen console window.`);
+            const postfix = showHelp === true ? "" : ` (containing "${showHelp}")`;
+            console.group("Available URL parameters:" + postfix);
             for (const key in params) {
+                // If ?help= is a string we only want to show the parameters that contain the string
+                if (typeof showHelp === "string") {
+                    if (!key.toLowerCase().includes(showHelp.toLowerCase())) continue;
+                }
                 console.groupCollapsed(key);
                 // Needs to be a separate log, otherwise Safari doesn't turn the next line into a URL:
                 console.log("Reload with this flag enabled:");
@@ -92,7 +118,7 @@
  * Returns the value if it exists e.g. ?message=hello
  */
 export function getParam<T extends string>(paramName: T): Param<T> {
-    if (saveParams && !requestedParams.includes(paramName))
+    if (showHelp && !requestedParams.includes(paramName))
         requestedParams.push(paramName);
     const urlParams = getUrlParams();
     if (urlParams.has(paramName)) {
@@ -106,7 +132,7 @@
     }
     return false;
 }
-saveParams = getParam("help") === true;
+showHelp = getParam("help");
 export function setParam(paramName: string, paramValue: string): void {
     const urlParams = getUrlParams();

src/engine-components/OrbitControls.ts CHANGED Viewed

@@ -242,14 +242,14 @@
     private _camera: Camera | null = null;
     private _syncedTransform?: SyncedTransform;
     private _didStart = false;
-    private _didSetTarget = false;
+    private _didSetTarget = 0;
     targetElement: HTMLElement | null = null;
     /** @internal */
     awake(): void {
         this._didStart = false;
-        this._didSetTarget = false;
+        this._didSetTarget = 0;
         this._startedListeningToKeyEvents = false;
     }
@@ -356,7 +356,7 @@
             if (!evt.hasRay) {
                 evt.intersections.push(...this.context.physics.raycast());
             }
             if (evt.intersections.length <= 0) {
                 const dt = this.context.time.time - this._lastTimeClickOnBackground;
                 this._lastTimeClickOnBackground = this.context.time.time;
@@ -508,8 +508,9 @@
     }
     private __handleSetTargetWhenBecomingActiveTheFirstTime() {
-        if (this._didSetTarget) return;
-        this._didSetTarget = true;
+        // we want to wait one frame so all matrixWorlds are updated
+        // otherwise raycasting will not work correctly
+        if (this._didSetTarget++ != 1) return;
         if (this.autoTarget) {
             const camGo = GameObject.getComponent(this.gameObject, Camera);
@@ -593,6 +594,11 @@
         }
         this._lookTargetEndPosition.copy(position);
+        if (debug) {
+            console.warn("OrbitControls: setLookTargetPosition", position, immediateOrDuration);
+            Gizmos.DrawWireSphere(this._lookTargetEndPosition, .2, 0xff0000, 2);
+        }
         if (immediateOrDuration === true) {
             this._controls.target.copy(this._lookTargetEndPosition);
         }

src/engine-components/webxr/WebXRImageTracking.ts CHANGED Viewed

@@ -41,9 +41,10 @@
     applyToObject(object: Object3D, t01: number | undefined = undefined) {
         this.ensureTransformData();
-        // check if position/_position or rotation/_rotation changed more than just a little bit
-        const haveChanged = object.position.distanceToSquared(this._position) > 0.05 || object.quaternion.angleTo(this._rotation) > 0.05;
-        if (t01 === undefined || t01 >= 1 || haveChanged) {
+        // check if position/_position or rotation/_rotation changed more than just a little bit and adjust smoothing accordingly
+        const changeAmount = object.position.distanceToSquared(this._position) / 0.05 + object.quaternion.angleTo(this._rotation) / 0.05;
+        if (t01) t01 *= Math.max(1, changeAmount);
+        if (t01 === undefined || t01 >= 1) {
             object.position.copy(this._position);
             object.quaternion.copy(this._rotation);
             // InstancingUtil.markDirty(object);
@@ -231,6 +232,9 @@
     @serializable(WebXRImageTrackingModel)
     trackedImages?: WebXRImageTrackingModel[];
+    /** Applies smoothing based on detected jitter to the tracked image. */
+    smooth: boolean = true;
     private readonly trackedImageIndexMap: Map<number, WebXRImageTrackingModel> = new Map();
     private static _imageElements: Map<string, ImageBitmap | null> = new Map();
@@ -481,7 +485,7 @@
                     xr.rig.gameObject.add(trackedData.object);
-                    image.applyToObject(trackedData.object);
+                    image.applyToObject(trackedData.object, this.smooth ? this.context.time.deltaTimeUnscaled * 3 : undefined);
                     if (!trackedData.object.activeSelf) {
                         GameObject.setActive(trackedData.object, true);
                     }