@needle-tools/engine 4.11.5-next.f5ee735 → 4.11.6

package/lib/engine/debug/debug_spector.d.ts

@@ -1,16 +1,16 @@
-import type { Context } from "../engine_setup.js";
-declare global {
-    interface Window {
-        SPECTOR?: {
-            Spector: new () => Spector;
-        };
-    }
-    interface Spector {
-        displayUI: () => void;
-        setCanvas: (canvas: HTMLCanvasElement) => void;
-        spyCanvases: boolean;
-        startCaptureOnNextFrame: () => void;
-        captureCanvas: (canvas: HTMLCanvasElement) => any;
-    }
-}
-export declare function initSpectorIfAvailable(_context: Context, canvas: HTMLCanvasElement): void;
+import type { Context } from "../engine_setup.js";
+declare global {
+    interface Window {
+        SPECTOR?: {
+            Spector: new () => Spector;
+        };
+    }
+    interface Spector {
+        displayUI: () => void;
+        setCanvas: (canvas: HTMLCanvasElement) => void;
+        spyCanvases: boolean;
+        startCaptureOnNextFrame: () => void;
+        captureCanvas: (canvas: HTMLCanvasElement) => any;
+    }
+}
+export declare function initSpectorIfAvailable(_context: Context, canvas: HTMLCanvasElement): void;

package/lib/engine/debug/debug_spector.js

@@ -1,28 +1,28 @@
-import { isDevEnvironment } from "./debug.js";
-export function initSpectorIfAvailable(_context, canvas) {
-    if (typeof window !== undefined && window.SPECTOR) {
-        console.log(window.SPECTOR);
-        const params = new URLSearchParams(window.location.search);
-        if (params.has("spector")) {
-            const frame = Number.parseInt(params.get("spector") || "0") || 0;
-            console.log("Scheduled Spector capture at frame #" + frame);
-            const spector = new window.SPECTOR.Spector();
-            spector.spyCanvases = true;
-            waitForFrameAndCapture();
-            return;
-            function waitForFrameAndCapture() {
-                if (frame > _context.time.frame)
-                    return window.requestAnimationFrame(() => waitForFrameAndCapture());
-                const res = spector.captureCanvas(canvas);
-                if (res && res instanceof Promise)
-                    res.then(() => spector.displayUI());
-                else
-                    spector.displayUI();
-            }
-        }
-        else if (isDevEnvironment()) {
-            console.debug("Spector available: Add '?spector=<frame>' to the URL to enable it and capture a frame.");
-        }
-    }
-}
+import { isDevEnvironment } from "./debug.js";
+export function initSpectorIfAvailable(_context, canvas) {
+    if (typeof window !== undefined && window.SPECTOR) {
+        console.log(window.SPECTOR);
+        const params = new URLSearchParams(window.location.search);
+        if (params.has("spector")) {
+            const frame = Number.parseInt(params.get("spector") || "0") || 0;
+            console.log("Scheduled Spector capture at frame #" + frame);
+            const spector = new window.SPECTOR.Spector();
+            spector.spyCanvases = true;
+            waitForFrameAndCapture();
+            return;
+            function waitForFrameAndCapture() {
+                if (frame > _context.time.frame)
+                    return window.requestAnimationFrame(() => waitForFrameAndCapture());
+                const res = spector.captureCanvas(canvas);
+                if (res && res instanceof Promise)
+                    res.then(() => spector.displayUI());
+                else
+                    spector.displayUI();
+            }
+        }
+        else if (isDevEnvironment()) {
+            console.debug("Spector available: Add '?spector=<frame>' to the URL to enable it and capture a frame.");
+        }
+    }
+}
 //# sourceMappingURL=debug_spector.js.map

package/lib/engine/debug/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./debug.js";
-export * from "./debug_console.js";
+export * from "./debug.js";
+export * from "./debug_console.js";

package/lib/engine/debug/index.js

@@ -1,3 +1,3 @@
-export * from "./debug.js";
-export * from "./debug_console.js";
+export * from "./debug.js";
+export * from "./debug_console.js";
 //# sourceMappingURL=index.js.map

package/lib/engine/engine_addressables.d.ts

