@stowkit/three-loader

Three.js loader for StowKit asset packs. Provides an easy-to-use API for loading meshes, textures, and audio from .stow files into Three.js scenes.

Installation

npm install @stowkit/three-loader three

Usage

Basic Mesh Loading

import * as THREE from 'three';
import { StowKitLoader } from '@stowkit/three-loader';

const loader = new StowKitLoader();
loader.setTranscoderPath('/basis/'); // Path to Basis Universal transcoder

// Load a mesh
const scene = await loader.loadMesh('assets.stow', 'models/character.mesh');
threeScene.add(scene);

Loading Multiple Assets from Same Pack

const loader = new StowKitLoader();
loader.setTranscoderPath('/basis/');

// Open pack once
await loader.openPack('assets.stow');

// Load multiple assets (no need to pass URL again)
const character = await loader.loadMesh('', 'models/character.mesh');
const weapon = await loader.loadMesh('', 'models/weapon.mesh');
const texture = await loader.loadTexture('', 'textures/diffuse.ktx2');

threeScene.add(character);
threeScene.add(weapon);

Loading Textures

const loader = new StowKitLoader();
loader.setTranscoderPath('/basis/');

const texture = await loader.loadTexture('assets.stow', 'textures/wood.ktx2');
material.map = texture;
material.needsUpdate = true;

Loading Audio

const listener = new THREE.AudioListener();
camera.add(listener);

const loader = new StowKitLoader();
const audio = await loader.loadAudio('assets.stow', 'sounds/bgm.ogg', listener);
audio.play();

With Callbacks (Three.js style)

loader.loadMesh(
    'assets.stow',
    'models/tree.mesh',
    (scene) => {
        // onLoad
        threeScene.add(scene);
    },
    (progress) => {
        // onProgress
        console.log('Loading...', progress);
    },
    (error) => {
        // onError
        console.error('Failed to load:', error);
    }
);

Getting Metadata

// Get texture info
const texInfo = loader.getTextureMetadata('textures/wood.ktx2');
console.log(`Texture: ${texInfo.width}x${texInfo.height}`);

// Get audio info
const audioInfo = loader.getAudioMetadata('sounds/bgm.ogg');
console.log(`Duration: ${audioInfo.durationMs}ms`);

Listing Assets

await loader.openPack('assets.stow');
const assets = loader.listAssets();

assets.forEach(asset => {
    console.log(`${asset.name} (${asset.type}): ${asset.dataSize} bytes`);
});

Features

• ✅ Automatic texture loading - Materials with mainTex properties automatically load and apply textures
• ✅ Material schema support - Reads tint colors, texture references, and other material properties
• ✅ KTX2/Basis Universal - Compressed texture support with GPU transcoding
• ✅ Scene hierarchy - Preserves node transforms and parent-child relationships
• ✅ Multi-material meshes - Supports meshes with multiple materials/submeshes
• ✅ Type-safe - Full TypeScript definitions

API Reference

StowKitLoader

Constructor

new StowKitLoader(manager?: THREE.LoadingManager, parameters?: StowKitLoaderParameters)

Methods

setTranscoderPath(path: string): this

Set the path to the Basis Universal transcoder (required for KTX2 textures).

detectSupport(renderer: THREE.WebGLRenderer): this

Detect GPU compressed texture format support.

openPack(url: string): Promise<void>

Open a .stow pack file. Call this once when loading multiple assets from the same pack.

loadMesh(url, assetPath, onLoad?, onProgress?, onError?): Promise<THREE.Group>

Load a mesh asset. Returns a Three.js Group containing the mesh hierarchy.

loadTexture(url, assetPath, onLoad?, onProgress?, onError?): Promise<THREE.CompressedTexture>

Load a texture asset. Returns a Three.js CompressedTexture.

loadAudio(url, assetPath, listener, onLoad?, onProgress?, onError?): Promise<THREE.Audio>

Load an audio asset. Returns a Three.js Audio object.

getTextureMetadata(assetPath): object | null

Get texture metadata (width, height, format, etc.).

getAudioMetadata(assetPath): object | null

Get audio metadata (sample rate, channels, duration).

listAssets(): array

List all assets in the opened pack.

dispose(): void

Clean up resources and free memory.

License

MIT