API
API|
@babylonjs/loaders|
GLTFFileLoader

Class GLTFFileLoader

File loader for loading glTF files into a scene.

Hierarchy (View Summary)

Implements

Index
constructor
alwaysComputeBoundingBox alwaysComputeSkeletonRootNode animationStartMode compileMaterials compileShadowGenerators coordinateSystemMode createInstances customRootNode? dontUseTransmissionHelper extensionOptions loadAllMaterials loadMorphTargets loadNodeAnimations loadOnlyMaterials loadSkins name onCameraLoadedObservable onCompleteObservable onDisposeObservable onErrorObservable onExtensionLoadedObservable onLoaderStateChangedObservable onMaterialLoadedObservable onMeshLoadedObservable onParsedObservable onSkinLoadedObservable onTextureLoadedObservable onValidatedObservable preprocessUrlAsync skipMaterials targetFps transparencyAsCoverage useClipPlane useGltfTextureNames useMaxMorphTargetInfluencers useOpenPBR useRangeRequests useSRGBBuffers validate
capturePerformanceCounters loaderState loggingEnabled onCameraLoaded onComplete onDispose onError onExtensionLoaded onMaterialLoaded onMeshLoaded onParsed onSkinLoaded onTextureLoaded onValidated
dispose rewriteRootURL? whenCompleteAsync
alwaysComputeBoundingBox: boolean = false

Defines if the loader should always compute the bounding boxes of meshes and not use the min/max values from the position accessor. Defaults to false.

alwaysComputeSkeletonRootNode: boolean = false

Defines if the loader should always compute the nearest common ancestor of the skeleton joints instead of using skin.skeleton. Defaults to false. Set this to true if loading assets with invalid skin.skeleton values.

animationStartMode: GLTFLoaderAnimationStartMode = GLTFLoaderAnimationStartMode.FIRST

The animation start mode. Defaults to FIRST.

compileMaterials: boolean = false

Defines if the loader should compile materials before raising the success callback. Defaults to false.

compileShadowGenerators: boolean = false

Defines if the loader should compile shadow generators before raising the success callback. Defaults to false.

coordinateSystemMode: GLTFLoaderCoordinateSystemMode = GLTFLoaderCoordinateSystemMode.AUTO

The coordinate system mode. Defaults to AUTO.

createInstances: boolean = true

Defines if the loader should create instances when multiple glTF nodes point to the same glTF mesh. Defaults to true.

customRootNode?: any

Defines the node to use as the root of the hierarchy when loading the scene (default: undefined). If not defined, a root node will be automatically created. You can also pass null if you don't want a root node to be created.

dontUseTransmissionHelper: boolean = false

If true, the loader will not use the transmission helper when loading materials with transmission.

extensionOptions: {
    EXT_lights_area?: { enabled?: boolean };
    EXT_lights_ies?: { enabled?: boolean };
    EXT_lights_image_based?: { enabled?: boolean };
    EXT_mesh_gpu_instancing?: { enabled?: boolean };
    EXT_meshopt_compression?: { enabled?: boolean };
    EXT_texture_avif?: { enabled?: boolean };
    EXT_texture_webp?: { enabled?: boolean };
    ExtrasAsMetadata?: { enabled?: boolean };
    KHR_animation_pointer?: { enabled?: boolean };
    KHR_draco_mesh_compression?: { enabled?: boolean };
    KHR_gaussian_splatting?: { enabled?: boolean };
    KHR_interactivity?: {
        autoStart?: boolean;
        enabled?: boolean;
        parseOnly?: boolean;
        strictValidation?: boolean;
    };
    KHR_lights_punctual?: { enabled?: boolean };
    KHR_materials_anisotropy?: { enabled?: boolean };
    KHR_materials_clearcoat?: { enabled?: boolean };
    KHR_materials_coat?: { enabled?: boolean };
    KHR_materials_diffuse_roughness?: { enabled?: boolean };
    KHR_materials_diffuse_transmission?: { enabled?: boolean };
    KHR_materials_dispersion?: { enabled?: boolean };
    KHR_materials_emissive_strength?: { enabled?: boolean };
    KHR_materials_fuzz?: { enabled?: boolean };
    KHR_materials_ior?: { enabled?: boolean };
    KHR_materials_iridescence?: { enabled?: boolean };
    KHR_materials_pbrSpecularGlossiness?: { enabled?: boolean };
    KHR_materials_sheen?: { enabled?: boolean };
    KHR_materials_specular?: { enabled?: boolean };
    KHR_materials_transmission?: { enabled?: boolean };
    KHR_materials_unlit?: { enabled?: boolean };
    KHR_materials_variants?: {
        defaultVariant?: string;
        enabled?: boolean;
        onLoaded?: (controller: MaterialVariantsController) => void;
    };
    KHR_materials_volume?: { enabled?: boolean };
    KHR_materials_volume_scatter?: { enabled?: boolean };
    KHR_mesh_quantization?: { enabled?: boolean };
    KHR_node_hoverability?: { enabled?: boolean };
    KHR_node_selectability?: { enabled?: boolean };
    KHR_node_visibility?: { enabled?: boolean };
    KHR_texture_basisu?: { enabled?: boolean };
    KHR_texture_transform?: { enabled?: boolean };
    KHR_xmp_json_ld?: { enabled?: boolean };
    MSFT_audio_emitter?: { enabled?: boolean };
    MSFT_lod?: { enabled?: boolean; maxLODsToLoad?: number };
    MSFT_minecraftMesh?: { enabled?: boolean };
    MSFT_sRGBFactors?: { enabled?: boolean };
    [key: string]: { enabled?: boolean; [key: string]: unknown } | undefined;
} = {}