@@ -1,232 +1,232 @@
-import { Object3D, Texture } from "three";
-import { type IInstantiateOptions } from "./engine_gameobject.js";
-import { SyncInstantiateOptions } from "./engine_networking_instantiate.js";
-import { SerializationContext, TypeSerializer } from "./engine_serialization_core.js";
-import { Context } from "./engine_setup.js";
-import type { IComponent, SourceIdentifier } from "./engine_types.js";
-/**
- * The Addressables class is used to register and manage {@link AssetReference} types
- * It can be accessed from components via {@link Context.Current} or {@link Context.addressables} (e.g. `this.context.addressables`)
- */
-export declare class Addressables {
-    private _context;
-    private _assetReferences;
-    /** @internal */
-    constructor(context: Context);
-    /** @internal */
-    dispose(): void;
-    private preUpdate;
-    /**
-     * Find a registered AssetReference by its URL
-     */
-    findAssetReference(url: string): AssetReference | null;
-    /**
-     * Register an asset reference
-     * @internal
-     */
-    registerAssetReference(ref: AssetReference): AssetReference;
-    /** @internal */
-    unregisterAssetReference(ref: AssetReference): void;
-}
-export type ProgressCallback = (asset: AssetReference, prog: ProgressEvent) => void;
-/** ### AssetReferences can be used to load glTF or GLB assets
- * Use {@link AssetReference.getOrCreateFromUrl} to get an AssetReference for a URL to be easily loaded. When using the same URL multiple times the same AssetReference will be returned, this avoids loading or creating the same asset multiple times.
- *
- * **Important methods:**
- * - {@link preload} to load the asset binary without creating an instance yet.
- * - {@link loadAssetAsync} to load the asset and create an instance.
- * - {@link instantiate} to load the asset and create another instance.
- * - {@link unload} to dispose allocated memory and destroy the asset instance.
- *
- * @example Loading an asset from a URL
- * ```ts
- * import { AssetReference } from '@needle-tools/engine';
- * const assetRef = AssetReference.getOrCreateFromUrl("https://example.com/myModel.glb");
- * const instance = await assetRef.loadAssetAsync();
- * scene.add(instance);
- * ```
- *
- * @example Referencing an asset in a component and loading it on start
- * ```ts
- * import { Behaviour, serializable, AssetReference } from '@needle-tools/engine';
- *
- * export class MyComponent extends Behaviour {
- *
- *   @serializable(AssetReference)
- *   myModel?: AssetReference;
- *
- *   // Load the model on start. Start is called after awake and onEnable
- *   start() {
- *     if (this.myModel) {
- *       this.myModel.loadAssetAsync().then(instance => {
- *         if (instance) {
- *           // add the loaded model to this component's game object
- *           this.gameObject.add(instance);
- *         }
- *       });
- *     }
- *   }
- * }
- * ```
- *
- * ### Related:
- * - {@link ImageReference} to load external image URLs
- * - {@link FileReference} to load external file URLs
- * - {@link loadAsset} to load assets directly without using AssetReferences
- */
-export declare class 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.
-     * @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;
-    /**
-     * 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;
-    readonly isAssetReference = true;
-    /**
-     * This is the loaded asset root object. If the asset is a glb/gltf file this will be the {@link three#Scene} object.
-     */
-    get rawAsset(): any;
-    /** The loaded asset root
-     */
-    get asset(): Object3D | null;
-    protected set asset(val: Object3D | null);
-    /** The url of the loaded asset (or the asset to be loaded)
-     * @deprecated use url */
-    get uri(): string;
-    /** The url of the loaded asset (or the asset to be loaded) */
-    get url(): string;
-    /** The name of the assigned url. This name is deduced from the url and might not reflect the actual name of the asset */
-    get urlName(): string;
-    /**
-     * @returns true if the uri is a valid URL (http, https, blob)
-     */
-    get hasUrl(): boolean;
-    private _rawAsset;
-    private _glbRoot?;
-    private _url;
-    private _urlName;
-    private _progressListeners;
-    private _isLoadingRawBinary;
-    private _rawBinary?;
-    /** @internal */
-    constructor(params: {
-        url: string;
-    } | {
-        asset: Object3D;
-    });
-    constructor(uri: string, _hash?: string, asset?: any);
-    private onResolvePrefab;
-    private get mustLoad();
-    private _loadingPromise;
-    /**
-     * @returns `true` if the asset has been loaded (via preload) or if it exists already (assigned to `asset`) */
-    isLoaded(): boolean | ArrayBuffer;
-    /** frees previously allocated memory and destroys the current `asset` instance (if any) */
-    unload(): void;
-    /** loads the asset binary without creating an instance */
-    preload(): Promise<ArrayBufferLike | null>;
-    /** Loads the asset and creates one instance (assigned to `asset`)
-     * @returns the loaded asset
-     */
-    loadAssetAsync(prog?: ProgressCallback | null): Promise<Object3D | null>;
-    /** loads and returns a new instance of `asset` */
-    instantiate(parent?: Object3D | IInstantiateOptions | null): Promise<Object3D<import("three").Object3DEventMap> | null>;
-    /** loads and returns a new instance of `asset` - this call is networked so an instance will be created on all connected users */
-    instantiateSynced(parent?: Object3D | SyncInstantiateOptions, saveOnServer?: boolean): Promise<Object3D<import("three").Object3DEventMap> | null>;
-    beginListenDownload(evt: ProgressCallback): void;
-    endListenDownload(evt: ProgressCallback): void;
-    private raiseProgressEvent;
-    private static readonly currentlyInstantiating;
-    private onInstantiate;
-    /**
-     * try to ignore the intermediate created object
-     * because it causes trouble if we instantiate an assetreference per player
-     * and call destroy on the player marker root
-     * @returns the scene root object if the asset was a glb/gltf
-     */
-    private tryGetActualGameObjectRoot;
-}
-/**
- * Load images or textures from external URLs.
- *
- * **Important methods:**
- * - {@link createHTMLImage} to create an HTMLImageElement from the URL
- * - {@link createTexture} to create a Three.js Texture from the URL
- *
- * @example
- * ```ts
- * import { ImageReference, serializable } from '@needle-tools/engine';
- *
- * export class MyComponent extends Behaviour {
- *   @serializable(ImageReference)
- *   myImage?:ImageReference;
- *   async start() {
- *     if(this.myImage) {
- *       const texture = await this.myImage.createTexture();
- *       if(texture) {
- *         // use the texture
- *       }
- *     }
- *   }
- * ```
- *
- * ### Related:
- * - {@link AssetReference} to load glTF or GLB assets
- * - {@link FileReference} to load external file URLs
- */
-export declare class ImageReference {
-    private static imageReferences;
-    static getOrCreate(url: string): ImageReference;
-    constructor(url: string);
-    readonly url: string;
-    private _bitmap?;
-    private _bitmapObject?;
-    dispose(): void;
-    createHTMLImage(): HTMLImageElement;
-    private loader;
-    createTexture(): Promise<Texture | null>;
-    /** Loads the bitmap data of the image */
-    getBitmap(): Promise<ImageBitmap | null>;
-}
-/** @internal */
-export declare class ImageReferenceSerializer extends TypeSerializer {
-    constructor();
-    onSerialize(_data: string, _context: SerializationContext): null;
-    onDeserialize(data: string, _context: SerializationContext): ImageReference | undefined;
-}
-/**
- * Use this if a file is a external file URL. The file can be any arbitrary binary data like a videofile or a text asset.
- *
- * ### Related:
- * - {@link AssetReference} to load glTF or GLB assets
- * - {@link ImageReference} to load external image URLs
- */
-export declare class FileReference {
-    private static cache;
-    static getOrCreate(url: string): FileReference;
-    /** Load the file binary data
-     * @returns a promise that resolves to the binary data of the file. Make sure to await this request or use `.then(res => {...})` to get the result.
-     */
-    loadRaw(): Promise<Blob>;
-    /** Load the file as text (if the referenced file is a text file like a .txt or .json file)
-     * @returns a promise that resolves to the text data of the file. Make sure to await this request or use `.then(res => {...})` to get the result. If the format is json you can use `JSON.parse(result)` to convert it to a json object
-     */
-    loadText(): Promise<string>;
-    /** The resolved url to the file */
-    readonly url: string;
-    private res?;
-    constructor(url: string);
-}
-/** @internal */
-export declare class FileReferenceSerializer extends TypeSerializer {
-    constructor();
-    onSerialize(_data: string, _context: SerializationContext): null;
-    onDeserialize(data: string, _context: SerializationContext): FileReference | undefined;
-}
+import { Object3D, Texture } from "three";
+import { type IInstantiateOptions } from "./engine_gameobject.js";
+import { SyncInstantiateOptions } from "./engine_networking_instantiate.js";
+import { SerializationContext, TypeSerializer } from "./engine_serialization_core.js";
+import { Context } from "./engine_setup.js";
+import type { IComponent, SourceIdentifier } from "./engine_types.js";
+/**
+ * The Addressables class is used to register and manage {@link AssetReference} types
+ * It can be accessed from components via {@link Context.Current} or {@link Context.addressables} (e.g. `this.context.addressables`)
+ */
+export declare class Addressables {
+    private _context;
+    private _assetReferences;
+    /** @internal */
+    constructor(context: Context);
+    /** @internal */
+    dispose(): void;
+    private preUpdate;
+    /**
+     * Find a registered AssetReference by its URL
+     */
+    findAssetReference(url: string): AssetReference | null;
+    /**
+     * Register an asset reference
+     * @internal
+     */
+    registerAssetReference(ref: AssetReference): AssetReference;
+    /** @internal */
+    unregisterAssetReference(ref: AssetReference): void;
+}
+export type ProgressCallback = (asset: AssetReference, prog: ProgressEvent) => void;
+/** ### AssetReferences can be used to load glTF or GLB assets
+ * Use {@link AssetReference.getOrCreateFromUrl} to get an AssetReference for a URL to be easily loaded. When using the same URL multiple times the same AssetReference will be returned, this avoids loading or creating the same asset multiple times.
+ *
+ * **Important methods:**
+ * - {@link preload} to load the asset binary without creating an instance yet.
+ * - {@link loadAssetAsync} to load the asset and create an instance.
+ * - {@link instantiate} to load the asset and create another instance.
+ * - {@link unload} to dispose allocated memory and destroy the asset instance.
+ *
+ * @example Loading an asset from a URL
+ * ```ts
+ * import { AssetReference } from '@needle-tools/engine';
+ * const assetRef = AssetReference.getOrCreateFromUrl("https://example.com/myModel.glb");
+ * const instance = await assetRef.loadAssetAsync();
+ * scene.add(instance);
+ * ```
+ *
+ * @example Referencing an asset in a component and loading it on start
+ * ```ts
+ * import { Behaviour, serializable, AssetReference } from '@needle-tools/engine';
+ *
+ * export class MyComponent extends Behaviour {
+ *
+ *   @serializable(AssetReference)
+ *   myModel?: AssetReference;
+ *
+ *   // Load the model on start. Start is called after awake and onEnable
+ *   start() {
+ *     if (this.myModel) {
+ *       this.myModel.loadAssetAsync().then(instance => {
+ *         if (instance) {
+ *           // add the loaded model to this component's game object
+ *           this.gameObject.add(instance);
+ *         }
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Related:
+ * - {@link ImageReference} to load external image URLs
+ * - {@link FileReference} to load external file URLs
+ * - {@link loadAsset} to load assets directly without using AssetReferences
+ */
+export declare class 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.
+     * @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;
+    /**
+     * 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;
+    readonly isAssetReference = true;
+    /**
+     * This is the loaded asset root object. If the asset is a glb/gltf file this will be the {@link three#Scene} object.
+     */
+    get rawAsset(): any;
+    /** The loaded asset root
+     */
+    get asset(): Object3D | null;
+    protected set asset(val: Object3D | null);
+    /** The url of the loaded asset (or the asset to be loaded)
+     * @deprecated use url */
+    get uri(): string;
+    /** The url of the loaded asset (or the asset to be loaded) */
+    get url(): string;
+    /** The name of the assigned url. This name is deduced from the url and might not reflect the actual name of the asset */
+    get urlName(): string;
+    /**
+     * @returns true if the uri is a valid URL (http, https, blob)
+     */
+    get hasUrl(): boolean;
+    private _rawAsset;
+    private _glbRoot?;
+    private _url;
+    private _urlName;
+    private _progressListeners;
+    private _isLoadingRawBinary;
+    private _rawBinary?;
+    /** @internal */
+    constructor(params: {
+        url: string;
+    } | {
+        asset: Object3D;
+    });
+    constructor(uri: string, _hash?: string, asset?: any);
+    private onResolvePrefab;
+    private get mustLoad();
+    private _loadingPromise;
+    /**
+     * @returns `true` if the asset has been loaded (via preload) or if it exists already (assigned to `asset`) */
+    isLoaded(): boolean | ArrayBuffer;
+    /** frees previously allocated memory and destroys the current `asset` instance (if any) */
+    unload(): void;
+    /** loads the asset binary without creating an instance */
+    preload(): Promise<ArrayBufferLike | null>;
+    /** Loads the asset and creates one instance (assigned to `asset`)
+     * @returns the loaded asset
+     */
+    loadAssetAsync(prog?: ProgressCallback | null): Promise<Object3D | null>;
+    /** loads and returns a new instance of `asset` */
+    instantiate(parent?: Object3D | IInstantiateOptions | null): Promise<Object3D<import("three").Object3DEventMap> | null>;
+    /** loads and returns a new instance of `asset` - this call is networked so an instance will be created on all connected users */
+    instantiateSynced(parent?: Object3D | SyncInstantiateOptions, saveOnServer?: boolean): Promise<Object3D<import("three").Object3DEventMap> | null>;
+    beginListenDownload(evt: ProgressCallback): void;
+    endListenDownload(evt: ProgressCallback): void;
+    private raiseProgressEvent;
+    private static readonly currentlyInstantiating;
+    private onInstantiate;
+    /**
+     * try to ignore the intermediate created object
+     * because it causes trouble if we instantiate an assetreference per player
+     * and call destroy on the player marker root
+     * @returns the scene root object if the asset was a glb/gltf
+     */
+    private tryGetActualGameObjectRoot;
+}
+/**
+ * Load images or textures from external URLs.
+ *
+ * **Important methods:**
+ * - {@link createHTMLImage} to create an HTMLImageElement from the URL
+ * - {@link createTexture} to create a Three.js Texture from the URL
+ *
+ * @example
+ * ```ts
+ * import { ImageReference, serializable } from '@needle-tools/engine';
+ *
+ * export class MyComponent extends Behaviour {
+ *   @serializable(ImageReference)
+ *   myImage?:ImageReference;
+ *   async start() {
+ *     if(this.myImage) {
+ *       const texture = await this.myImage.createTexture();
+ *       if(texture) {
+ *         // use the texture
+ *       }
+ *     }
+ *   }
+ * ```
+ *
+ * ### Related:
+ * - {@link AssetReference} to load glTF or GLB assets
+ * - {@link FileReference} to load external file URLs
+ */
+export declare class ImageReference {
+    private static imageReferences;
+    static getOrCreate(url: string): ImageReference;
+    constructor(url: string);
+    readonly url: string;
+    private _bitmap?;
+    private _bitmapObject?;
+    dispose(): void;
+    createHTMLImage(): HTMLImageElement;
+    private loader;
+    createTexture(): Promise<Texture | null>;
+    /** Loads the bitmap data of the image */
+    getBitmap(): Promise<ImageBitmap | null>;
+}
+/** @internal */
+export declare class ImageReferenceSerializer extends TypeSerializer {
+    constructor();
+    onSerialize(_data: string, _context: SerializationContext): null;
+    onDeserialize(data: string, _context: SerializationContext): ImageReference | undefined;
+}
+/**
+ * Use this if a file is a external file URL. The file can be any arbitrary binary data like a videofile or a text asset.
+ *
+ * ### Related:
+ * - {@link AssetReference} to load glTF or GLB assets
+ * - {@link ImageReference} to load external image URLs
+ */
+export declare class FileReference {
+    private static cache;
+    static getOrCreate(url: string): FileReference;
+    /** Load the file binary data
+     * @returns a promise that resolves to the binary data of the file. Make sure to await this request or use `.then(res => {...})` to get the result.
+     */
+    loadRaw(): Promise<Blob>;
+    /** Load the file as text (if the referenced file is a text file like a .txt or .json file)
+     * @returns a promise that resolves to the text data of the file. Make sure to await this request or use `.then(res => {...})` to get the result. If the format is json you can use `JSON.parse(result)` to convert it to a json object
+     */
+    loadText(): Promise<string>;
+    /** The resolved url to the file */
+    readonly url: string;
+    private res?;
+    constructor(url: string);
+}
+/** @internal */
+export declare class FileReferenceSerializer extends TypeSerializer {
+    constructor();
+    onSerialize(_data: string, _context: SerializationContext): null;
+    onDeserialize(data: string, _context: SerializationContext): FileReference | undefined;
+}