Needle Engine 3.36.4-beta

Files changed (14) hide show

src/engine/engine_addressables.ts +36 -4
src/engine/engine_input.ts +5 -1
src/engine/engine_instancing.ts +3 -0
src/engine/engine_license.ts +4 -0
src/engine/engine_networking_instantiate.ts +2 -0
src/engine/engine_scenetools.ts +17 -0
src/engine/engine_shaders.ts +24 -0
src/engine/engine_texture.ts +3 -0
src/engine/engine_three_utils.ts +56 -7
src/engine/engine_types.ts +8 -1
src/engine/engine_util_decorator.ts +3 -2
src/engine/engine_utils.ts +3 -1
src/engine-components/OrbitControls.ts +7 -0
src/engine-components/SceneSwitcher.ts +70 -1

src/engine/engine_addressables.ts CHANGED Viewed

@@ -45,11 +45,17 @@
     }
-    findAssetReference(key: string): AssetReference | null {
-        return this._assetReferences[key] || null;
+    /**
+     * Find a registered AssetReference by its URL
+     */
+    findAssetReference(url: string): AssetReference | null {
+        return this._assetReferences[url] || null;
     }
-    /** @internal */
+    /**
+     * Register an asset reference
+     * @internal
+     */
     registerAssetReference(ref: AssetReference): AssetReference {
         if (!ref.uri) return ref;
         if (!this._assetReferences[ref.uri]) {
@@ -83,8 +89,32 @@
  */
 export class AssetReference {
+    /**
+     * Experimental!
+     * @internal
+     * Get an AssetReference for a URL to be easily loaded.
+     * AssetReferences are cached so calling this method multiple times with the same arguments will always return the same AssetReference.
+     * @param url The URL of the asset to load. The url can be relative or absolute.
+     * @param context The context to use for loading the asset
+     * @returns the AssetReference for the URL
+     */
+    static getOrCreateFromUrl(url: string, context?: Context): AssetReference {
+        if (!context) {
+            context = Context.Current;
+            if (!context)
+                throw new Error("Context is required when sourceId is a string. When you call this method from a component you can call it with \"getOrCreate(this, url)\" where \"this\" is the component.");
+        }
+        const addressables = context.addressables;
+        const existing = addressables.findAssetReference(url);
+        if (existing) return existing;
+        const ref = new AssetReference(url, context.hash);
+        addressables.registerAssetReference(ref);
+        return ref;
+    }
     /**
-     * Get an AssetReference for a URL to be easily loaded. AssetReferences are cached so calling this method multiple times with the same arguments will always return the same AssetReference.
+     * Get an AssetReference for a URL to be easily loaded.
+     * AssetReferences are cached so calling this method multiple times with the same arguments will always return the same AssetReference.
      */
     static getOrCreate(sourceId: SourceIdentifier | IComponent, url: string, context?: Context): AssetReference {
@@ -515,6 +545,7 @@
 }
+/** @internal */
 export class ImageReferenceSerializer extends TypeSerializer {
     constructor() {
         super([ImageReference], "ImageReferenceSerializer");
@@ -578,6 +609,7 @@
 }
+/** @internal */
 export class FileReferenceSerializer extends TypeSerializer {
     constructor() {
         super([FileReference], "FileReferenceSerializer");

src/engine/engine_input.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { Intersection,Matrix4, Object3D, Ray, Vector2, Vector3 } from 'three';
+import { Intersection, Matrix4, Object3D, Ray, Vector2, Vector3 } from 'three';
 import { showBalloonMessage, showBalloonWarning } from './debug/debug.js';
 import { Context } from './engine_setup.js';
@@ -207,6 +207,9 @@
     signal?: AbortSignal;
 }
+/**
+ * The input system is responsible for handling all input events like pointer events (mouse, touch, xr controllers) and keyboard events.
+ */
 export class Input implements IInput {
     /** This is a list of event listeners per event type (e.g. pointerdown, pointerup, keydown...). Each entry contains a priority and list of listeners.
@@ -649,6 +652,7 @@
         vec2.y = -((vec2.y - this.context.domY) / this.context.domHeight) * 2 + 1;
     }
+    /** @internal */
     constructor(context: Context) {
         this.context = context;
         this.context.post_render_callbacks.push(this.onEndOfFrame);

src/engine/engine_instancing.ts CHANGED Viewed

@@ -6,6 +6,9 @@
 export const $instancingRenderer = Symbol("instancingRenderer");
 export const $instancingAutoUpdateBounds = Symbol("instancingAutoUpdateBounds");
+/**
+ * Utility class for accessing instancing related properties
+ */
 export class InstancingUtil {
     /** Is this object rendered using a InstancedMesh */

src/engine/engine_license.ts CHANGED Viewed

@@ -10,6 +10,7 @@
 let NEEDLE_ENGINE_LICENSE_TYPE: string = "basic";
 if (debug) console.log("License Type: " + NEEDLE_ENGINE_LICENSE_TYPE)
+/** @internal */
 export function hasProLicense() {
     switch (NEEDLE_ENGINE_LICENSE_TYPE) {
         case "pro":
@@ -19,6 +20,7 @@
     return false;
 }
+/** @internal */
 export function hasIndieLicense() {
     switch (NEEDLE_ENGINE_LICENSE_TYPE) {
         case "indie":
@@ -27,11 +29,13 @@
     return false;
 }
+/** @internal */
 export function hasCommercialLicense() {
     return hasProLicense() || hasIndieLicense();
 }
 const _licenseCheckResultChangedCallbacks: ((result: boolean) => void)[] = [];
+/** @internal */
 export function onLicenseCheckResultChanged(cb: (result: boolean) => void) {
     if (hasProLicense() || hasIndieLicense())
         return cb(true);

src/engine/engine_networking_instantiate.ts CHANGED Viewed

@@ -151,6 +151,8 @@
 // when a file is instantiated via some server (e.g. via file drop) we also want to send the info where the file can be downloaded
 // doing it this route will ensure we have
+/** @internal */
 export class HostData {
     filename: string;
     hash: string;

src/engine/engine_scenetools.ts CHANGED Viewed

@@ -15,6 +15,7 @@
 import { NEEDLE_components } from "./extensions/NEEDLE_components.js";
+/** @internal */
 export class NeedleGltfLoader implements INeedleGltfLoader {
     createBuiltinComponents(context: Context, gltfId: string, gltf: any, seed: number | UIDProvider | null, extension?: NEEDLE_components | undefined) {
         return createBuiltinComponents(context, gltfId, gltf, seed, extension);
@@ -103,6 +104,13 @@
     return loader;
 }
+/** Load a gltf file from a url. This is the core method used by Needle Engine to load gltf files. All known extensions are registered here.
+ * @param context The current context
+ * @param data The gltf data as string or ArrayBuffer
+ * @param path The path to the gltf file
+ * @param seed The seed for generating unique ids
+ * @returns The loaded gltf object
+ */
 export async function parseSync(context: Context, data: string | ArrayBuffer, path: string, seed: number | UIDProvider | null): Promise<GLTF | undefined> {
     if (typeof path !== "string") {
         console.warn("Parse gltf binary without path, this might lead to errors in resolving extensions. Please provide the source path of the gltf/glb file", path, typeof path);
@@ -153,6 +161,15 @@
     });
 }
+/**
+ * Load a gltf file from a url. This is the core method used by Needle Engine to load gltf files. All known extensions are registered here.
+ * @param context The current context
+ * @param url The url to the gltf file
+ * @param sourceId The source id of the gltf file - this is usually the url
+ * @param seed The seed for generating unique ids
+ * @param prog A progress callback
+ * @returns The loaded gltf object
+ */
 export async function loadSync(context: Context, url: string, sourceId: string, seed: number | UIDProvider | null, prog?: (ProgressEvent) => void): Promise<GLTF | undefined> {
     // better to create new loaders every time
     // (maybe we can cache them...)

src/engine/engine_shaders.ts CHANGED Viewed

@@ -11,6 +11,12 @@
 white[0] = 255; white[1] = 255; white[2] = 255; white[3] = 255;
 export const whiteDefaultTexture = new DataTexture(white, 1, 1, RGBAFormat);
+/**
+ * Creates a new texture with a single color
+ * @param col Color to use
+ * @param size Size of the texture
+ * @returns A texture with the specified color
+ */
 export function createFlatTexture(col: RGBAColor | Color, size: number = 1) {
     const hasAlpha = "alpha" in col;
     const length = size * size;
@@ -31,6 +37,15 @@
     return tex;
 }
+/**
+ * Creates a new texture with three colors
+ * @param col0 First color
+ * @param col1 Second color
+ * @param col2 Third color
+ * @param width Width of the texture
+ * @param height Height of the texture
+ * @returns A texture with the specified colors
+ */
 export function createTrilightTexture<T extends Color>(col0: T, col1: T, col2: T, width: number = 1, height: number = 3) {
     const hasAlpha = false;// "alpha" in col0;
     const channels = 4;
@@ -62,11 +77,13 @@
     return tex;
 }
+/** @internal */
 export enum Stage {
     Vertex,
     Fragment,
 }
+/** @internal */
 export class UnityShaderStage {
     stage: Stage;
     code: string;
@@ -105,9 +122,11 @@
     }
 }
+/** @internal */
 export const lib = new ShaderLib();
+/** @internal */
 export function ToUnityMatrixArray(mat: Matrix4, buffer?: Array<Vector4>): Array<Vector4> {
     const arr = mat.elements;
     if (!buffer)
@@ -126,6 +145,8 @@
 const noAmbientLight: Array<number> = [];
 const copyBuffer: Array<number> = [];
+/** @internal */
 export function SetUnitySphericalHarmonics(obj: object, array?: number[]) {
     if (noAmbientLight.length === 0) {
@@ -147,6 +168,7 @@
     obj["unity_SHC"] = { value: new Vector4(array[24], array[25], array[26], 1) };
 }
+/** @internal */
 export class ShaderBundle {
     readonly vertexShader: string;
     readonly fragmentShader: string;
@@ -159,6 +181,7 @@
     }
 }
+/** @internal */
 export async function FindShaderTechniques(shaderData: SHADERDATA.ShaderData, id: number): Promise<ShaderBundle | null> {
     // console.log(shaderData);
     if (!shaderData) {
@@ -191,6 +214,7 @@
     return null;
 }
+/** @internal */
 async function loadShaderCode(shader: SHADERDATA.Shader) {
     const uri = shader.uri;
     if (!uri) return;

src/engine/engine_texture.ts CHANGED Viewed

@@ -21,6 +21,9 @@
  */
 export class RenderTexture extends WebGLRenderTarget {
+    /**
+     * Render the scene to the texture
+     */
     render(scene: Object3D, camera: Camera, renderer: WebGLRenderer | EffectComposer) {
         if (renderer instanceof EffectComposer) {
             if (!this["_unsupported_effectcomposer_warning"]) {

src/engine/engine_three_utils.ts CHANGED Viewed

@@ -1,5 +1,5 @@
-import { AnimationAction, Euler, Mesh,Object3D, PerspectiveCamera, PlaneGeometry, Quaternion, Scene, Texture, Uniform, Vector3 } from "three";
-import { ShaderMaterial,WebGLRenderer } from "three";
+import { AnimationAction, Euler, Mesh, Object3D, PerspectiveCamera, PlaneGeometry, Quaternion, Scene, Texture, Uniform, Vector3 } from "three";
+import { ShaderMaterial, WebGLRenderer } from "three";
 import { Mathf } from "./engine_math.js"
 import { CircularBuffer } from "./engine_utils.js";
@@ -13,6 +13,7 @@
 }
 const flipYQuat: Quaternion = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI);
 export function lookAtInverse(obj: Object3D, target: Vector3) {
     obj.lookAt(target);
@@ -50,6 +51,14 @@
 const _tempVecs = new CircularBuffer(() => new Vector3(), 100);
+/** Gets a temporary vector. If a vector is passed in it will be copied to the temporary vector
+ * Temporary vectors are cached and reused internally. Don't store them!
+ * @param vecOrX the vector to copy or the x value
+ * @param y the y value
+ * @param z the z value
+ * @returns a temporary vector
+ */
 export function getTempVector(vecOrX?: Vector3 | number | DOMPointReadOnly, y?: number, z?: number) {
     const vec = _tempVecs.get();
     if (vecOrX instanceof Vector3) vec.copy(vecOrX);
@@ -62,6 +71,13 @@
     return vec;
 }
 const _tempQuats = new CircularBuffer(() => new Quaternion(), 100);
+/**
+ * Gets a temporary quaternion. If a quaternion is passed in it will be copied to the temporary quaternion
+ * Temporary quaternions are cached and reused internally. Don't store them!
+ * @param value the quaternion to copy
+ * @returns a temporary quaternion
+ */
 export function getTempQuaternion(value?: Quaternion | DOMPointReadOnly) {
     const val = _tempQuats.get();
     if (value instanceof Quaternion) val.copy(value);
@@ -73,6 +89,13 @@
 const _worldPositions = new CircularBuffer(() => new Vector3(), 100);
 const _lastMatrixWorldUpdateKey = Symbol("lastMatrixWorldUpdateKey");
+/**
+ * Get the world position of an object
+ * @param obj the object to get the world position from
+ * @param vec a vector to store the result in. If not passed in a temporary vector will be used
+ * @param updateParents if true the parents will be updated before getting the world position
+ * @returns the world position
+ */
 export function getWorldPosition(obj: Object3D, vec: Vector3 | null = null, updateParents: boolean = true): Vector3 {
     const wp = vec ?? _worldPositions.get();
     if (!obj) return wp.set(0, 0, 0);
@@ -87,20 +110,34 @@
     return wp;
 }
-export function setWorldPosition(obj: Object3D, val: Vector3) {
-    if (!obj) return;
+/**
+ * Set the world position of an object
+ * @param obj the object to set the world position of
+ * @param val the world position to set
+ */
+export function setWorldPosition(obj: Object3D, val: Vector3): Object3D {
+    if (!obj) return obj;
     const wp = _worldPositions.get();
     if (val !== wp)
         wp.copy(val);
     const obj2 = obj?.parent ?? obj;
     obj2.worldToLocal(wp);
     obj.position.set(wp.x, wp.y, wp.z);
+    return obj;
 }
-export function setWorldPositionXYZ(obj: Object3D, x: number, y: number, z: number) {
+/**
+ * Set the world position of an object
+ * @param obj the object to set the world position of
+ * @param x the x position
+ * @param y the y position
+ * @param z the z position
+ */
+export function setWorldPositionXYZ(obj: Object3D, x: number, y: number, z: number): Object3D {
     const wp = _worldPositions.get();
     wp.set(x, y, z);
     setWorldPosition(obj, wp);
+    return obj;
 }
@@ -254,7 +291,7 @@
 export function getParentHierarchyPath(obj: Object3D): string {
     let path = obj?.name || "";
-    if(!obj) return path;
+    if (!obj) return path;
     let parent = obj.parent;
     while (parent) {
         path = parent.name + "/" + path;
@@ -278,6 +315,9 @@
+/**
+ * Utility class to perform various graphics operations like copying textures to canvas
+ */
 export class Graphics {
     private static planeGeometry = new PlaneGeometry(2, 2, 1, 1);
     private static renderer: WebGLRenderer | undefined = undefined;
@@ -300,6 +340,9 @@
     }`;
     private static blipMaterial: ShaderMaterial | undefined = undefined;
+    /**
+     * Create a blit material for copying textures
+     */
     static createBlitMaterial(fragment: string): ShaderMaterial {
         return new ShaderMaterial({
             uniforms: { map: new Uniform(null) },
@@ -309,7 +352,13 @@
     }
     private static mesh: Mesh | undefined = undefined;
-    static copyTexture(texture: Texture, blitMaterial?: ShaderMaterial) {
+    /**
+     * Copy a texture to a new texture
+     * @param texture the texture to copy
+     * @param blitMaterial the material to use for copying (optional)
+     * @returns the newly created, copied texture
+    */
+    static copyTexture(texture: Texture, blitMaterial?: ShaderMaterial): Texture {
         const material = blitMaterial ?? this.blipMaterial!;
         material.uniforms.map.value = texture;
         material.needsUpdate = true;

src/engine/engine_types.ts CHANGED Viewed

@@ -320,6 +320,9 @@
 const contactsVectorBuffer = new CircularBuffer(() => new Vector3(), 20);
+/**
+ * Holds information about physics contacts
+ */
 export class ContactPoint {
     private readonly _point: Vec3;
@@ -350,6 +353,7 @@
         return target.set(this._tangentVelocity.x, this._tangentVelocity.y, this._tangentVelocity.z);
     }
+    /** @internal */
     constructor(point: Vec3, dist: number, normal: Vec3, impulse: number, friction: number, tangentVelocity: Vec3) {
         this._point = point;
         this.distance = dist;
@@ -360,12 +364,15 @@
     }
 }
-/// all info in here must be readonly because the object is only created once per started collision
+/**
+ * Holds information about a collision event. Includes a list of contact points and the colliders involved
+ */
 export class Collision {
     /** The contact points of this collision. Contains information about positions, normals, distance, friction, impulse... */
     readonly contacts: ContactPoint[];
+    /** @internal */
     constructor(obj: IGameObject, otherCollider: ICollider, contacts: ContactPoint[]) {
         this.me = obj;
         this._collider = otherCollider;

src/engine/engine_util_decorator.ts CHANGED Viewed

@@ -96,8 +96,9 @@
-/** experimental attribute - use to hook into another type's methods and run before the other methods run (similar to Harmony prefixes).
- * Return false to prevent the original method from running.
+/** Experimental attribute
+ * Use to hook into another type's methods and run before the other methods run (similar to Harmony prefixes).
+ * Return false to prevent the original method from running.
  */
 export const prefix = function <T>(type: Constructor<T>) {
     return function (target: IComponent | any, _propertyKey: string | { name: string }, _PropertyDescriptor: PropertyDescriptor) {

src/engine/engine_utils.ts CHANGED Viewed

@@ -319,10 +319,12 @@
     if (pathIndex >= 0) {
         // Take the source uri as the base path
         const basePath = source.substring(0, pathIndex + 1);
+        // make sure we don't have double slashes
+        while (basePath.endsWith("/") && uri.startsWith("/")) uri = uri.substring(1);
         // Append the relative uri
         const newUri = basePath + uri;
         // newUri = new URL(newUri, globalThis.location.href).href;
-        if (debugGetPath) console.log("source:", source, "- changed uri \nfrom", uri, "\n→ ", newUri, "\n" + basePath);
+        if (debugGetPath) console.log("source:", source, "changed uri \nfrom", uri, "\nto ", newUri, "\nbasePath: " + basePath);
         return newUri;
     }
     return uri;

src/engine-components/OrbitControls.ts CHANGED Viewed

@@ -639,10 +639,17 @@
                 expandByObjectRecursive(child);
             }
         }
+        let hasAnyObject = false;
         for (const object of objects) {
+            if (!object) continue;
+            hasAnyObject = true;
             object.updateMatrixWorld();
             expandByObjectRecursive(object);
         }
+        if (!hasAnyObject) {
+            console.warn("No objects to fit camera to...");
+            return;
+        }
         camera.updateMatrixWorld();
         camera.updateProjectionMatrix();

src/engine-components/SceneSwitcher.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 import { Object3D } from "three";
-import { AssetReference } from "../engine/engine_addressables.js";
+import { Addressables, AssetReference } from "../engine/engine_addressables.js";
 import { registerObservableAttribute } from "../engine/engine_element_extras.js";
 import { InputEvents } from "../engine/engine_input.js";
 import { isLocalNetwork } from "../engine/engine_networking_utils.js";
@@ -64,6 +64,7 @@
  * - `loadscene-start`: Called when a scene starts loading
  * - `loadscene-finished`: Called when a scene finished loading
  * - `progress`: Called when a scene is loading and the progress changes
+ * - `scene-opened`: Called when a scene is loaded and added to the SceneSwitcher's GameObject
  * @example
  * ```ts
  * sceneSwitcher.addEventListener("loadscene-start", (e) => {
@@ -75,6 +76,9 @@
  * sceneSwitcher.addEventListener("progress", (e) => {
  *  console.log("Loading progress", e.loaded, e.total);
  * });
+ * sceneSwitcher.addEventListener("scene-opened", (e) => {
+ * console.log("Scene opened", e.detail.scene.uri);
+ * });
  * ```
  *
  */
@@ -159,10 +163,14 @@
     private _preloadScheduler?: PreLoadScheduler;
+    /** @internal */
     awake(): void {
+        if (this.scenes === undefined) this.scenes = [];
         if (debug) console.log("SceneSwitcher", this);
     }
+    /** @internal */
     async onEnable() {
         globalThis.addEventListener("popstate", this.onPopState);
         this.context.input.addEventListener(InputEvents.KeyDown, this.onInputKeyDown);
@@ -210,6 +218,7 @@
         }
     }
+    /** @internal */
     onDisable(): void {
         globalThis.removeEventListener("popstate", this.onPopState);
         this.context.input.removeEventListener(InputEvents.KeyDown, this.onInputKeyDown);
@@ -288,14 +297,58 @@
         }
     }
+    /**
+     * Add a scene to the SceneSwitcher.
+     * If the scene is already added it will be added again.
+     * @param urlOrAssetReference The url of the scene or an AssetReference to the scene
+     * @returns The AssetReference of the scene that was added
+     * @example
+     * ```ts
+     * // adding a scene:
+     * sceneSwitcher.addScene("scene1.glb");
+     * // add another scene and load it:
+     * const scene2 = sceneSwitcher.addScene("scene2.glb");
+     * sceneSwitcher.switchScene(scene2).then(res => { console.log("Scene loaded", res); });
+     * ```
+     */
+    addScene(urlOrAssetReference: string | AssetReference): AssetReference {
+        if (typeof urlOrAssetReference === "string") {
+            let assetReference = this.context.addressables.findAssetReference(urlOrAssetReference);
+            if (!assetReference) {
+                assetReference = new AssetReference(urlOrAssetReference);
+                this.context.addressables.registerAssetReference(assetReference);
+            }
+            this.scenes.push(assetReference);
+            return assetReference;
+        }
+        this.scenes.push(urlOrAssetReference);
+        return urlOrAssetReference;
+    }
+    /**
+     * Load the next scene in the scenes array ({@link this.currentIndex} + 1)
+     * If the current scene is the last scene in the array and {@link this.clamp} is disabled then the first scene will be loaded.
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     */
     selectNext(): Promise<boolean> {
         return this.select(this._currentIndex + 1);
     }
+    /**
+     * Load the previous scene in the scenes array ({@link this.currentIndex} - 1)
+     * If the current scene is the first scene in the array and {@link this.clamp} is disabled then the last scene will be loaded.
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     */
     selectPrev(): Promise<boolean> {
         return this.select(this._currentIndex - 1);
     }
+    /**
+     * Load a scene by its index in the scenes array.
+     * @param index The index of the scene or a string that represents the scene uri (if the url is not known to the SceneSwitcher it will try to load the scene by its uri but it won't be added to the current scenes array. Use {@link addScene} to add a scene to the SceneSwitcher)
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     */
     select(index: number | string): Promise<boolean> {
         if (debug) console.log("select", index);
@@ -341,6 +394,19 @@
     private __lastSwitchScene?: AssetReference;
     private __lastSwitchScenePromise?: Promise<boolean>;
+    /**
+     * Switch to a scene by its AssetReference.
+     * If the scene is already loaded it will be unloaded and the new scene will be loaded.
+     * If the scene is already loading it will wait for the scene to be loaded.
+     * If the scene is already loaded and the same scene is requested again it will return the same promise that was returned the first time the scene was requested.
+     * @param scene The AssetReference of the scene to switch to
+     * @returns a promise that resolves to true if the scene was loaded successfully
+     * @example
+     * ```ts
+     * const myAssetReference = new AssetReference("scene1.glb");
+     * sceneSwitcher.switchScene(myAssetReference).then(res => { console.log("Scene loaded", res); });
+     * ```
+     */
     async switchScene(scene: AssetReference): Promise<boolean> {
         if (!(scene instanceof AssetReference)) {
             const type = typeof scene;
@@ -444,6 +510,9 @@
                     const res = sceneListener.sceneOpened(this);
                     if (res instanceof Promise) await res;
                 }
+                const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
+                this.dispatchEvent(openedEvt);
                 return true;
             }
         }