Defines options for glTF extensions.

Type Declaration

  • [key: string]: { enabled?: boolean; [key: string]: unknown } | undefined

    Type Declaration

    • { enabled?: boolean; [key: string]: unknown }
      • [key: string]: unknown
      • Optionalenabled?: boolean

        Defines if the extension is enabled

    • undefined
  • OptionalEXT_lights_area?: { enabled?: boolean }

    Defines options for the EXT_lights_area extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalEXT_lights_ies?: { enabled?: boolean }

    Defines options for the EXT_lights_ies extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalEXT_lights_image_based?: { enabled?: boolean }

    Defines options for the EXT_lights_image_based extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalEXT_mesh_gpu_instancing?: { enabled?: boolean }

    Defines options for the EXT_mesh_gpu_instancing extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalEXT_meshopt_compression?: { enabled?: boolean }

    Defines options for the EXT_meshopt_compression extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalEXT_texture_avif?: { enabled?: boolean }

    Defines options for the EXT_texture_avif extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalEXT_texture_webp?: { enabled?: boolean }

    Defines options for the EXT_texture_webp extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalExtrasAsMetadata?: { enabled?: boolean }

    Defines options for the ExtrasAsMetadata extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_animation_pointer?: { enabled?: boolean }

    Defines options for the KHR_animation_pointer extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_draco_mesh_compression?: { enabled?: boolean }

    Defines options for the KHR_draco_mesh_compression extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_gaussian_splatting?: { enabled?: boolean }

    Defines options for the KHR_gaussian_splatting extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_interactivity?: {
        autoStart?: boolean;
        enabled?: boolean;
        parseOnly?: boolean;
        strictValidation?: boolean;
    }

    Defines options for the KHR_interactivity extension.

    • OptionalautoStart?: boolean

      Whether the selected default graph starts automatically after import. Defaults to true.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

    • OptionalparseOnly?: boolean

      Whether to retain only the canonical source model and executable FlowGraph serialization without constructing runtime graphs. Defaults to false.

    • OptionalstrictValidation?: boolean

      Whether to enforce the ratified graph validation rules. Defaults to true. Set to false only for pre-ratification assets.

  • OptionalKHR_lights_punctual?: { enabled?: boolean }

    Defines options for the KHR_lights_punctual extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_anisotropy?: { enabled?: boolean }

    Defines options for the KHR_materials_anisotropy extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_clearcoat?: { enabled?: boolean }

    Defines options for the KHR_materials_clearcoat extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_coat?: { enabled?: boolean }

    Defines options for the KHR_materials_coat extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_diffuse_roughness?: { enabled?: boolean }

    Defines options for the KHR_materials_diffuse_roughness extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_diffuse_transmission?: { enabled?: boolean }

    Defines options for the KHR_materials_diffuse_transmission extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_dispersion?: { enabled?: boolean }

    Defines options for the KHR_materials_dispersion extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_emissive_strength?: { enabled?: boolean }

    Defines options for the KHR_materials_emissive_strength extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_fuzz?: { enabled?: boolean }

    Defines options for the KHR_materials_fuzz extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_ior?: { enabled?: boolean }

    Defines options for the KHR_materials_ior extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_iridescence?: { enabled?: boolean }

    Defines options for the KHR_materials_iridescence extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_pbrSpecularGlossiness?: { enabled?: boolean }

    Defines options for the KHR_materials_pbrSpecularGlossiness extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_sheen?: { enabled?: boolean }

    Defines options for the KHR_materials_sheen extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_specular?: { enabled?: boolean }

    Defines options for the KHR_materials_specular extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_transmission?: { enabled?: boolean }

    Defines options for the KHR_materials_transmission extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_unlit?: { enabled?: boolean }

    Defines options for the KHR_materials_unlit extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_variants?: {
        defaultVariant?: string;
        enabled?: boolean;
        onLoaded?: (controller: MaterialVariantsController) => void;
    }

    Defines options for the KHR_materials_variants extension.

    • OptionaldefaultVariant?: string

      Specifies the name of the variant that should be selected by default.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

    • Optional ExperimentalonLoaded?: (controller: MaterialVariantsController) => void

      Defines a callback that will be called if material variants are loaded.

  • OptionalKHR_materials_volume?: { enabled?: boolean }

    Defines options for the KHR_materials_volume extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_materials_volume_scatter?: { enabled?: boolean }

    Defines options for the KHR_materials_volume_scatter extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_mesh_quantization?: { enabled?: boolean }

    Defines options for the KHR_mesh_quantization extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_node_hoverability?: { enabled?: boolean }

    Defines options for the KHR_node_hoverability extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_node_selectability?: { enabled?: boolean }

    Defines options for the KHR_selectability extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_node_visibility?: { enabled?: boolean }

    Defines options for the KHR_node_visibility extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_texture_basisu?: { enabled?: boolean }

    Defines options for the KHR_texture_basisu extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_texture_transform?: { enabled?: boolean }

    Defines options for the KHR_texture_transform extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalKHR_xmp_json_ld?: { enabled?: boolean }

    Defines options for the KHR_xmp_json_ld extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalMSFT_audio_emitter?: { enabled?: boolean }

    Defines options for the MSFT_audio_emitter extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalMSFT_lod?: { enabled?: boolean; maxLODsToLoad?: number }

    Defines options for the MSFT_lod extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

    • OptionalmaxLODsToLoad?: number

      Maximum number of LODs to load, starting from the lowest LOD.

  • OptionalMSFT_minecraftMesh?: { enabled?: boolean }

    Defines options for the MSFT_minecraftMesh extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

  • OptionalMSFT_sRGBFactors?: { enabled?: boolean }

    Defines options for the MSFT_sRGBFactors extension.

    • Optionalenabled?: boolean

      Defines if the extension is enabled

