@thibka/three-multiloader

three-multiloader

Three.js loading manager for textures, basis textures, cube textures, images, videos, and GLTF files.

Install

npm i @thibka/three-multiloader

Usage

import MultiLoader from '@thibka/three-multiloader'

let options = {
    progressBar: true,
    logs: true
}
let loader = new MultiLoader( options )

loader.onLoaded.add( callbackFunction )

loader.load([
    // textures
    { alias: 'cat', type: 'texture', path: 'path/to/texture.jpg' },
    { type: 'texture', path: 'path/to/texture.basis' }, // if no alias is used, the asset name will be its path
    { type: 'texture', path: 'path/to/texture.png', encoding: THREE.sRGBEncoding }, // encoding can be provided right away, default is THREE.LinearEncoding

    // images
    { alias: 'dog', type: 'image', path: 'path/to/image.jpg' },

    // glb files
    { alias: 'main-scene', type: 'gltf', path: 'path/to/model.glb' },

    // videos
    // The 'loadEvent' property can be any video event ('loadedmetadata', 'canplaythrough', etc.) 
    // and will define when the video is considered to be loaded.
    // Default is 'loadedmetadata'.
    { alias: 'my-video', type: 'video', path: './path/to/video.mp4', loadEvent: 'loadedmetadata' },
])

function callbackFunction() {
    console.log(loader.textures['cat']);
    console.log(loader.textures['path/to/texture.basis']);
    console.log(loader.images['dog']);
    console.log(loader.models['main-scene']);
    console.log(loader.cubeTextures['skybox']);
    console.log(loader.videos['my-video']);
}

Loading progress bar

Default progress bar

By default the MultiLoader instance will create a full screen progress bar. This can be turned off by setting the progressBar option to false.

let loader = new MultiLoader( { progressBar: false } );
// MultiLoader.load(...);

The loading bar should be disabled for lightweight models as the bar animation would add unnecessary waiting time.

Custom progress bar

A custom loading function can be define within the onProgress attribute, before calling the load method.

loader.onProgress = progress => {
    console.log(progress * 100 + '%'); // Will display 0% to 100%
}

Additionally, you can access the loading completion this way:

loader.progress; // returns a number between 0 and 1.

logs

Setting the logs to true will output the loading progress in the console.
Default is false.

let loader = new MultiLoader( { logs: true } );

texturesFlipY

This option defines if the textures should be flipped along the vertical axis when uploaded to the GPU. Default is false.

let loader = new MultiLoader( { texturesFlipY: true } );

CubeTexture loading

An alias must be provided for each cube-texture since they don't have a single unique path.

import MultiLoader from '@thibka/three-multiloader'
import { CubeTextureLoader } from 'three';

const loader = new MultiLoader({ 
    cubeTextureLoader: CubeTextureLoader,
});

loader.onLoaded.add( callbackFunction );

loader.load([
    { alias: 'skybox', type: 'cube-texture', path: [
        'path/to/px.png', 'path/to/nx.png',
        'path/to/py.png', 'path/to/ny.png',
        'path/to/pz.png', 'path/to/nz.png'
    ]}
]);

function callbackFunction() {
    console.log(loader.cubeTextures['skybox']);
}

KTX2 Compressed Textures

Transcoder files must be provided in the build.
This can be done in various ways:

Manually

By moving the file from node_modules/three/examples/jsm/libs/basis/ to build/basis/

With Webpack

By using copy-webpack-plugin:

/* webpack.config.js */
const CopyPlugin = require('copy-webpack-plugin');
let config = {
    plugins: [
        new CopyPlugin({
            patterns: [
                { from: 'node_modules/three/examples/jsm/libs/basis', to: 'basis' },
            ]
        })
    ]
}

With Vite

Using the vite-plugin-static-copy plugin:

/* vite.config.js */
import { viteStaticCopy } from 'vite-plugin-static-copy';
export default {
    plugins: [
        viteStaticCopy({
            targets: [
                {
                    src: 'node_modules/three/examples/jsm/libs/basis',
                    dest: ''
                }
            ]
        })
    ]
}

You can then use it this way:

import MultiLoader from '@thibka/three-multiloader'
import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';

const loader = new MultiLoader({ 
    KTX2Loader, 
    basisTranscoderPath: 'basis/', // Transcoder files must be provided in the build. See above.
    renderer: renderer // A renderer must be provided so that the basisLoader can work.
});

loader.onLoaded.add( callbackFunction );

loader.load([
    { alias: 'some-texture', type: 'texture', path: 'path/to/my_texture.ktx2' }
]);

function callbackFunction() {
    console.log(loader.textures['some-texture']);
}

DRACO compressed GLTF file loading

draco_decoder.js (600ko) must be provided in the build.
This can be done in various ways:

Manually

By moving the file from node_modules/three/examples/jsm/libs/draco/draco_decoder.js to build/draco/draco_decoder.js

With Webpack

Using copy-webpack-plugin:

/* webpack.config.js */
const CopyPlugin = require('copy-webpack-plugin');
let config = {
    plugins: [
        new CopyPlugin({
            patterns: [
                { from: 'node_modules/three/examples/jsm/libs/draco/draco_decoder.js', to: 'draco/draco_decoder.js' },
            ]
        })
    ]
}

With Vite

Using the vite-plugin-static-copy plugin:

/* vite.config.js */
import { viteStaticCopy } from 'vite-plugin-static-copy';
export default {
    plugins: [
        viteStaticCopy({
            targets: [
                {
                    src: 'node_modules/three/examples/jsm/libs/draco/draco_decoder.js',
                    dest: 'draco'
                }
            ]
        })
    ]
}

Then use it this way:

import MultiLoader from '@thibka/three-multiloader'
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';

const loader = new MultiLoader({ 
    DRACOLoader,
    DRACODecoderPath: 'draco/' // draco_decoder.js must be provided in the build.
});

loader.onLoaded.add( callbackFunction );

loader.load([
    { alias: 'some-model', type: 'gltf-draco', path: 'path/to/model.glb' }
]);

function callbackFunction() {
    let gltf = loader.models['some-model'];

    scene.add(gltf.scene);
}

.drc file loading

This loader should only be used for .drc files.

import MultiLoader from '@thibka/three-multiloader'
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';

const loader = new MultiLoader({ 
    DRACOLoader
});

loader.onLoaded.add( callbackFunction );

loader.load([
    { alias: 'some-model', type: 'drc', path: 'path/to/model.drc' }
]);

function callbackFunction() {
    let geometry = loader.models['some-model'];
    let material = new THREE.MeshStandardMaterial();
    let dracoMesh = new THREE.Mesh( geometry, material );
    scene.add( dracoMesh );
}

HDR textures

import MultiLoader from '@thibka/three-multiloader'
import { RGBELoader } from 'three/examples/jsm/loaders/RGBELoader.js';

const loader = new MultiLoader({ 
    RGBELoader
});

loader.onLoaded.add( callbackFunction );

loader.load([
    { alias: 'hdr', type: 'texture', path: 'path/toe/image.hdr' }
]);

Lottie textures

import MultiLoader from '@thibka/three-multiloader'
import { LottieLoader } from 'three/examples/jsm/loaders/LottieLoader.js';

const loader = new MultiLoader({ 
    lottieLoader: LottieLoader,
    lottieLoaderQuality: 2 // default is 1
});

loader.onLoaded.add(() => {
    // Once it's loaded as a texture, access the lottie animation with texture.animation
    console.log(loader.textures['lottie'].animation);
});

loader.load([
    { alias: 'lottie', type: 'texture', path: 'textures/lottie-logo-animation.json' }
]);