or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bvh-loading.mdgltf-loading.mdindex.mdobj-loading.mdsplat-loading.mdstl-loading.md
tile.json

tessl/npm-babylonjs--loaders

Babylon.js loaders module providing support for importing various 3D file formats including glTF, BVH, OBJ, STL, and SPLAT into Babylon.js 3D scenes

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@babylonjs/loaders@8.26.x

To install, run

npx @tessl/cli install tessl/npm-babylonjs--loaders@8.26.0

index.mddocs/

Babylon.js Loaders

The Babylon.js Loaders module provides comprehensive 3D file format loading capabilities for the Babylon.js WebGL engine. It enables developers to import and display 3D models from various industry-standard formats including glTF/GLB, BVH motion capture data, OBJ mesh files, STL stereolithography files, and SPLAT Gaussian splatting format.

Package Information

  • Package Name: @babylonjs/loaders
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @babylonjs/core @babylonjs/loaders

Core Imports

// Import specific loader modules to extend Babylon.js capabilities
import "@babylonjs/loaders/glTF";     // glTF/GLB support
import "@babylonjs/loaders/OBJ";      // OBJ/MTL support  
import "@babylonjs/loaders/STL";      // STL support
import "@babylonjs/loaders/BVH";      // BVH motion capture support
import "@babylonjs/loaders/SPLAT";    // SPLAT/PLY support

Or import all loaders:

import "@babylonjs/loaders";

For direct API access:

import { 
  GLTFFileLoader, 
  OBJFileLoader, 
  STLFileLoader, 
  BVHFileLoader, 
  SPLATFileLoader,
  GLTFValidation,
  SolidParser,
  ReadBvh
} from "@babylonjs/loaders";

CommonJS:

require("@babylonjs/loaders/glTF");
const { GLTFFileLoader } = require("@babylonjs/loaders");

Basic Usage

The loaders integrate automatically with Babylon.js scene loading when imported. Most usage is through the standard scene loading API:

import { Engine, Scene, SceneLoader } from "@babylonjs/core";
import "@babylonjs/loaders/glTF";

const engine = new Engine(canvas, true);
const scene = new Scene(engine);

// Load a 3D model - the appropriate loader is selected automatically
const result = await SceneLoader.ImportMeshAsync(
  "", 
  "https://example.com/models/", 
  "robot.glb", 
  scene
);

const meshes = result.meshes;
const materials = result.materials;
const skeletons = result.skeletons;

For more control, loaders can be configured directly:

import { GLTFFileLoader, GLTFLoaderCoordinateSystemMode } from "@babylonjs/loaders";

const loader = new GLTFFileLoader();
loader.coordinateSystemMode = GLTFLoaderCoordinateSystemMode.FORCE_RIGHT_HANDED;
loader.animationStartMode = GLTFLoaderAnimationStartMode.ALL;

// Register the configured loader
SceneLoader.RegisterPlugin(loader);

Architecture

The Babylon.js Loaders module follows a consistent plugin architecture:

  • Scene Loader Integration: All loaders implement Babylon.js scene loader plugin interfaces for seamless integration
  • Automatic Registration: Importing a loader module automatically registers it with the scene loading system
  • File Format Detection: Loaders are selected automatically based on file extensions and content analysis
  • Async Loading: Modern Promise-based APIs with progress callbacks and observable patterns
  • Asset Containers: Support for isolated loading via AssetContainer for advanced asset management
  • Extension System: Particularly rich for glTF with 40+ extensions supporting the latest 3D web standards

Capabilities

glTF Validation

Comprehensive validation support for glTF files with detailed error reporting and configuration options.

class GLTFValidation {
  static Configuration: IGLTFValidationConfiguration;
  static ValidateAsync(
    data: string | Uint8Array, 
    rootUrl: string, 
    fileName: string, 
    getExternalResource?: (uri: string) => Promise<Uint8Array>
  ): Promise<GLTF2.IGLTFValidationResults>;
}

interface IGLTFValidationConfiguration {
  url: string;
}

enum GLTFLoaderState {
  LOADING = 0,
  READY = 1,
  COMPLETE = 2
}

interface IGLTFLoaderData {
  json: object;
  bin: Nullable<IDataBuffer>;
}

glTF/GLB Loading

Comprehensive support for GL Transmission Format, the standard for 3D model transmission. Includes extensive extension support for materials, animation, compression, and interactivity.

class GLTFFileLoader implements ISceneLoaderPluginAsync, ISceneLoaderPluginFactory {
  static IncrementalLoading: boolean;
  static HomogeneousCoordinates: boolean;
  
  coordinateSystemMode: GLTFLoaderCoordinateSystemMode;
  animationStartMode: GLTFLoaderAnimationStartMode;
  compileMaterials: boolean;
  compileShadowGenerators: boolean;
  transparencyAsCoverage: boolean;
  
