@babylonjs/core 7.19.1 → 7.20.0

package/Loading/sceneLoader.d.ts

@@ -13,7 +13,7 @@ import type { TransformNode } from "../Meshes/transformNode";
 import type { Geometry } from "../Meshes/geometry";
 import type { Light } from "../Lights/light";
 import type { ISpriteManager } from "../Sprites/spriteManager";
-import type { AbstractEngine } from "../Engines/abstractEngine";
+import { AbstractEngine } from "../Engines/abstractEngine";
 /**
  * Type used for the success callback of ImportMesh
  */
@@ -79,7 +79,7 @@ export interface ISceneLoaderPluginExtensions {
     /**
      * Defines the list of supported extensions
      */
-    [extension: string]: {
+    readonly [extension: string]: {
         isBinary: boolean;
     };
 }
@@ -90,12 +90,13 @@ export interface ISceneLoaderPluginFactory {
     /**
      * Defines the name of the factory
      */
-    name: string;
+    readonly name: string;
     /**
      * Function called to create a new plugin
+     * @param options plugin options that were passed to the SceneLoader operation
      * @returns the new plugin
      */
-    createPlugin(): ISceneLoaderPlugin | ISceneLoaderPluginAsync;
+    createPlugin(options: SceneLoaderPluginOptions): ISceneLoaderPlugin | ISceneLoaderPluginAsync;
     /**
      * The callback that returns true if the data can be directly loaded.
      * @param data string containing the file data
@@ -110,11 +111,11 @@ export interface ISceneLoaderPluginBase {
     /**
      * The friendly name of this plugin.
      */
-    name: string;
+    readonly name: string;
     /**
      * The file extensions supported by this plugin.
      */
-    extensions: string | ISceneLoaderPluginExtensions;
+    readonly extensions: string | ISceneLoaderPluginExtensions;
     /**
      * The callback called when loading from a url.
      * @param scene scene loading this url
@@ -264,6 +265,91 @@ interface IRegisteredPlugin {
      */
     isBinary: boolean;
 }
+/**
+ * Defines options for SceneLoader plugins. This interface is extended by specific plugins.
+ */
+export interface SceneLoaderPluginOptions extends Record<string, Record<string, unknown> | undefined> {
+}
+/**
+ * Adds default/implicit options to plugin specific options.
+ */
+type DefaultPluginOptions<BasePluginOptions> = {
+    /**
+     * Defines if the plugin is enabled
+     */
+    enabled?: boolean;
+} & BasePluginOptions;
+type SceneSource = string | File | ArrayBufferView;
+/**
+ * Defines common options for loading operations performed by SceneLoader.
+ */
+interface SceneLoaderOptions {
+    /**
+     * A string that defines the root url for the scene and resources or the concatenation of rootURL and filename (e.g. http://example.com/test.glb)
+     */
+    rootUrl?: string;
+    /**
+     * A callback with a progress event for each file being loaded
+     */
+    onProgress?: (event: ISceneLoaderProgressEvent) => void;
+    /**
+     * The extension used to determine the plugin
+     */
+    pluginExtension?: string;
+    /**
+     * Defines the filename, if the data is binary
+     */
+    name?: string;
+    /**
+     * Defines options for the registered plugins
+     */
+    pluginOptions?: {
+        [Plugin in keyof SceneLoaderPluginOptions]: {
+            [Option in keyof DefaultPluginOptions<SceneLoaderPluginOptions[Plugin]>]: DefaultPluginOptions<SceneLoaderPluginOptions[Plugin]>[Option];
+        };
+    };
+}
+/**
+ * Defines options for ImportMeshAsync.
+ */
+export interface ImportMeshOptions extends SceneLoaderOptions {
+    /**
+     * An array of mesh names, a single mesh name, or empty string for all meshes that filter what meshes are imported
+     */
+    meshNames?: string | readonly string[] | null | undefined;
+}
+/**
+ * Defines options for LoadAsync.
+ */
+export interface LoadOptions extends SceneLoaderOptions {
+}
+/**
+ * Defines options for AppendAsync.
+ */
+export interface AppendOptions extends SceneLoaderOptions {
+}
+/**
+ * Defines options for LoadAssetContainerAsync.
+ */
+export interface LoadAssetContainerOptions extends SceneLoaderOptions {
+}
+/**
+ * Defines options for ImportAnimationsAsync.
+ */
+export interface ImportAnimationsOptions extends SceneLoaderOptions {
+    /**
+     * When true, animations are cleaned before importing new ones. Animations are appended otherwise
+     */
+    overwriteAnimations?: boolean;
+    /**
+     * Defines how to handle old animations groups before importing new ones
+     */
+    animationGroupLoadingMode?: SceneLoaderAnimationGroupLoadingMode;
+    /**
+     * defines a function used to convert animation targets from loaded scene to current scene (default: search node by name)
+     */
+    targetConverter?: Nullable<(target: unknown) => unknown>;
+}
 /**
  * Class used to load scene from various file formats using registered plugins
  * @see https://doc.babylonjs.com/features/featuresDeepDive/importers/loadingFileTypes
@@ -354,7 +440,17 @@ export declare class SceneLoader {
      * @param name defines the name of the file, if the data is binary
      * @returns The loaded plugin
      */
-    static ImportMesh(meshNames: string | readonly string[] | null | undefined, rootUrl: string, sceneFilename?: string | File | ArrayBufferView, scene?: Nullable<Scene>, onSuccess?: Nullable<SceneLoaderSuccessCallback>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): Nullable<ISceneLoaderPlugin | ISceneLoaderPluginAsync>;
+    static ImportMesh(meshNames: string | readonly string[] | null | undefined, rootUrl: string, sceneFilename?: SceneSource, scene?: Nullable<Scene>, onSuccess?: Nullable<SceneLoaderSuccessCallback>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): Nullable<ISceneLoaderPlugin | ISceneLoaderPluginAsync>;
+    private static _ImportMesh;
+    /**
+     * Import meshes into a scene
+     * @experimental
+     * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
+     * @param scene the instance of BABYLON.Scene to append to
+     * @param options an object that configures aspects of how the scene is loaded
+     * @returns The loaded list of imported meshes, particle systems, skeletons, and animation groups
+     */
+    static ImportMeshAsync(source: SceneSource, scene: Scene, options?: ImportMeshOptions): Promise<ISceneLoaderAsyncResult>;
     /**
      * Import meshes into a scene
      * @param meshNames an array of mesh names, a single mesh name, or empty string for all meshes that filter what meshes are imported
@@ -366,7 +462,7 @@ export declare class SceneLoader {
      * @param name defines the name of the file
      * @returns The loaded list of imported meshes, particle systems, skeletons, and animation groups
      */
-    static ImportMeshAsync(meshNames: string | readonly string[] | null | undefined, rootUrl: string, sceneFilename?: string | File | ArrayBufferView, scene?: Nullable<Scene>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, pluginExtension?: Nullable<string>, name?: string): Promise<ISceneLoaderAsyncResult>;
+    static ImportMeshAsync(meshNames: string | readonly string[] | null | undefined, rootUrl: string, sceneFilename?: SceneSource, scene?: Nullable<Scene>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, pluginExtension?: Nullable<string>, name?: string): Promise<ISceneLoaderAsyncResult>;
     /**
      * Load a scene
      * @param rootUrl a string that defines the root url for the scene and resources or the concatenation of rootURL and filename (e.g. http://example.com/test.glb)
@@ -379,7 +475,17 @@ export declare class SceneLoader {
      * @param name defines the filename, if the data is binary
      * @returns The loaded plugin
      */
-    static Load(rootUrl: string, sceneFilename?: string | File | ArrayBufferView, engine?: Nullable<AbstractEngine>, onSuccess?: Nullable<(scene: Scene) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): Nullable<ISceneLoaderPlugin | ISceneLoaderPluginAsync>;
+    static Load(rootUrl: string, sceneFilename?: SceneSource, engine?: Nullable<AbstractEngine>, onSuccess?: Nullable<(scene: Scene) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): Nullable<ISceneLoaderPlugin | ISceneLoaderPluginAsync>;
+    private static _Load;
+    /**
+     * Load a scene
+     * @experimental
+     * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
+     * @param engine is the instance of BABYLON.Engine to use to create the scene
+     * @param options an object that configures aspects of how the scene is loaded
+     * @returns The loaded scene
+     */
+    static LoadAsync(source: SceneSource, engine: AbstractEngine, options?: LoadOptions): Promise<Scene>;
     /**
      * Load a scene
      * @param rootUrl a string that defines the root url for the scene and resources or the concatenation of rootURL and filename (e.g. http://example.com/test.glb)
@@ -390,7 +496,7 @@ export declare class SceneLoader {
      * @param name defines the filename, if the data is binary
      * @returns The loaded scene
      */
-    static LoadAsync(rootUrl: string, sceneFilename?: string | File | ArrayBufferView, engine?: Nullable<AbstractEngine>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, pluginExtension?: Nullable<string>, name?: string): Promise<Scene>;
+    static LoadAsync(rootUrl: string, sceneFilename?: SceneSource, engine?: Nullable<AbstractEngine>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, pluginExtension?: Nullable<string>, name?: string): Promise<Scene>;
     /**
      * Append a scene
      * @param rootUrl a string that defines the root url for the scene and resources or the concatenation of rootURL and filename (e.g. http://example.com/test.glb)
@@ -403,7 +509,17 @@ export declare class SceneLoader {
      * @param name defines the name of the file, if the data is binary
      * @returns The loaded plugin
      */
-    static Append(rootUrl: string, sceneFilename?: string | File | ArrayBufferView, scene?: Nullable<Scene>, onSuccess?: Nullable<(scene: Scene) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): Nullable<ISceneLoaderPlugin | ISceneLoaderPluginAsync>;
+    static Append(rootUrl: string, sceneFilename?: SceneSource, scene?: Nullable<Scene>, onSuccess?: Nullable<(scene: Scene) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): Nullable<ISceneLoaderPlugin | ISceneLoaderPluginAsync>;
+    private static _Append;
+    /**
+     * Append a scene
+     * @experimental
+     * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
+     * @param scene is the instance of BABYLON.Scene to append to
+     * @param options an object that configures aspects of how the scene is loaded
+     * @returns The given scene
+     */
+    static AppendAsync(source: SceneSource, scene: Scene, options?: LoadAssetContainerOptions): Promise<Scene>;
     /**
      * Append a scene
      * @param rootUrl a string that defines the root url for the scene and resources or the concatenation of rootURL and filename (e.g. http://example.com/test.glb)
@@ -414,7 +530,7 @@ export declare class SceneLoader {
      * @param name defines the name of the file, if the data is binary
      * @returns The given scene
      */
-    static AppendAsync(rootUrl: string, sceneFilename?: string | File | ArrayBufferView, scene?: Nullable<Scene>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, pluginExtension?: Nullable<string>, name?: string): Promise<Scene>;
+    static AppendAsync(rootUrl: string, sceneFilename?: SceneSource, scene?: Nullable<Scene>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, pluginExtension?: Nullable<string>, name?: string): Promise<Scene>;
     /**
      * Load a scene into an asset container
      * @param rootUrl a string that defines the root url for the scene and resources or the concatenation of rootURL and filename (e.g. http://example.com/test.glb)
@@ -427,7 +543,17 @@ export declare class SceneLoader {
      * @param name defines the filename, if the data is binary
      * @returns The loaded plugin
      */
-    static LoadAssetContainer(rootUrl: string, sceneFilename?: string | File | ArrayBufferView, scene?: Nullable<Scene>, onSuccess?: Nullable<(assets: AssetContainer) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): Nullable<ISceneLoaderPlugin | ISceneLoaderPluginAsync>;
+    static LoadAssetContainer(rootUrl: string, sceneFilename?: SceneSource, scene?: Nullable<Scene>, onSuccess?: Nullable<(assets: AssetContainer) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): Nullable<ISceneLoaderPlugin | ISceneLoaderPluginAsync>;
+    private static _LoadAssetContainer;
+    /**
+     * Load a scene into an asset container
+     * @experimental
+     * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
+     * @param scene is the instance of Scene to append to
+     * @param options an object that configures aspects of how the scene is loaded
+     * @returns The loaded asset container
+     */
+    static LoadAssetContainerAsync(source: SceneSource, scene: Scene, options?: LoadAssetContainerOptions): Promise<AssetContainer>;
     /**
      * Load a scene into an asset container
      * @param rootUrl a string that defines the root url for the scene and resources or the concatenation of rootURL and filename (e.g. http://example.com/test.glb)
@@ -435,9 +561,10 @@ export declare class SceneLoader {
      * @param scene is the instance of Scene to append to
      * @param onProgress a callback with a progress event for each file being loaded
      * @param pluginExtension the extension used to determine the plugin
+     * @param name defines the filename, if the data is binary
      * @returns The loaded asset container
      */
-    static LoadAssetContainerAsync(rootUrl: string, sceneFilename?: string | File, scene?: Nullable<Scene>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, pluginExtension?: Nullable<string>): Promise<AssetContainer>;
+    static LoadAssetContainerAsync(rootUrl: string, sceneFilename?: SceneSource, scene?: Nullable<Scene>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, pluginExtension?: Nullable<string>, name?: string): Promise<AssetContainer>;
     /**
      * Import animations from a file into a scene
      * @param rootUrl a string that defines the root url for the scene and resources or the concatenation of rootURL and filename (e.g. http://example.com/test.glb)
@@ -450,8 +577,19 @@ export declare class SceneLoader {
      * @param onProgress a callback with a progress event for each file being loaded
      * @param onError a callback with the scene, a message, and possibly an exception when import fails
      * @param pluginExtension the extension used to determine the plugin
+     * @param name defines the filename, if the data is binary
      */
-    static ImportAnimations(rootUrl: string, sceneFilename?: string | File, scene?: Nullable<Scene>, overwriteAnimations?: boolean, animationGroupLoadingMode?: SceneLoaderAnimationGroupLoadingMode, targetConverter?: Nullable<(target: any) => any>, onSuccess?: Nullable<(scene: Scene) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>): void;
+    static ImportAnimations(rootUrl: string, sceneFilename?: SceneSource, scene?: Nullable<Scene>, overwriteAnimations?: boolean, animationGroupLoadingMode?: SceneLoaderAnimationGroupLoadingMode, targetConverter?: Nullable<(target: any) => any>, onSuccess?: Nullable<(scene: Scene) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): void;
+    private static _ImportAnimations;
+    /**
+     * Import animations from a file into a scene
+     * @experimental
+     * @param source a string that defines the name of the scene file, or starts with "data:" following by the stringified version of the scene, or a File object, or an ArrayBufferView
+     * @param scene is the instance of BABYLON.Scene to append to (default: last created scene)
+     * @param options an object that configures aspects of how the scene is loaded
+     * @returns The loaded asset container
+     */
+    static ImportAnimationsAsync(source: SceneSource, scene: Scene, options?: ImportAnimationsOptions): Promise<Scene>;
     /**
      * Import animations from a file into a scene
      * @param rootUrl a string that defines the root url for the scene and resources or the concatenation of rootURL and filename (e.g. http://example.com/test.glb)
@@ -464,8 +602,9 @@ export declare class SceneLoader {
      * @param onProgress a callback with a progress event for each file being loaded
      * @param onError a callback with the scene, a message, and possibly an exception when import fails
      * @param pluginExtension the extension used to determine the plugin
+     * @param name defines the filename, if the data is binary
      * @returns the updated scene with imported animations
      */
-    static ImportAnimationsAsync(rootUrl: string, sceneFilename?: string | File, scene?: Nullable<Scene>, overwriteAnimations?: boolean, animationGroupLoadingMode?: SceneLoaderAnimationGroupLoadingMode, targetConverter?: Nullable<(target: any) => any>, onSuccess?: Nullable<(scene: Scene) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>): Promise<Scene>;
+    static ImportAnimationsAsync(rootUrl: string, sceneFilename?: SceneSource, scene?: Nullable<Scene>, overwriteAnimations?: boolean, animationGroupLoadingMode?: SceneLoaderAnimationGroupLoadingMode, targetConverter?: Nullable<(target: any) => any>, onSuccess?: Nullable<(scene: Scene) => void>, onProgress?: Nullable<(event: ISceneLoaderProgressEvent) => void>, onError?: Nullable<(scene: Scene, message: string, exception?: any) => void>, pluginExtension?: Nullable<string>, name?: string): Promise<Scene>;
 }
 export {};