CtrlK
BlogDocsLog inGet started
Tessl Logo

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
}

docs

bvh-loading.md

gltf-loading.md

index.md

obj-loading.md

splat-loading.md

stl-loading.md

tile.json