Caricare modelli gltfpack in Three.js

Per caricare i file prodotti da questo strumento con GLTFLoader, aggiungi MeshoptDecoder per la compressione Meshopt e KTX2Loader per le texture KTX2. Controlla nel pannello dei risultati quali estensioni richiede il file.

Installa dipendenze compatibili

Usa questo esempio in un progetto npm con un bundler per moduli ES, per esempio un'applicazione Vite esistente. Le versioni qui sotto corrispondono al visualizzatore del sito. Gli import senza percorso non funzionano aprendo semplicemente il file JavaScript nel browser.

npm install [email protected] [email protected]

Copia i file del transcoder Basis dal pacchetto Three.js installato nella cartella pubblica. Con una normale cartella public servita alla radice del sito, i file seguenti saranno disponibili sotto /basis/. Devono provenire dalla stessa versione di Three.js di KTX2Loader.

node -e "require('fs').cpSync('node_modules/three/examples/jsm/libs/basis', 'public/basis', {recursive:true})"

Collega i decoder prima del caricamento

Salva il file ottimizzato in public/models/optimized.glb e crea un canvas con id model. Usa il codice seguente come modulo di ingresso dell'applicazione. Adatta la camera ai limiti del modello caricato e riproduce la prima animazione, se presente.

<canvas id="model"></canvas>

import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
import { MeshoptDecoder } from 'meshoptimizer';

const renderer = new THREE.WebGLRenderer({
  canvas: document.querySelector('#model'), antialias: true,
});
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xeeeeee);
scene.add(new THREE.HemisphereLight(0xffffff, 0x444444, 3));
const light = new THREE.DirectionalLight(0xffffff, 3);
light.position.set(3, 5, 4);
scene.add(light);
const camera = new THREE.PerspectiveCamera(45, 1, 0.01, 1000);

const ktx2 = new KTX2Loader()
  .setTranscoderPath('/basis/')
  .detectSupport(renderer);
const loader = new GLTFLoader()
  .setMeshoptDecoder(MeshoptDecoder)
  .setKTX2Loader(ktx2);

function resize() {
  renderer.setSize(window.innerWidth, window.innerHeight);
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
}
window.addEventListener('resize', resize);
resize();

try {
  await MeshoptDecoder.ready;
  const gltf = await loader.loadAsync('/models/optimized.glb');
  scene.add(gltf.scene);
  const bounds = new THREE.Box3().setFromObject(gltf.scene);
  const center = bounds.getCenter(new THREE.Vector3());
  const radius = Math.max(bounds.getBoundingSphere(new THREE.Sphere()).radius, 0.01);
  const verticalFov = THREE.MathUtils.degToRad(camera.fov);
  const horizontalFov = 2 * Math.atan(Math.tan(verticalFov / 2) * camera.aspect);
  const distance = 1.2 * radius / Math.sin(Math.min(verticalFov, horizontalFov) / 2);
  camera.position.copy(center).add(new THREE.Vector3(1, 0.6, 1).normalize().multiplyScalar(distance));
  camera.near = radius / 100;
  camera.far = distance + radius * 10;
  camera.lookAt(center);
  camera.updateProjectionMatrix();

  const mixer = new THREE.AnimationMixer(gltf.scene);
  if (gltf.animations.length) mixer.clipAction(gltf.animations[0]).play();
  const clock = new THREE.Clock();
  renderer.setAnimationLoop(() => {
    mixer.update(Math.min(clock.getDelta(), 0.1));
    renderer.render(scene, camera);
  });
} catch (error) {
  console.error('Model loading failed:', error);
  const message = document.createElement('p');
  message.textContent = 'Model loading failed. Check the browser console and network requests.';
  document.body.prepend(message);
}

Controlla l'estensione e la richiesta fallita

In un sito con una Content Security Policy rigorosa, controlla nella console se Web Workers o WebAssembly vengono bloccati. Configura consapevolmente la distribuzione di worker e WASM; non rimuovere la policy solo per nascondere un errore. Una risposta di rete riuscita non conferma, da sola, che la decodifica sia riuscita.

L'esempio installa entrambi i decoder per caricare entrambi i tipi di risultato. I file che mantengono texture PNG o JPEG non richiedono KTX2Loader. WebP richiede il supporto del browser e del loader, ma non usa il transcoder Basis. In un'applicazione che cambia spesso modello, libera geometria, materiali e texture precedenti; rilascia il loader KTX2 quando non serve più.

Three.js GLTFLoader · Three.js KTX2Loader

Verificare gli altri requisiti di compatibilità →

Riferimento del motore: gltfpack