  // Extended configuration properties
  loaderState: Nullable<GLTFLoaderState>;
  capturePerformanceCounters: boolean;
  loggingEnabled: boolean;
  alwaysComputeSkeletonRootNode: boolean;
  createInstances: boolean;
  loadMorphTargets: boolean;
  loadNodeAnimations: boolean;
  loadOnlyMaterials: boolean;
  loadSkins: boolean;
  targetFps: number;
  useRangeRequests: boolean;
  useSRGBBuffers: boolean;
  validate: boolean;
  useGltfTextureNames: boolean;
  
  // Observable events
  onParsedObservable: Observable<IGLTFLoaderData>;
  onCompleteObservable: Observable<void>;
  onErrorObservable: Observable<any>;
  
  importMeshAsync(meshesNames: any, scene: Scene, data: any, rootUrl: string): Promise<ISceneLoaderAsyncResult>;
  loadAsync(scene: Scene, data: any): Promise<void>;
  loadAssetContainerAsync(scene: Scene, data: any): Promise<AssetContainer>;
  createPlugin(options: SceneLoaderPluginOptions): ISceneLoaderPluginAsync;
}

enum GLTFLoaderCoordinateSystemMode {
  AUTO = 0,
  FORCE_RIGHT_HANDED = 1
}

enum GLTFLoaderAnimationStartMode {
  NONE = 0,
  FIRST = 1, 
  ALL = 2
}

glTF Loading

OBJ Parser Utilities

Advanced OBJ parsing utilities for custom processing and parsing control.

class SolidParser {
  // Static descriptors
  static ObjectDescriptor: RegExp;
  static GroupDescriptor: RegExp;
  static MtlLibGroupDescriptor: RegExp;
  static UseMtlDescriptor: RegExp;
  static SmoothDescriptor: RegExp;
  
  // Parsing patterns
  static VertexPattern: RegExp;
  static NormalPattern: RegExp;
  static UVPattern: RegExp;
  static FacePattern1: RegExp;
  static FacePattern2: RegExp;
  static FacePattern3: RegExp;
  static FacePattern4: RegExp;
  static FacePattern5: RegExp;
  static LinePattern1: RegExp;
  static LinePattern2: RegExp;
  static LinePattern3: RegExp;
  
  constructor(materialToUse: string[], babylonMeshesArray: Array<Mesh>, loadingOptions: OBJLoadingOptions);
  parse(meshesNames: any, data: string, scene: Scene, assetContainer: Nullable<AssetContainer>, onFileToLoadFound: (fileToLoad: string) => void): void;
}

type OBJLoadingOptions = {
  optimizeWithUV: boolean;
  UVScaling: Vector2;
  invertY: boolean;
  invertTextureY: boolean;
  importVertexColors: boolean;
  computeNormals: boolean;
  optimizeNormals: boolean;
  skipMaterials: boolean;
  materialLoadingFailsSilently: boolean;
  useLegacyBehavior: boolean;
};

OBJ/MTL Loading

Support for Wavefront OBJ 3D object files with associated MTL material files. Includes vertex colors, normals computation, and texture coordinate handling.

class OBJFileLoader implements ISceneLoaderPluginAsync, ISceneLoaderPluginFactory {
  static OPTIMIZE_WITH_UV: boolean;
  static INVERT_Y: boolean;
  static IMPORT_VERTEX_COLORS: boolean;
  static COMPUTE_NORMALS: boolean;
  static UV_SCALING: Vector2;
  static SKIP_MATERIALS: boolean;
  
  importMeshAsync(meshesNames: any, scene: Scene, data: any, rootUrl: string): Promise<ISceneLoaderAsyncResult>;
  loadAsync(scene: Scene, data: any): Promise<void>;
  loadAssetContainerAsync(scene: Scene, data: any): Promise<AssetContainer>;
}

class MTLFileLoader {
  static INVERT_TEXTURE_Y: boolean;
  materials: StandardMaterial[];
  
  parseMTL(scene: Scene, data: string | ArrayBuffer, rootUrl: string, assetContainer: Nullable<AssetContainer>): void;
}

OBJ Loading

STL Loading

Support for STL (stereolithography) files commonly used in 3D printing and CAD applications.

class STLFileLoader implements ISceneLoaderPlugin {
  static DO_NOT_ALTER_FILE_COORDINATES: boolean;
  
  importMesh(meshesNames: any, scene: Scene, data: any, rootUrl: string, meshes: AbstractMesh[]): boolean;
  loadAssetContainer(scene: Scene, data: any, rootUrl: string): AssetContainer;
}

STL Loading

BVH Motion Capture Loading

Support for BVH (Biovision Hierarchy) motion capture files for skeletal animation.

class BVHFileLoader implements ISceneLoaderPluginAsync, ISceneLoaderPluginFactory {
  constructor(loadingOptions?: Partial<Readonly<BVHLoadingOptions>>);
  
