@needle-tools/engine 3.28.6-beta → 3.28.7-beta.1

package/lib/engine/engine_context.d.ts

@@ -1,269 +1,269 @@
-/// <reference types="webxr" />
-import { BufferGeometry, Camera, DepthTexture, Group, Material, Object3D, PerspectiveCamera, Scene, Texture, WebGLRenderer, type WebGLRendererParameters, type WebXRArrayCamera } from 'three';
-import { Input } from './engine_input.js';
-import { Physics } from './engine_physics.js';
-import { Time } from './engine_time.js';
-import { NetworkConnection } from './engine_networking.js';
-import { EffectComposer } from "postprocessing";
-import { AssetDatabase } from './engine_assetdatabase.js';
-import { RendererData as SceneLighting } from './engine_scenelighting.js';
-import { Addressables } from './engine_addressables.js';
-import { Application } from './engine_application.js';
-import { type ILightDataRegistry } from './engine_lightdata.js';
-import { PlayerViewManager } from './engine_playerview.js';
-import { type CoroutineData, type GLTF, type ICamera, type IComponent, type IContext, type ILight } from "./engine_types.js";
-export declare const build_scene_functions: {
-    [name: string]: (context: Context) => Promise<void>;
-};
-export declare class LoadingProgressArgs {
-    /** the name or URL of the loaded file */
-    name: string;
-    /** the loading progress event from the loader */
-    progress: ProgressEvent;
-    /** the index of the loaded file */
-    index: number;
-    /** the total number of files to load */
-    count: number;
-}
-export declare class ContextCreateArgs {
-    /** list of glTF or GLB files to load */
-    files: Array<string>;
-    /** called when loading a provided glTF file started */
-    onLoadingStart?: (index: number, file: string) => void;
-    /** called on update for each loaded glTF file */
-    onLoadingProgress?: (args: LoadingProgressArgs) => void;
-    /** Called after a gLTF file has finished loading */
-    onLoadingFinished?: (index: number, file: string, glTF: GLTF | null) => void;
-}
-export declare class ContextArgs {
-    name?: string;
-    /** for debugging only */
-    alias?: string;
-    /** the hash is used as a seed when initially loading the scene files */
-    hash?: string;
-    /** when true the context will not check if it's visible in the viewport and always update and render */
-    runInBackground?: boolean;
-    /** the DOM element the context belongs to or is inside of (this does not have to be the canvas. use renderer.domElement if you want to access the dom canvas) */
-    domElement?: HTMLElement | null;
-    /** externally owned renderer */
-    renderer?: WebGLRenderer;
-    /** externally owned camera */
-    camera?: Camera;
-    /** externally owned scene */
-    scene?: Scene;
-}
-export declare enum FrameEvent {
-    Start = -1,
-    EarlyUpdate = 0,
-    Update = 1,
-    LateUpdate = 2,
-    OnBeforeRender = 3,
-    OnAfterRender = 4,
-    PrePhysicsStep = 9,
-    PostPhysicsStep = 10,
-    Undefined = -1
-}
-export declare enum XRSessionMode {
-    ImmersiveVR = "immersive-vr",
-    ImmersiveAR = "immersive-ar"
-}
-/** threejs callback event signature */
-export declare type OnRenderCallback = (renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group) => void;
-export declare function registerComponent(script: IComponent, context?: Context): void;
-export declare class Context implements IContext {
-    private static _defaultTargetFramerate;
-    /** When a new context is created this is the framerate that will be used by default */
-    static get DefaultTargetFrameRate(): number | undefined;
-    /** When a new context is created this is the framerate that will be used by default */
-    static set DefaultTargetFrameRate(val: number | undefined);
-    private static _defaultWebglRendererParameters;
-    static get DefaultWebGLRendererParameters(): WebGLRendererParameters;
-    /** the needle engine version */
-    get version(): string;
-    /** The currently active context. Only set during the update loops */
-    static get Current(): Context;
-    /** @internal this property should not be set by user code */
-    static set Current(context: Context);
-    name: string;
-    alias: string | undefined | null;
-    /** When the renderer or camera are managed by an external process (e.g. when running in r3f context).
-     * When this is false you are responsible to call update(timestamp, xframe.
-     * It is also currently assumed that rendering is handled performed by an external process
-     * */
-    isManagedExternally: boolean;
-    /** set to true to pause the update loop. You can receive an event for it in your components.
-     * Note that script updates will not be called when paused */
-    isPaused: boolean;
-    /** When enabled the application will run while not visible on the page */
-    runInBackground: boolean;
-    /**
-     * Set to the target framerate you want your application to run in (you can use ?stats to check the fps)
-     * Set to undefined if you want to run at the maximum framerate
-     */
-    targetFrameRate?: number | {
-        value?: number;
-    };
-    /** Use a higher number for more accurate physics simulation.
-     * When undefined physics steps will be 1 for mobile devices and 5 for desktop devices
-     * Set to 0 to disable physics updates
-     * TODO: changing physics steps is currently not supported because then forces that we get from the character controller and rigidbody et al are not correct anymore - this needs to be properly tested before making this configureable
-    */
-    private physicsSteps?;
-    /** used to append to loaded assets */
-    hash?: string;
-    /** the <needle-engine> HTML element */
-    domElement: HTMLElement;
-    appendHTMLElement(element: HTMLElement): HTMLElement;
-    get resolutionScaleFactor(): number;
-    /** use to scale the resolution up or down of the renderer. default is 1 */
-    set resolutionScaleFactor(val: number);
-    private _resolutionScaleFactor;
-    private _boundingClientRectFrame;
-    private _boundingClientRect;
-    private _domX;
-    private _domY;
-    private calculateBoundingClientRect;
-    get domWidth(): number;
-    get domHeight(): number;
-    get domX(): number;
-    get domY(): number;
-    get isInXR(): boolean;
-    xrSessionMode: XRSessionMode | undefined;
-    get isInVR(): boolean;
-    get isInAR(): boolean;
-    get xrSession(): XRSession | null;
-    get xrFrame(): XRFrame | null;
-    get xrCamera(): WebXRArrayCamera | undefined;
-    private _xrFrame;
-    get arOverlayElement(): HTMLElement;
-    /** Current event of the update cycle */
-    get currentFrameEvent(): FrameEvent;
-    private _currentFrameEvent;
-    scene: Scene;
-    renderer: WebGLRenderer;
-    composer: EffectComposer | null;
-    scripts: IComponent[];
-    scripts_pausedChanged: IComponent[];
-    scripts_earlyUpdate: IComponent[];
-    scripts_update: IComponent[];
-    scripts_lateUpdate: IComponent[];
-    scripts_onBeforeRender: IComponent[];
-    scripts_onAfterRender: IComponent[];
-    scripts_WithCorroutines: IComponent[];
-    coroutines: {
-        [FrameEvent: number]: Array<CoroutineData>;
-    };
-    mainCameraComponent: ICamera | undefined;
-    private _camera;
-    get mainCamera(): Camera | null;
-    set mainCamera(cam: Camera | null);
-    post_setup_callbacks: Function[];
-    pre_update_callbacks: Function[];
-    pre_render_callbacks: Function[];
-    post_render_callbacks: Function[];
-    new_scripts: IComponent[];
-    new_script_start: IComponent[];
-    new_scripts_pre_setup_callbacks: Function[];
-    new_scripts_post_setup_callbacks: Function[];
-    application: Application;
-    time: Time;
-    input: Input;
-    physics: Physics;
-    connection: NetworkConnection;
-    /**
-     * @deprecated AssetDataBase is deprecated
-     */
-    assets: AssetDatabase;
-    mainLight: ILight | null;
-    /** @deprecated Use sceneLighting */
-    get rendererData(): SceneLighting;
-    sceneLighting: SceneLighting;
-    addressables: Addressables;
-    lightmaps: ILightDataRegistry;
-    players: PlayerViewManager;
-    get isCreated(): boolean;
-    private _sizeChanged;
-    private _isCreated;
-    private _isCreating;
-    private _isVisible;
-    private _stats;
-    constructor(args?: ContextArgs);
-    private createNewRenderer;
-    private _intersectionObserver;
-    private internalOnUpdateVisible;
-    private _disposeCallbacks;
-    updateSize(): void;
-    updateAspect(camera: PerspectiveCamera, width?: number, height?: number): void;
-    /** This will recreate the whole needle engine context and dispose the whole scene content
-     * All content will be reloaded (loading times might be faster due to browser caches)
-     * All scripts will be recreated */
-    recreate(): void;
-    private _originalCreationArgs?;
-    /** @deprecated use create. This method will be removed in a future version */
-    onCreate(opts?: ContextCreateArgs): Promise<boolean | any[]>;
-    create(opts?: ContextCreateArgs): Promise<boolean | any[]>;
-    private onUnhandledRejection;
-    /** Will destroy all scenes and objects in the scene
-     */
-    clear(): void;
-    dispose(): void;
-    /**@deprecated use dispose()  */
-    onDestroy(): void;
-    private internalOnDestroy;
-    registerCoroutineUpdate(script: IComponent, coroutine: Generator, evt: FrameEvent): Generator;
-    unregisterCoroutineUpdate(coroutine: Generator, evt: FrameEvent): void;
-    stopAllCoroutinesFrom(script: IComponent): void;
-    private _cameraStack;
-    setCurrentCamera(cam: ICamera): void;
-    removeCamera(cam?: ICamera | null): void;
-    private _onBeforeRenderListeners;
-    private _onAfterRenderListeners;
-    /** use this to subscribe to onBeforeRender events on threejs objects */
-    addBeforeRenderListener(target: Object3D, callback: OnRenderCallback): void;
-    removeBeforeRenderListener(target: Object3D, callback: OnRenderCallback): void;
-    /** use this to subscribe to onAfterRender events on threejs objects */
-    addAfterRenderListener(target: Object3D, callback: OnRenderCallback): void;
-    removeAfterRenderListener(target: Object3D, callback: OnRenderCallback): void;
-    private _createRenderCallbackWrapper;
-    private _requireDepthTexture;
-    private _requireColorTexture;
-    private _renderTarget?;
-    private _isRendering;
-    get isRendering(): boolean;
-    setRequireDepth(val: boolean): void;
-    setRequireColor(val: boolean): void;
-    get depthTexture(): DepthTexture | null;
-    get opaqueColorTexture(): Texture | null;
-    /** returns true if the dom element is visible on screen */
-    get isVisibleToUser(): boolean;
-    private _createId;
-    private internalOnCreate;
-    private internalLoadInitialContent;
-    /** Sets the animation loop.
-     * Can not be done while creating the context or when disposed
-     **/
-    restartRenderLoop(): boolean;
-    private _renderlooperrors;
-    /** Performs a full update step including script callbacks, rendering (unless isManagedExternally is set to false) and post render callbacks */
-    update(timestamp: DOMHighResTimeStamp, frame?: XRFrame | null): void;
-    /** Call to **manually** perform physics steps.
-     * By default the context uses the `physicsSteps` property to perform steps during the update loop
-     * If you just want to increase the accuracy of physics you can instead set the `physicsSteps` property to a higher value
-     * */
-    updatePhysics(steps: number): void;
-    private _lastTimestamp;
-    private _accumulatedTime;
-    private _dispatchReadyAfterFrame;
-    private internalStep;
-    private internalOnBeforeRender;
-    private internalUpdatePhysics;
-    private internalOnRender;
-    private internalOnAfterRender;
-    renderNow(camera?: Camera): boolean;
-    /** returns true if we should return out of the frame loop */
-    private _wasPaused;
-    private onHandlePaused;
-    private evaluatePaused;
-    private renderRequiredTextures;
-    private executeCoroutines;
-}
+/// <reference types="webxr" />
+import { BufferGeometry, Camera, DepthTexture, Group, Material, Object3D, PerspectiveCamera, Scene, Texture, WebGLRenderer, type WebGLRendererParameters, type WebXRArrayCamera } from 'three';
+import { Input } from './engine_input.js';
+import { Physics } from './engine_physics.js';
+import { Time } from './engine_time.js';
+import { NetworkConnection } from './engine_networking.js';
+import { EffectComposer } from "postprocessing";
+import { AssetDatabase } from './engine_assetdatabase.js';
+import { RendererData as SceneLighting } from './engine_scenelighting.js';
+import { Addressables } from './engine_addressables.js';
+import { Application } from './engine_application.js';
+import { type ILightDataRegistry } from './engine_lightdata.js';
+import { PlayerViewManager } from './engine_playerview.js';
+import { type CoroutineData, type GLTF, type ICamera, type IComponent, type IContext, type ILight } from "./engine_types.js";
+export declare const build_scene_functions: {
+    [name: string]: (context: Context) => Promise<void>;
+};
+export declare class LoadingProgressArgs {
+    /** the name or URL of the loaded file */
+    name: string;
+    /** the loading progress event from the loader */
+    progress: ProgressEvent;
+    /** the index of the loaded file */
+    index: number;
+    /** the total number of files to load */
+    count: number;
+}
+export declare class ContextCreateArgs {
+    /** list of glTF or GLB files to load */
+    files: Array<string>;
+    /** called when loading a provided glTF file started */
+    onLoadingStart?: (index: number, file: string) => void;
+    /** called on update for each loaded glTF file */
+    onLoadingProgress?: (args: LoadingProgressArgs) => void;
+    /** Called after a gLTF file has finished loading */
+    onLoadingFinished?: (index: number, file: string, glTF: GLTF | null) => void;
+}
+export declare class ContextArgs {
+    name?: string;
+    /** for debugging only */
+    alias?: string;
+    /** the hash is used as a seed when initially loading the scene files */
+    hash?: string;
+    /** when true the context will not check if it's visible in the viewport and always update and render */
+    runInBackground?: boolean;
+    /** the DOM element the context belongs to or is inside of (this does not have to be the canvas. use renderer.domElement if you want to access the dom canvas) */
+    domElement?: HTMLElement | null;
+    /** externally owned renderer */
+    renderer?: WebGLRenderer;
+    /** externally owned camera */
+    camera?: Camera;
+    /** externally owned scene */
+    scene?: Scene;
+}
+export declare enum FrameEvent {
+    Start = -1,
+    EarlyUpdate = 0,
+    Update = 1,
+    LateUpdate = 2,
+    OnBeforeRender = 3,
+    OnAfterRender = 4,
+    PrePhysicsStep = 9,
+    PostPhysicsStep = 10,
+    Undefined = -1
+}
+export declare enum XRSessionMode {
+    ImmersiveVR = "immersive-vr",
+    ImmersiveAR = "immersive-ar"
+}
+/** threejs callback event signature */
+export declare type OnRenderCallback = (renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group) => void;
+export declare function registerComponent(script: IComponent, context?: Context): void;
+export declare class Context implements IContext {
+    private static _defaultTargetFramerate;
+    /** When a new context is created this is the framerate that will be used by default */
+    static get DefaultTargetFrameRate(): number | undefined;
+    /** When a new context is created this is the framerate that will be used by default */
+    static set DefaultTargetFrameRate(val: number | undefined);
+    private static _defaultWebglRendererParameters;
+    static get DefaultWebGLRendererParameters(): WebGLRendererParameters;
+    /** the needle engine version */
+    get version(): string;
+    /** The currently active context. Only set during the update loops */
+    static get Current(): Context;
+    /** @internal this property should not be set by user code */
+    static set Current(context: Context);
+    name: string;
+    alias: string | undefined | null;
+    /** When the renderer or camera are managed by an external process (e.g. when running in r3f context).
+     * When this is false you are responsible to call update(timestamp, xframe.
+     * It is also currently assumed that rendering is handled performed by an external process
+     * */
+    isManagedExternally: boolean;
+    /** set to true to pause the update loop. You can receive an event for it in your components.
+     * Note that script updates will not be called when paused */
+    isPaused: boolean;
+    /** When enabled the application will run while not visible on the page */
+    runInBackground: boolean;
+    /**
+     * Set to the target framerate you want your application to run in (you can use ?stats to check the fps)
+     * Set to undefined if you want to run at the maximum framerate
+     */
+    targetFrameRate?: number | {
+        value?: number;
+    };
+    /** Use a higher number for more accurate physics simulation.
+     * When undefined physics steps will be 1 for mobile devices and 5 for desktop devices
+     * Set to 0 to disable physics updates
+     * TODO: changing physics steps is currently not supported because then forces that we get from the character controller and rigidbody et al are not correct anymore - this needs to be properly tested before making this configureable
+    */
+    private physicsSteps?;
+    /** used to append to loaded assets */
+    hash?: string;
+    /** the <needle-engine> HTML element */
+    domElement: HTMLElement;
+    appendHTMLElement(element: HTMLElement): HTMLElement;
+    get resolutionScaleFactor(): number;
+    /** use to scale the resolution up or down of the renderer. default is 1 */
+    set resolutionScaleFactor(val: number);
+    private _resolutionScaleFactor;
+    private _boundingClientRectFrame;
+    private _boundingClientRect;
+    private _domX;
+    private _domY;
+    private calculateBoundingClientRect;
+    get domWidth(): number;
+    get domHeight(): number;
+    get domX(): number;
+    get domY(): number;
+    get isInXR(): boolean;
+    xrSessionMode: XRSessionMode | undefined;
+    get isInVR(): boolean;
+    get isInAR(): boolean;
+    get xrSession(): XRSession | null;
+    get xrFrame(): XRFrame | null;
+    get xrCamera(): WebXRArrayCamera | undefined;
+    private _xrFrame;
+    get arOverlayElement(): HTMLElement;
+    /** Current event of the update cycle */
+    get currentFrameEvent(): FrameEvent;
+    private _currentFrameEvent;
+    scene: Scene;
+    renderer: WebGLRenderer;
+    composer: EffectComposer | null;
+    scripts: IComponent[];
+    scripts_pausedChanged: IComponent[];
+    scripts_earlyUpdate: IComponent[];
+    scripts_update: IComponent[];
+    scripts_lateUpdate: IComponent[];
+    scripts_onBeforeRender: IComponent[];
+    scripts_onAfterRender: IComponent[];
+    scripts_WithCorroutines: IComponent[];
+    coroutines: {
+        [FrameEvent: number]: Array<CoroutineData>;
+    };
+    mainCameraComponent: ICamera | undefined;
+    private _camera;
+    get mainCamera(): Camera | null;
+    set mainCamera(cam: Camera | null);
+    post_setup_callbacks: Function[];
+    pre_update_callbacks: Function[];
+    pre_render_callbacks: Function[];
+    post_render_callbacks: Function[];
+    new_scripts: IComponent[];
+    new_script_start: IComponent[];
+    new_scripts_pre_setup_callbacks: Function[];
+    new_scripts_post_setup_callbacks: Function[];
+    application: Application;
+    time: Time;
+    input: Input;
+    physics: Physics;
+    connection: NetworkConnection;
+    /**
+     * @deprecated AssetDataBase is deprecated
+     */
+    assets: AssetDatabase;
+    mainLight: ILight | null;
+    /** @deprecated Use sceneLighting */
+    get rendererData(): SceneLighting;
+    sceneLighting: SceneLighting;
+    addressables: Addressables;
+    lightmaps: ILightDataRegistry;
+    players: PlayerViewManager;
+    get isCreated(): boolean;
+    private _sizeChanged;
+    private _isCreated;
+    private _isCreating;
+    private _isVisible;
+    private _stats;
+    constructor(args?: ContextArgs);
+    private createNewRenderer;
+    private _intersectionObserver;
+    private internalOnUpdateVisible;
+    private _disposeCallbacks;
+    updateSize(): void;
+    updateAspect(camera: PerspectiveCamera, width?: number, height?: number): void;
+    /** This will recreate the whole needle engine context and dispose the whole scene content
+     * All content will be reloaded (loading times might be faster due to browser caches)
+     * All scripts will be recreated */
+    recreate(): void;
+    private _originalCreationArgs?;
+    /** @deprecated use create. This method will be removed in a future version */
+    onCreate(opts?: ContextCreateArgs): Promise<boolean | any[]>;
+    create(opts?: ContextCreateArgs): Promise<boolean | any[]>;
+    private onUnhandledRejection;
+    /** Will destroy all scenes and objects in the scene
+     */
+    clear(): void;
+    dispose(): void;
+    /**@deprecated use dispose()  */
+    onDestroy(): void;
+    private internalOnDestroy;
+    registerCoroutineUpdate(script: IComponent, coroutine: Generator, evt: FrameEvent): Generator;
+    unregisterCoroutineUpdate(coroutine: Generator, evt: FrameEvent): void;
+    stopAllCoroutinesFrom(script: IComponent): void;
+    private _cameraStack;
+    setCurrentCamera(cam: ICamera): void;
+    removeCamera(cam?: ICamera | null): void;
+    private _onBeforeRenderListeners;
+    private _onAfterRenderListeners;
+    /** use this to subscribe to onBeforeRender events on threejs objects */
+    addBeforeRenderListener(target: Object3D, callback: OnRenderCallback): void;
+    removeBeforeRenderListener(target: Object3D, callback: OnRenderCallback): void;
+    /** use this to subscribe to onAfterRender events on threejs objects */
+    addAfterRenderListener(target: Object3D, callback: OnRenderCallback): void;
+    removeAfterRenderListener(target: Object3D, callback: OnRenderCallback): void;
+    private _createRenderCallbackWrapper;
+    private _requireDepthTexture;
+    private _requireColorTexture;
+    private _renderTarget?;
+    private _isRendering;
+    get isRendering(): boolean;
+    setRequireDepth(val: boolean): void;
+    setRequireColor(val: boolean): void;
+    get depthTexture(): DepthTexture | null;
+    get opaqueColorTexture(): Texture | null;
+    /** returns true if the dom element is visible on screen */
+    get isVisibleToUser(): boolean;
+    private _createId;
+    private internalOnCreate;
+    private internalLoadInitialContent;
+    /** Sets the animation loop.
+     * Can not be done while creating the context or when disposed
+     **/
+    restartRenderLoop(): boolean;
+    private _renderlooperrors;
+    /** Performs a full update step including script callbacks, rendering (unless isManagedExternally is set to false) and post render callbacks */
+    update(timestamp: DOMHighResTimeStamp, frame?: XRFrame | null): void;
+    /** Call to **manually** perform physics steps.
+     * By default the context uses the `physicsSteps` property to perform steps during the update loop
+     * If you just want to increase the accuracy of physics you can instead set the `physicsSteps` property to a higher value
+     * */
+    updatePhysics(steps: number): void;
+    private _lastTimestamp;
+    private _accumulatedTime;
+    private _dispatchReadyAfterFrame;
+    private internalStep;
+    private internalOnBeforeRender;
+    private internalUpdatePhysics;
+    private internalOnRender;
+    private internalOnAfterRender;
+    renderNow(camera?: Camera): boolean;
+    /** returns true if we should return out of the frame loop */
+    private _wasPaused;
+    private onHandlePaused;
+    private evaluatePaused;
+    private renderRequiredTextures;
+    private executeCoroutines;
+}