
Threejs Syntax Loaders
- 18 installs
- 11 repo stars
- Updated July 8, 2026
- openaec-foundation/three.js-claude-skill-package
Helps with ai & agent building tasks.
About
threejs-syntax-loaders is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.
- threejs-syntax-loaders
- AI & Agent Building
- AI-coding skill
Threejs Syntax Loaders by the numbers
- 18 all-time installs (skills.sh)
- +2 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #10,710 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/openaec-foundation/three.js-claude-skill-package --skill threejs-syntax-loadersAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 18 |
|---|---|
| repo stars | ★ 11 |
| Last updated | July 8, 2026 |
| Repository | openaec-foundation/three.js-claude-skill-package ↗ |
What it does
Helps with ai & agent building tasks.
Files
threejs-syntax-loaders
Quick Reference
Loader Architecture
All Three.js loaders extend the Loader base class and share two loading patterns:
// Callback style
loader.load(url, onLoad, onProgress, onError);
// Promise style (preferred)
const result = await loader.loadAsync(url, onProgress);Import Paths
| Loader | Import |
|---|---|
TextureLoader | import { TextureLoader } from 'three'; |
CubeTextureLoader | import { CubeTextureLoader } from 'three'; |
GLTFLoader | import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'; |
DRACOLoader | import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js'; |
KTX2Loader | import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js'; |
FBXLoader | import { FBXLoader } from 'three/addons/loaders/FBXLoader.js'; |
OBJLoader | import { OBJLoader } from 'three/addons/loaders/OBJLoader.js'; |
MTLLoader | import { MTLLoader } from 'three/addons/loaders/MTLLoader.js'; |
RGBELoader | import { RGBELoader } from 'three/addons/loaders/RGBELoader.js'; |
MeshoptDecoder | import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js'; |
Format Recommendation
ALWAYS prefer glTF/GLB over other 3D formats. glTF is the recommended format for Three.js. It supports PBR materials, animations, cameras, lights, and scene hierarchy in a single file. Use .glb (binary glTF) for single-file distribution.
Critical Warnings
NEVER call loader.load() inside requestAnimationFrame or any render loop. Load assets once at initialization and cache the result.
NEVER forget to set the DRACOLoader decoder path before loading Draco-compressed models. The path MUST point to a directory containing draco_decoder.wasm.
NEVER skip error handling on loadAsync calls. ALWAYS wrap in try/catch. Failed loads without error handlers crash silently.
NEVER forget to dispose loaded models when removing them. GLTF models contain meshes, materials, and textures that ALL require disposal.
ALWAYS set texture.colorSpace = THREE.SRGBColorSpace on diffuse/color textures (map, emissiveMap). NEVER set SRGBColorSpace on data textures (normalMap, roughnessMap, metalnessMap, aoMap).
ALWAYS call dracoLoader.dispose() after all Draco-compressed models are loaded to free the WASM decoder memory.
---
Loader Base Class
Every loader inherits these methods from Loader:
| Method | Signature | Purpose |
|---|---|---|
load | (url, onLoad, onProgress, onError) | Callback-based loading |
loadAsync | (url, onProgress) => Promise | Promise-based loading |
setPath | (path: string) | Set base URL prefix for all loads |
setResourcePath | (path: string) | Set resource resolution path |
setCrossOrigin | (value: string) | Set CORS mode |
setWithCredentials | (value: boolean) | Enable credentials for cross-origin |
setRequestHeader | (header: object) | Set custom HTTP headers |
---
LoadingManager
Coordinates multiple loaders and tracks overall progress.
import * as THREE from 'three';
const manager = new THREE.LoadingManager(
() => { console.log('All assets loaded'); },
(url, loaded, total) => { console.log(`Progress: ${loaded}/${total}`); },
(url) => { console.error(`Failed to load: ${url}`); }
);
// Pass manager to any loader
const textureLoader = new THREE.TextureLoader(manager);
const gltfLoader = new GLTFLoader(manager);Manager Callbacks
| Callback | Signature | When |
|---|---|---|
onStart | (url, itemsLoaded, itemsTotal) | First item begins loading |
onLoad | () | All items finished |
onProgress | (url, itemsLoaded, itemsTotal) | Each item completes |
onError | (url) | An item fails |
Manager Methods
| Method | Purpose |
|---|---|
itemStart(url) | Manually register a loading item |
itemEnd(url) | Manually mark item as loaded |
itemError(url) | Manually mark item as failed |
resolveURL(url) | Resolve URL through modifiers |
setURLModifier(callback) | Custom URL rewriting (blob URLs, service workers) |
---
GLTFLoader
The primary loader for 3D models. glTF 2.0 supports meshes, PBR materials, animations, cameras, lights, and scene hierarchy.
Setup with Draco Compression
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/');
const gltfLoader = new GLTFLoader();
gltfLoader.setDRACOLoader(dracoLoader);Setup with KTX2 Textures
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');
ktx2Loader.detectSupport(renderer); // MUST pass renderer instance
gltfLoader.setKTX2Loader(ktx2Loader);Setup with Meshopt Decoder
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
await MeshoptDecoder.ready;
gltfLoader.setMeshoptDecoder(MeshoptDecoder);Loading a Model
try {
const gltf = await gltfLoader.loadAsync('model.glb');
scene.add(gltf.scene);
} catch (error) {
console.error('Failed to load model:', error);
}GLTF Result Object
{
scene: THREE.Group, // Root scene node -- add this to your scene
scenes: THREE.Group[], // All scenes in the file
cameras: THREE.Camera[], // Embedded cameras
animations: THREE.AnimationClip[], // Animation data for AnimationMixer
asset: { generator: string, version: string }, // File metadata
parser: GLTFParser, // Internal parser (advanced use)
userData: {} // Custom glTF extensions
}GLTFLoader Methods
| Method | Signature | Purpose |
|---|---|---|
load | (url, onLoad, onProgress, onError) | Load with callbacks |
loadAsync | (url, onProgress) => Promise<GLTF> | Load with Promise |
parse | (data, path, onLoad, onError) | Parse ArrayBuffer or JSON directly |
setDRACOLoader | (dracoLoader: DRACOLoader) | Enable Draco decompression |
setKTX2Loader | (ktx2Loader: KTX2Loader) | Enable KTX2 texture decompression |
setMeshoptDecoder | (decoder) | Enable meshopt decompression |
register | (plugin) | Register a glTF extension plugin |
unregister | (plugin) | Unregister a glTF extension plugin |
---
DRACOLoader
Decodes Draco-compressed geometry. Reduces mesh file size by 80-90%.
| Method | Signature | Purpose |
|---|---|---|
setDecoderPath | (path: string) | Path to directory containing WASM decoders |
setDecoderConfig | (config: object) | `{ type: 'js' \ |
preload | () | Pre-fetch decoder WASM before first use |
dispose | () | Free WASM decoder memory |
ALWAYS call dracoLoader.dispose() after loading all Draco-compressed models.
---
TextureLoader
Loads 2D textures (PNG, JPG, WebP) into THREE.Texture.
const loader = new THREE.TextureLoader();
const texture = await loader.loadAsync('diffuse.jpg');
texture.colorSpace = THREE.SRGBColorSpace; // ALWAYS for color textures
texture.wrapS = THREE.RepeatWrapping;
texture.wrapT = THREE.RepeatWrapping;
material.map = texture;---
CubeTextureLoader
Loads six images as a cube map for skyboxes or environment reflections.
const cubeLoader = new THREE.CubeTextureLoader();
cubeLoader.setPath('/textures/cube/');
const cubeTexture = cubeLoader.load([
'px.jpg', 'nx.jpg', // positive-x, negative-x
'py.jpg', 'ny.jpg', // positive-y, negative-y
'pz.jpg', 'nz.jpg' // positive-z, negative-z
]);
scene.background = cubeTexture;
scene.environment = cubeTexture;---
RGBELoader
Loads HDR environment maps in Radiance .hdr format.
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
const rgbeLoader = new RGBELoader();
rgbeLoader.load('environment.hdr', (texture) => {
texture.mapping = THREE.EquirectangularReflectionMapping;
scene.environment = texture; // PBR environment lighting
scene.background = texture; // Optional: visible HDR background
});The RGBELoader sets color space automatically. NEVER manually override the color space on HDR textures.
---
FBXLoader
Loads Autodesk FBX models. Supports meshes, materials, and skeletal animations.
import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
const fbxLoader = new FBXLoader();
const model = await fbxLoader.loadAsync('character.fbx');
scene.add(model);---
OBJLoader + MTLLoader
Loads Wavefront OBJ geometry with optional MTL material files.
import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
const mtlLoader = new MTLLoader();
const materials = await mtlLoader.loadAsync('model.mtl');
materials.preload();
const objLoader = new OBJLoader();
objLoader.setMaterials(materials);
const model = await objLoader.loadAsync('model.obj');
scene.add(model);ALWAYS load the MTL file first, then pass the materials to OBJLoader before loading the OBJ file.
---
Disposing Loaded Models
ALWAYS traverse and dispose ALL resources when removing a loaded model:
function disposeModel(model) {
model.traverse((child) => {
if (child.isMesh) {
child.geometry.dispose();
if (Array.isArray(child.material)) {
child.material.forEach((mat) => {
disposeMaterial(mat);
});
} else {
disposeMaterial(child.material);
}
}
});
model.removeFromParent();
}
function disposeMaterial(material) {
for (const key of Object.keys(material)) {
const value = material[key];
if (value && typeof value === 'object' && 'dispose' in value) {
value.dispose(); // Disposes textures
}
}
material.dispose();
}---
Reference Links
- references/methods.md -- Complete API signatures for all loaders
- references/examples.md -- Working code examples for common loading scenarios
- references/anti-patterns.md -- What NOT to do when loading assets
Official Sources
- https://threejs.org/docs/#api/en/loaders/Loader
- https://threejs.org/docs/#api/en/loaders/LoadingManager
- https://threejs.org/docs/#api/en/loaders/TextureLoader
- https://threejs.org/docs/#examples/en/loaders/GLTFLoader
- https://threejs.org/docs/#examples/en/loaders/DRACOLoader
- https://threejs.org/docs/#examples/en/loaders/KTX2Loader
- https://threejs.org/docs/#examples/en/loaders/FBXLoader
- https://threejs.org/docs/#examples/en/loaders/OBJLoader
- https://threejs.org/docs/#examples/en/loaders/RGBELoader
threejs-syntax-loaders — Anti-Patterns
Anti-Pattern 1: Loading Assets in the Render Loop
WRONG:
function animate() {
requestAnimationFrame(animate);
// WRONG: creates a new load request every frame (60+ times per second)
loader.load('model.glb', (gltf) => {
scene.add(gltf.scene);
});
renderer.render(scene, camera);
}WHY: Each frame spawns a new HTTP request and parse operation. This floods the network, consumes unbounded memory, and adds duplicate objects to the scene every frame.
CORRECT:
// Load ONCE during initialization
const gltf = await gltfLoader.loadAsync('model.glb');
scene.add(gltf.scene);
// Render loop does NOT load anything
function animate() {
requestAnimationFrame(animate);
renderer.render(scene, camera);
}---
Anti-Pattern 2: Missing DRACOLoader Decoder Path
WRONG:
const dracoLoader = new DRACOLoader();
// Forgot to call setDecoderPath()
gltfLoader.setDRACOLoader(dracoLoader);
const gltf = await gltfLoader.loadAsync('compressed.glb');
// Runtime error: decoder WASM not foundWHY: Draco decompression requires WASM files (draco_decoder.wasm, draco_wasm_wrapper.js). Without the correct path, loading silently fails or throws a cryptic error.
CORRECT:
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/');
gltfLoader.setDRACOLoader(dracoLoader);---
Anti-Pattern 3: Not Disposing Loaded Models
WRONG:
// Remove model from scene but forget to dispose GPU resources
scene.remove(model);
// GPU memory leak: geometry buffers, shader programs, and textures remain allocatedWHY: Removing an object from the scene does NOT free GPU memory. Geometry, materials, and textures MUST be explicitly disposed. Repeated load-remove cycles without disposal cause the application to run out of GPU memory and crash.
CORRECT:
function disposeModel(model) {
model.traverse((child) => {
if (child.isMesh) {
child.geometry.dispose();
if (Array.isArray(child.material)) {
child.material.forEach((mat) => {
Object.values(mat).forEach((val) => {
if (val && typeof val === 'object' && 'dispose' in val) {
val.dispose();
}
});
mat.dispose();
});
} else {
Object.values(child.material).forEach((val) => {
if (val && typeof val === 'object' && 'dispose' in val) {
val.dispose();
}
});
child.material.dispose();
}
}
});
model.removeFromParent();
}---
Anti-Pattern 4: No Error Handling on loadAsync
WRONG:
// No try/catch -- if the file does not exist, the promise rejects silently
const gltf = await gltfLoader.loadAsync('missing-model.glb');
scene.add(gltf.scene);
// Unhandled promise rejection -- may crash the applicationWHY: Network failures, 404 responses, and corrupt files cause unhandled promise rejections. In strict environments this crashes the application. Without error handling, there is no feedback about what went wrong.
CORRECT:
try {
const gltf = await gltfLoader.loadAsync('model.glb');
scene.add(gltf.scene);
} catch (error) {
console.error('Failed to load model:', error);
// Show fallback geometry or user-facing error message
}---
Anti-Pattern 5: Wrong Color Space on Data Textures
WRONG:
const normalMap = await loader.loadAsync('normal.jpg');
normalMap.colorSpace = THREE.SRGBColorSpace; // WRONG for data texturesWHY: Normal maps, roughness maps, metalness maps, AO maps, and other non-color textures store mathematical data, not visible colors. Setting SRGBColorSpace applies gamma correction that corrupts the data values, causing incorrect lighting, broken normals, or washed-out PBR rendering.
CORRECT:
// Color textures: ALWAYS set SRGBColorSpace
const diffuse = await loader.loadAsync('diffuse.jpg');
diffuse.colorSpace = THREE.SRGBColorSpace;
// Data textures: NEVER set SRGBColorSpace -- leave at default
const normalMap = await loader.loadAsync('normal.jpg');
// normalMap.colorSpace stays at NoColorSpace (default)---
Anti-Pattern 6: Not Disposing DRACOLoader After Use
WRONG:
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('/draco/');
gltfLoader.setDRACOLoader(dracoLoader);
await gltfLoader.loadAsync('model1.glb');
await gltfLoader.loadAsync('model2.glb');
// WASM decoder stays in memory foreverWHY: The DRACOLoader spawns Web Workers with WASM decoders. If not disposed after loading is complete, these workers and their WASM memory remain allocated for the entire application lifetime.
CORRECT:
await gltfLoader.loadAsync('model1.glb');
await gltfLoader.loadAsync('model2.glb');
// All Draco models loaded -- free decoder resources
dracoLoader.dispose();---
Anti-Pattern 7: Loading .gltf Without .bin Companion
WRONG:
/models/
scene.gltf <-- deployed
// scene.bin <-- MISSINGWHY: Separated .gltf files reference an external .bin file for mesh data. If the .bin file is missing, the loader fails with a network error. This is a common deployment mistake.
CORRECT: Use .glb (binary GLTF) for single-file distribution, or ensure both .gltf and .bin files are deployed together.
// Preferred: single-file binary format
const gltf = await gltfLoader.loadAsync('scene.glb');---
Anti-Pattern 8: Loading OBJ Before MTL
WRONG:
// Loading OBJ first -- materials are not available
const model = await objLoader.loadAsync('model.obj');
// Now loading MTL after the fact -- too late
const materials = await mtlLoader.loadAsync('model.mtl');
// model already has default white materialsWHY: OBJLoader assigns materials at parse time. If MTL materials are not set on the loader before calling load(), all meshes get default white MeshPhongMaterial.
CORRECT:
// ALWAYS load MTL first
const materials = await mtlLoader.loadAsync('model.mtl');
materials.preload();
objLoader.setMaterials(materials);
// Then load OBJ -- materials are applied during parsing
const model = await objLoader.loadAsync('model.obj');---
Anti-Pattern 9: Forgetting KTX2Loader.detectSupport()
WRONG:
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');
// Forgot detectSupport() -- transcoder does not know which GPU formats are available
gltfLoader.setKTX2Loader(ktx2Loader);WHY: KTX2 textures are transcoded to GPU-native compressed formats (BC, ETC, ASTC). Without calling detectSupport(renderer), the transcoder does not know which formats the GPU supports and either fails or picks a suboptimal fallback.
CORRECT:
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');
ktx2Loader.detectSupport(renderer); // MUST pass the renderer instance
gltfLoader.setKTX2Loader(ktx2Loader);---
Anti-Pattern 10: Missing CORS Headers for Cross-Origin Assets
WRONG:
// Loading from a different domain without CORS
const texture = loader.load('https://other-domain.com/texture.jpg');
// Fails silently or shows security errorWHY: Browsers block cross-origin resource loading unless the server sends proper CORS headers (Access-Control-Allow-Origin). Texture loads fail silently, resulting in black or missing textures with no console error in some cases.
CORRECT:
// Option 1: Serve assets from the same origin
const texture = loader.load('/textures/texture.jpg');
// Option 2: Configure CORS on the loader and ensure server sends CORS headers
loader.setCrossOrigin('anonymous');
const texture = loader.load('https://cdn.example.com/texture.jpg');
// Server MUST respond with: Access-Control-Allow-Origin: *threejs-syntax-loaders — Examples
Example 1: Load GLTF with Draco Compression and Error Handling
The most common loading pattern: GLTF model with Draco-compressed geometry.
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
// Set up Draco decoder
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/');
dracoLoader.preload(); // Pre-fetch WASM for faster first load
// Set up GLTF loader
const gltfLoader = new GLTFLoader();
gltfLoader.setDRACOLoader(dracoLoader);
// Load model
try {
const gltf = await gltfLoader.loadAsync('/models/building.glb');
// Add to scene
scene.add(gltf.scene);
// Access animations if present
if (gltf.animations.length > 0) {
const mixer = new THREE.AnimationMixer(gltf.scene);
gltf.animations.forEach((clip) => {
mixer.clipAction(clip).play();
});
}
// Access embedded cameras if present
if (gltf.cameras.length > 0) {
const embeddedCamera = gltf.cameras[0];
}
} catch (error) {
console.error('Failed to load GLTF model:', error);
}
// After all models are loaded, free WASM decoder memory
dracoLoader.dispose();---
Example 2: LoadingManager with Progress Tracking
Track loading progress across multiple loaders for a loading screen.
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
const progressBar = document.getElementById('progress-bar');
const loadingScreen = document.getElementById('loading-screen');
const manager = new THREE.LoadingManager();
manager.onStart = (url, loaded, total) => {
loadingScreen.style.display = 'flex';
};
manager.onProgress = (url, loaded, total) => {
const percent = (loaded / total) * 100;
progressBar.style.width = `${percent}%`;
};
manager.onLoad = () => {
loadingScreen.style.display = 'none';
};
manager.onError = (url) => {
console.error(`Failed to load: ${url}`);
};
// All loaders share the same manager
const textureLoader = new THREE.TextureLoader(manager);
const gltfLoader = new GLTFLoader(manager);
const rgbeLoader = new RGBELoader(manager);
// Load assets -- manager tracks all of them
const diffuse = textureLoader.load('/textures/diffuse.jpg');
const normal = textureLoader.load('/textures/normal.jpg');
gltfLoader.load('/models/scene.glb', (gltf) => { scene.add(gltf.scene); });
rgbeLoader.load('/env/studio.hdr', (texture) => {
texture.mapping = THREE.EquirectangularReflectionMapping;
scene.environment = texture;
});---
Example 3: HDR Environment Map with RGBELoader
Load an HDR environment map for physically-based lighting and reflections.
import * as THREE from 'three';
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;
const rgbeLoader = new RGBELoader();
rgbeLoader.load('/environments/sunset.hdr', (texture) => {
texture.mapping = THREE.EquirectangularReflectionMapping;
// Use as environment lighting (affects all PBR materials)
scene.environment = texture;
// Optionally use as visible background
scene.background = texture;
});---
Example 4: OBJ with MTL Materials
Load a Wavefront OBJ file with its companion MTL material file.
import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
// ALWAYS load MTL first, then OBJ
const mtlLoader = new MTLLoader();
mtlLoader.setPath('/models/');
try {
const materials = await mtlLoader.loadAsync('furniture.mtl');
materials.preload();
const objLoader = new OBJLoader();
objLoader.setMaterials(materials);
objLoader.setPath('/models/');
const model = await objLoader.loadAsync('furniture.obj');
scene.add(model);
} catch (error) {
console.error('Failed to load OBJ/MTL:', error);
}---
Example 5: Full Loader Setup with KTX2 and Meshopt
Complete production loader setup supporting all compression formats.
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
// Draco decoder for compressed geometry
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/');
// KTX2 transcoder for compressed textures
const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');
ktx2Loader.detectSupport(renderer); // MUST pass renderer
// Meshopt decoder
await MeshoptDecoder.ready;
// Configure GLTF loader with all decoders
const gltfLoader = new GLTFLoader();
gltfLoader.setDRACOLoader(dracoLoader);
gltfLoader.setKTX2Loader(ktx2Loader);
gltfLoader.setMeshoptDecoder(MeshoptDecoder);
// Now load any GLTF/GLB -- compressed or uncompressed
try {
const gltf = await gltfLoader.loadAsync('/models/optimized-scene.glb');
scene.add(gltf.scene);
} catch (error) {
console.error('Model loading failed:', error);
}
// Cleanup after all loading is complete
dracoLoader.dispose();
ktx2Loader.dispose();---
Example 6: Texture Loading with Correct Color Spaces
Load textures with proper color space assignments for PBR materials.
import * as THREE from 'three';
const loader = new THREE.TextureLoader();
// Color textures: ALWAYS set SRGBColorSpace
const diffuseMap = await loader.loadAsync('/textures/wood_diffuse.jpg');
diffuseMap.colorSpace = THREE.SRGBColorSpace;
// Data textures: NEVER set SRGBColorSpace -- leave at default (NoColorSpace)
const normalMap = await loader.loadAsync('/textures/wood_normal.jpg');
const roughnessMap = await loader.loadAsync('/textures/wood_roughness.jpg');
const aoMap = await loader.loadAsync('/textures/wood_ao.jpg');
const material = new THREE.MeshStandardMaterial({
map: diffuseMap,
normalMap: normalMap,
roughnessMap: roughnessMap,
aoMap: aoMap,
});---
Example 7: Cubemap Skybox
Load a six-image cubemap as scene background.
import * as THREE from 'three';
const cubeLoader = new THREE.CubeTextureLoader();
cubeLoader.setPath('/textures/skybox/');
const skybox = cubeLoader.load([
'px.jpg', 'nx.jpg', // right, left
'py.jpg', 'ny.jpg', // top, bottom
'pz.jpg', 'nz.jpg' // front, back
]);
scene.background = skybox;
scene.environment = skybox; // Also use for reflectionsthreejs-syntax-loaders — Methods Reference
Loader Base Class
All loaders inherit from THREE.Loader.
Constructor
new THREE.Loader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
load | (url: string, onLoad: Function, onProgress?: Function, onError?: Function) | void | Load asset with callbacks |
loadAsync | (url: string, onProgress?: Function) | Promise<any> | Load asset with Promise |
setPath | (path: string) | this | Set base URL prefix prepended to all load URLs |
setResourcePath | (path: string) | this | Set path for resolving referenced resources (textures in models) |
setCrossOrigin | (value: string) | this | Set CORS mode ('anonymous' or 'use-credentials') |
setWithCredentials | (value: boolean) | this | Enable credentials for cross-origin requests |
setRequestHeader | (header: object) | this | Set custom HTTP headers as key-value pairs |
Properties
| Property | Type | Description |
|---|---|---|
manager | LoadingManager | The LoadingManager instance for this loader |
crossOrigin | string | CORS mode |
withCredentials | boolean | Credentials flag |
path | string | Base path prefix |
resourcePath | string | Resource resolution path |
requestHeader | object | Custom HTTP headers |
---
LoadingManager
Constructor
new THREE.LoadingManager(
onLoad?: () => void,
onProgress?: (url: string, itemsLoaded: number, itemsTotal: number) => void,
onError?: (url: string) => void
)Callbacks (assignable properties)
| Callback | Signature | When Invoked |
|---|---|---|
onStart | (url: string, itemsLoaded: number, itemsTotal: number) => void | First item begins loading |
onLoad | () => void | All items finished loading |
onProgress | (url: string, itemsLoaded: number, itemsTotal: number) => void | Each individual item completes |
onError | (url: string) => void | An item fails to load |
Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
itemStart | (url: string) | void | Manually register a loading item |
itemEnd | (url: string) | void | Manually mark item as loaded |
itemError | (url: string) | void | Manually mark item as failed |
resolveURL | (url: string) | string | Resolve URL through any registered URL modifier |
setURLModifier | (callback: (url: string) => string) | this | Register custom URL rewriting function |
addHandler | (regex: RegExp, loader: Loader) | this | Auto-select loader by filename pattern |
removeHandler | (regex: RegExp) | this | Remove a registered handler |
---
GLTFLoader
Constructor
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
new GLTFLoader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
load | (url: string, onLoad: (gltf: GLTF) => void, onProgress?: Function, onError?: Function) | void | Load glTF/GLB with callbacks |
loadAsync | (url: string, onProgress?: Function) | Promise<GLTF> | Load glTF/GLB with Promise |
parse | `(data: ArrayBuffer \ | string, path: string, onLoad: (gltf: GLTF) => void, onError?: Function)` | void |
setDRACOLoader | (dracoLoader: DRACOLoader) | this | Enable Draco geometry decompression |
setKTX2Loader | (ktx2Loader: KTX2Loader) | this | Enable KTX2 texture decompression |
setMeshoptDecoder | (decoder: typeof MeshoptDecoder) | this | Enable meshopt geometry decompression |
register | (plugin: (parser: GLTFParser) => GLTFLoaderPlugin) | this | Register glTF extension plugin |
unregister | (plugin: (parser: GLTFParser) => GLTFLoaderPlugin) | this | Unregister glTF extension plugin |
GLTF Result Object
interface GLTF {
scene: THREE.Group; // Root scene node
scenes: THREE.Group[]; // All scenes in file
cameras: THREE.Camera[]; // Embedded cameras
animations: THREE.AnimationClip[]; // Animation clips
asset: {
generator: string;
version: string; // glTF spec version (e.g., "2.0")
};
parser: GLTFParser; // Internal parser (advanced)
userData: Record<string, any>; // Custom extension data
}---
DRACOLoader
Constructor
import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
new DRACOLoader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
setDecoderPath | (path: string) | this | Path to directory containing draco_decoder.wasm and draco_wasm_wrapper.js |
setDecoderConfig | `(config: { type: 'js' \ | 'wasm' })` | this |
preload | () | this | Pre-fetch decoder before first load (reduces first-load latency) |
dispose | () | void | Free WASM decoder memory and terminate worker |
load | (url: string, onLoad: Function, onProgress?: Function, onError?: Function) | void | Load Draco-compressed geometry |
loadAsync | (url: string, onProgress?: Function) | Promise<BufferGeometry> | Load with Promise |
---
KTX2Loader
Constructor
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
new KTX2Loader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
setTranscoderPath | (path: string) | this | Path to Basis Universal transcoder files |
detectSupport | (renderer: WebGLRenderer) | this | Detect GPU compressed texture support -- MUST call before loading |
load | (url: string, onLoad: Function, onProgress?: Function, onError?: Function) | void | Load KTX2 texture |
loadAsync | (url: string, onProgress?: Function) | Promise<CompressedTexture> | Load with Promise |
dispose | () | void | Free transcoder resources |
---
TextureLoader
Constructor
new THREE.TextureLoader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
load | (url: string, onLoad?: (texture: Texture) => void, onProgress?: Function, onError?: Function) | Texture | Load texture -- returns Texture immediately (populated async) |
loadAsync | (url: string, onProgress?: Function) | Promise<Texture> | Load texture with Promise |
---
CubeTextureLoader
Constructor
new THREE.CubeTextureLoader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
load | (urls: string[6], onLoad?: Function, onProgress?: Function, onError?: Function) | CubeTexture | Load 6 images as cube map. Order: px, nx, py, ny, pz, nz |
loadAsync | (urls: string[6], onProgress?: Function) | Promise<CubeTexture> | Load with Promise |
setPath | (path: string) | this | Base path prepended to each URL |
---
RGBELoader
Constructor
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
new RGBELoader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
load | (url: string, onLoad?: (texture: DataTexture) => void, onProgress?: Function, onError?: Function) | void | Load .hdr file |
loadAsync | (url: string, onProgress?: Function) | Promise<DataTexture> | Load with Promise |
setDataType | (type: number) | this | Set texture data type (e.g., THREE.HalfFloatType) |
---
FBXLoader
Constructor
import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
new FBXLoader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
load | (url: string, onLoad?: (group: Group) => void, onProgress?: Function, onError?: Function) | void | Load FBX model |
loadAsync | (url: string, onProgress?: Function) | Promise<Group> | Load with Promise |
parse | (data: ArrayBuffer, path: string) | Group | Parse raw FBX data |
---
OBJLoader
Constructor
import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
new OBJLoader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
load | (url: string, onLoad?: (group: Group) => void, onProgress?: Function, onError?: Function) | void | Load OBJ file |
loadAsync | (url: string, onProgress?: Function) | Promise<Group> | Load with Promise |
parse | (data: string) | Group | Parse OBJ text data |
setMaterials | (materials: MTLLoader.MaterialCreator) | this | Assign materials loaded from MTL file |
---
MTLLoader
Constructor
import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
new MTLLoader(manager?: THREE.LoadingManager)Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
load | (url: string, onLoad?: (creator: MaterialCreator) => void, onProgress?: Function, onError?: Function) | void | Load MTL material file |
loadAsync | (url: string, onProgress?: Function) | Promise<MaterialCreator> | Load with Promise |
parse | (data: string, path: string) | MaterialCreator | Parse MTL text data |
setMaterialOptions | (options: object) | this | Set material creation options |
MaterialCreator Methods
| Method | Signature | Returns | Description |
|---|---|---|---|
preload | () | void | Create all materials from parsed data |
getAsArray | () | Material[] | Get all materials as array |
create | (name: string) | Material | Create a specific material by name |