  importMeshAsync(meshesNames: any, scene: Scene, data: any, rootUrl: string): Promise<ISceneLoaderAsyncResult>;
  loadAsync(scene: Scene, data: any): Promise<void>;
  loadAssetContainerAsync(scene: Scene, data: any): Promise<AssetContainer>;
}

function ReadBvh(text: string, scene: Scene, assetContainer: Nullable<AssetContainer>, loadingOptions: BVHLoadingOptions): Skeleton;

type BVHLoadingOptions = {
  loopMode: number; // Uses Animation.ANIMATIONLOOPMODE_* constants
};

BVH Loading

SPLAT/Gaussian Splatting Loading

Support for SPLAT, PLY, and SPZ files used in Gaussian splatting for neural 3D scene representation.

class SPLATFileLoader implements ISceneLoaderPluginAsync, ISceneLoaderPluginFactory {
  constructor(loadingOptions?: Partial<Readonly<SPLATLoadingOptions>>);
  
  importMeshAsync(meshesNames: any, scene: Scene, data: any, rootUrl: string): Promise<ISceneLoaderAsyncResult>;
  loadAsync(scene: Scene, data: any): Promise<void>;
  loadAssetContainerAsync(scene: Scene, data: any): Promise<AssetContainer>;
}

type SPLATLoadingOptions = {
  keepInRam?: boolean;
  flipY?: boolean;
};

SPLAT Loading

Common Types

interface ISceneLoaderProgressEvent {
  /** Whether the progress can be measured accurately */
  lengthComputable: boolean;
  /** Number of bytes loaded so far */
  loaded: number;
  /** Total number of bytes to load */
  total: number;
}

interface ImageProcessingConfiguration {
  /** Enable/disable color curves */
  colorCurvesEnabled: boolean;
  /** Enable/disable color grading */
  colorGradingEnabled: boolean;
  /** Enable/disable tone mapping */
  toneMappingEnabled: boolean;
  /** Exposure level */
  exposure: number;
  /** Contrast level */
  contrast: number;
}

class Vector2 {
  constructor(x: number, y: number);
  x: number;
  y: number;
  
  /** Set both x and y components */
  setAll(value: number): Vector2;
  /** Subtract another Vector2 from this one */
  subtractInPlace(other: Vector2): Vector2;
}

class Vector3 {
  constructor(x: number, y: number, z: number);
  x: number;
  y: number;
  z: number;
  
  /** Zero vector constant */
  static Zero(): Vector3;
  /** Set all components */
  set(x: number, y: number, z: number): Vector3;
  /** Subtract another Vector3 from this one */
  subtractInPlace(other: Vector3): Vector3;
}

enum Animation {
  /** Animation plays once and stops */
  ANIMATIONLOOPMODE_ONCE = 1,
  /** Animation loops continuously */
  ANIMATIONLOOPMODE_CYCLE = 2,
  /** Animation plays relative to current state */
  ANIMATIONLOOPMODE_RELATIVE = 3
}

interface ISceneLoaderAsyncResult {
  meshes: AbstractMesh[];
  particleSystems: IParticleSystem[];
  skeletons: Skeleton[];
  animationGroups: AnimationGroup[];
  materials: Material[];
  textures: BaseTexture[];
  lights: Light[];
  transformNodes: TransformNode[];
  geometries: Geometry[];
}

interface ISceneLoaderPluginAsync {
  name: string;
  extensions: string | { [key: string]: { isBinary: boolean } };
  
  importMeshAsync(meshesNames: any, scene: Scene, data: any, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<ISceneLoaderAsyncResult>;
  loadAsync(scene: Scene, data: any, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<void>;
  loadAssetContainerAsync(scene: Scene, data: any, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): Promise<AssetContainer>;
}

interface ISceneLoaderPlugin {
  name: string;
  extensions: string | { [key: string]: { isBinary: boolean } };
  
  importMesh(meshesNames: any, scene: Scene, data: any, rootUrl: string, meshes: AbstractMesh[], onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): boolean;
  load(scene: Scene, data: any, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): boolean;
  loadAssetContainer(scene: Scene, data: any, rootUrl: string, onProgress?: (event: ISceneLoaderProgressEvent) => void, fileName?: string): AssetContainer;
}

interface ISceneLoaderPluginFactory {
  createPlugin(options: SceneLoaderPluginOptions): ISceneLoaderPluginAsync | ISceneLoaderPlugin;
}

interface GLTFLoaderExtensionOptions extends Record<string, Record<string, unknown> | undefined> {}

interface SceneLoaderPluginOptions {
  [key: string]: any;
}

interface IGLTFLoaderExtension {
  readonly name: string;
  enabled: boolean;
  order?: number;
}

// Additional metadata constants
interface BVHFileLoaderMetadata {
  name: string;
}

interface GLTFFileLoaderMetadata {
  name: string;
}

interface OBJFileLoaderMetadata {
  name: string;
}

interface STLFileLoaderMetadata {
  name: string;
}

interface SPLATFileLoaderMetadata {
  name: string;
}