loadAllMaterials: boolean = false

If true, load all materials defined in the file, even if not used by any mesh. Defaults to false.

loadMorphTargets: boolean = true

Defines if the loader should load morph targets. Defaults to true.

loadNodeAnimations: boolean = true

Defines if the loader should load node animations. Defaults to true. NOTE: The animation of this node will still load if the node is also a joint of a skin and loadSkins is true.

loadOnlyMaterials: boolean = false

If true, load only the materials defined in the file. Defaults to false.

loadSkins: boolean = true

Defines if the loader should load skins. Defaults to true.

name: any = GLTFFileLoaderMetadata.name

Name of the loader ("gltf")

onCameraLoadedObservable: any = ...

Observable raised when the loader creates a camera after parsing the glTF properties of the camera.

onCompleteObservable: any = ...

Observable raised when the asset is completely loaded, immediately before the loader is disposed. For assets with LODs, raised when all of the LODs are complete. For assets without LODs, raised when the model is complete, immediately after the loader resolves the returned promise.

onDisposeObservable: any = ...

Observable raised after the loader is disposed.

onErrorObservable: any = ...

Observable raised when an error occurs.

onExtensionLoadedObservable: any = ...

Observable raised after a loader extension is created. Set additional options for a loader extension in this event.

onLoaderStateChangedObservable: any = ...

Observable raised when the loader state changes.

onMaterialLoadedObservable: any = ...

Observable raised when the loader creates a material after parsing the glTF properties of the material.

onMeshLoadedObservable: any = ...

Observable raised when the loader creates a mesh after parsing the glTF properties of the mesh. Note that the observable is raised as soon as the mesh object is created, meaning some data may not have been setup yet for this mesh (vertex data, morph targets, material, ...)

onParsedObservable: any = ...

Raised when the asset has been parsed

onSkinLoadedObservable: any = ...

Observable raised when the loader creates a skin after parsing the glTF properties of the skin node.

https://doc.babylonjs.com/features/featuresDeepDive/importers/glTF/glTFSkinning#ignoring-the-transform-of-the-skinned-mesh

the transform node that corresponds to the original glTF skin node used for animations

the transform node that is the skinned mesh itself or the parent of the skinned meshes

onTextureLoadedObservable: any = ...

Observable raised when the loader creates a texture after parsing the glTF properties of the texture.

onValidatedObservable: any = ...

Observable raised after validation when validate is set to true. The event data is the result of the validation.

preprocessUrlAsync: (url: string, rootUrl?: string) => Promise<string> = DefaultPreprocessUrlAsync

Function called before loading a URL referenced by the asset. Setting this function allows parent-relative asset URIs and makes the callback responsible for URI safety.

Type Declaration

    • (url: string, rootUrl?: string): Promise<string>

    • Parameters

      • url: string

        The URL referenced by the asset

      • OptionalrootUrl: string

        The root URL of the asset, if available

      Returns Promise<string>

      A promise that resolves to the URL to load

skipMaterials: boolean = false

If true, do not load any materials defined in the file. Defaults to false.

targetFps: number = 60

When loading glTF animations, which are defined in seconds, target them to this FPS. Defaults to 60.

transparencyAsCoverage: boolean = false

Defines if the Alpha blended materials are only applied as coverage. If false, (default) The luminance of each pixel will reduce its opacity to simulate the behaviour of most physical materials. If true, no extra effects are applied to transparent pixels.

useClipPlane: boolean = false

Defines if the loader should also compile materials with clip planes. Defaults to false.

useGltfTextureNames: boolean = false

If true, the loader will derive the name for Babylon textures from the glTF texture name, image name, or image url. Defaults to false. Note that it is possible for multiple Babylon textures to share the same name when the Babylon textures load from the same glTF texture or image.

useMaxMorphTargetInfluencers: boolean = true

When loading a mesh with morph targets, configure its MorphTargetManager so the morph shader is compiled once for all targets (numMaxInfluencers = numTargets, optimizeInfluencers = false). This prevents the shader from being recompiled (and the resulting one-frame visual glitch) when an animated morph target influence passes through zero and the active influencer count changes. Disable to restore the previous behavior, where only the currently active (non-zero) influencers drive the shader. That is cheaper per frame for meshes with very large morph target counts, but recompiles the shader during animation. Defaults to true.

useOpenPBR: boolean = false

Load the glTF files using the OpenPBR material.

useRangeRequests: boolean = false

Defines if the loader should use range requests when load binary glTF files from HTTP. Enabling will disable offline support and glTF validator. Defaults to false.

useSRGBBuffers: boolean = true

If true, load the color (gamma encoded) textures into sRGB buffers (if supported by the GPU), which will yield more accurate results when sampling the texture. Defaults to true.

validate: boolean = false

Defines if the loader should validate the asset.

  • set onCameraLoaded(callback: ((camera: Camera) => void) | undefined): void

    Callback raised when the loader creates a camera after parsing the glTF properties of the camera.

    Parameters

    • callback: ((camera: Camera) => void) | undefined

    Returns void

  • set onComplete(callback: () => void): void

    Callback raised when the asset is completely loaded, immediately before the loader is disposed. For assets with LODs, raised when all of the LODs are complete. For assets without LODs, raised when the model is complete, immediately after the loader resolves the returned promise.

    Parameters

    • callback: () => void

    Returns void

  • set onMaterialLoaded(callback: ((material: Material) => void) | undefined): void

    Callback raised when the loader creates a material after parsing the glTF properties of the material.

    Parameters

    • callback: ((material: Material) => void) | undefined

    Returns void

  • set onMeshLoaded(callback: ((mesh: AbstractMesh) => void) | undefined): void

    Callback raised when the loader creates a mesh after parsing the glTF properties of the mesh. Note that the callback is called as soon as the mesh object is created, meaning some data may not have been setup yet for this mesh (vertex data, morph targets, material, ...)

    Parameters

    • callback: ((mesh: AbstractMesh) => void) | undefined

    Returns void

  • set onTextureLoaded(
        callback: ((texture: BaseTexture) => void) | undefined,
    ): void

    Callback raised when the loader creates a texture after parsing the glTF properties of the texture.

    Parameters

    • callback: ((texture: BaseTexture) => void) | undefined

    Returns void

  • set onValidated(callback: (results: IGLTFValidationResults) => void): void

    Callback raised after the asset is validated.

    Parameters

    • callback: (results: IGLTFValidationResults) => void

    Returns void

  • The callback that allows custom handling of the root url based on the response url.

    Parameters

    • rootUrl: string

      the original root url

    • OptionalresponseURL: string

      the response url if available

    Returns string

    the new root url