Blender to the web (three.js)

Getting a Blender 5.x model onto a web page: preparing the scene, the glTF exporter's settings, what survives the trip, shrinking the file with glTF Transform or gltfpack, and the first lines of three.js or React Three Fiber that load it. The three.js side in depth (decoders, the animation mixer, picking, performance) is in Models, animation & picking; the ideas behind meshes, PBR and rigs are in Fundamentals.

The pipeline

Before you export

Work through this in Blender before touching the export dialog; most "it looks wrong in three.js" bugs start here.

Exporter settings

File > Export > glTF 2.0 (.glb/.gltf). The dialog has collapsible panels; this is the web setup, with labels as in the Blender 5.2 manual. Tick Remember Export Settings to store them in the .blend.

The same exporter runs from Python as bpy.ops.export_scene.gltf(...); see the recipe Export from the command line and batch exports in Python scripting.

What survives export

Extensions the exporter can write (Blender 5.2): KHR_draco_mesh_compression, KHR_lights_punctual, KHR_materials_clearcoat, _transmission, _unlit, _emissive_strength, _volume, _sheen, _specular, _anisotropy, _dispersion, _ior, _variants, KHR_texture_transform, EXT_mesh_gpu_instancing, EXT_meshopt_compression or KHR_meshopt_compression (a Meshopt option), and EXT_texture_webp when Images is WebP. It does not write KTX2 (KHR_texture_basisu); add that with the tools in Optimize after export.

Animations for the web

A glTF animation is a clip that moves objects, bones or shape keys. In Blender the unit is an action (a set of keyframed curves). The exporter only sees actions that are active on an object or stashed in the NLA (non-linear animation) editor.

Blender 4.4 introduced slotted actions (one action can drive several objects); since then the Actions mode merges tracks that use the same action. More in Blender animation.

Watch for how the clips are set up in Blender before export, then how the app plays them with the mixer.

Optimize after export

Blender's output is correct but big. Run it through one optimizer before shipping.

# glTF Transform: all-in-one (defaults: Meshopt, 2048 px max)
bunx @gltf-transform/cli optimize model.glb web.glb \
  --compress meshopt --texture-compress webp
# Draco geometry, 1K textures, keep named nodes for code
bunx @gltf-transform/cli optimize model.glb web.glb \
  --compress draco --texture-compress webp \
  --texture-size 1024 --join false --flatten false
# report: sizes, draw calls, texture memory
bunx @gltf-transform/cli inspect web.glb
bunx @gltf-transform/cli validate web.glb
 
# gltfpack: Meshopt, keep named nodes, KTX2 textures
# (native binary; the npm build has no texture compression)
gltfpack -i model.glb -o web.glb -cc -kn -tc

A 2048 × 2048 RGBA texture takes about 22 MB of GPU memory with mipmaps as PNG, JPEG or WebP, and about 5.6 MB as KTX2 transcoded to a GPU format. The download size says nothing about GPU cost.

Measured on a test scene exported from Blender 5.2 (Suzanne with Subdivision level 3 applied, 63k triangles, two 2048² textures, one action). The textures are synthetic, so real ones compress differently; the ratios are typical.

The default optimize also simplified the mesh from 63k to 43k triangles (flat areas lose the most); pass --simplify false if silhouettes or UV seams change.

Load it in three.js

Copy the Draco decoder from node_modules/three/examples/jsm/libs/draco/ to public/draco/ (Compression decoders). The minimum, with an environment map so PBR materials are not black and AgX tone mapping to look closer to Blender's default:

import {
  AgXToneMapping, AnimationMixer, PMREMGenerator,
  PerspectiveCamera, Scene, Timer, WebGLRenderer,
} from "three";
import { GLTFLoader } from
  "three/addons/loaders/GLTFLoader.js";
import { DRACOLoader } from
  "three/addons/loaders/DRACOLoader.js";
import { MeshoptDecoder } from
  "three/addons/libs/meshopt_decoder.module.js";
import { RoomEnvironment } from
  "three/addons/environments/RoomEnvironment.js";
 
const renderer = new WebGLRenderer({ antialias: true });
renderer.toneMapping = AgXToneMapping; // Blender's default
renderer.setSize(innerWidth, innerHeight);
document.body.append(renderer.domElement);
 
const scene = new Scene();
const pmrem = new PMREMGenerator(renderer);
scene.environment = pmrem.fromScene(
  new RoomEnvironment(),
).texture; // stands in for the Blender World
 
const camera = new PerspectiveCamera(
  50, innerWidth / innerHeight, 0.1, 100,
);
camera.position.set(0, 1.6, 4); // meters, eye height
 
const draco = new DRACOLoader().setDecoderPath("/draco/");
const loader = new GLTFLoader()
  .setDRACOLoader(draco)
  .setMeshoptDecoder(MeshoptDecoder);
 
const gltf = await loader.loadAsync("/models/robot.glb");
scene.add(gltf.scene);
 
const mixer = new AnimationMixer(gltf.scene);
const walk = gltf.animations.find((c) => c.name === "Walk");
if (walk) mixer.clipAction(walk).play();
 
const timer = new Timer();
renderer.setAnimationLoop((t) => {
  timer.update(t);
  mixer.update(timer.getDelta());
  renderer.render(scene, camera);
});

Next steps on the three.js side: a shared cached loader and KTX2 in Models, animation & picking, HDRI lighting and tone mapping in Lights & shadows, color spaces in Fundamentals.

React Three Fiber

gltfjsx turns the file into a typed component and can optimize it on the way (React Three Fiber: gltfjsx):

bunx gltfjsx public/models/robot.glb --transform --types
# -T/--transform  writes robot-transformed.glb: Draco,
#                 prune, textures resized (-R, default
#                 1024) and converted (-f, default webp)
# -t/--types      TypeScript definitions for the nodes
# -s/--shadows    cast and receive shadows
# -k/--keepnames  keep original names

Without a generated component, useGLTF from drei is enough:

import { Suspense, useEffect } from "react";
import { Canvas } from "@react-three/fiber";
import {
  Environment, useAnimations, useGLTF,
} from "@react-three/drei";
 
const URL = "/models/robot.glb";
 
function Robot() {
  const { scene, animations } = useGLTF(URL);
  const { actions } = useAnimations(animations, scene);
  useEffect(() => {
    actions["Walk"]?.reset().fadeIn(0.3).play();
  }, [actions]);
  return <primitive object={scene} />;
}
useGLTF.preload(URL);
 
export function Viewer() {
  return (
    <Canvas camera={{ position: [0, 1.6, 4] }}>
      <Suspense fallback={null}>
        <Robot />
        <Environment preset="city" />
      </Suspense>
    </Canvas>
  );
}

useGLTF wires Draco (decoder from a CDN by default) and Meshopt for you. A <primitive> can be mounted once; for copies use drei's <Clone> or the gltfjsx component.

Check and debug

Common problems

Recipes

Export from the command line

Use in a build script so every export uses the same settings (see Python scripting for batching many files).

# export_web.py
# run: blender -b scene.blend -P export_web.py
import bpy
 
out = bpy.path.abspath("//build/scene.glb")
bpy.ops.export_scene.gltf(
    filepath=out,
    export_format="GLB",
    use_visible=True,
    export_yup=True,
    export_apply=True,  # Apply Modifiers
    export_image_format="WEBP",
    export_animation_mode="ACTIONS",
    export_lights=False,  # light it in three.js
)

A hero asset under 5 MB

Use for a product or character that has to load fast on phones.

1. In Blender: apply transforms, purge unused data, bake procedural materials, 2K textures at most.
2. Export GLB with Apply Modifiers, Images Automatic, no compression.
3. bunx @gltf-transform/cli inspect model.glb to find the biggest textures and meshes.
4. bunx @gltf-transform/cli optimize model.glb web.glb --compress meshopt --texture-compress ktx2 (or webp without KTX-Software).
5. Open web.glb in the glTF Viewer; check clips, materials and the validator.
6. Serve with a long cache lifetime and a versioned file name (robot.3f2a.glb).

Inspect what arrived

Use when the model looks wrong: size in meters, mesh and material names, clip names and lengths.

import { Box3, Vector3 } from "three";
import type { Mesh, Object3D } from "three";
import type { GLTF } from
  "three/addons/loaders/GLTFLoader.js";
 
/** Log what Blender actually exported. */
export function report(gltf: GLTF): void {
  const size = new Box3().setFromObject(gltf.scene)
    .getSize(new Vector3());
  console.table({ x: size.x, y: size.y, z: size.z }); // m
  gltf.scene.traverse((o: Object3D) => {
    const m = o as Mesh;
    if (!m.isMesh) return;
    const mats = [m.material].flat().map((x) => x.name);
    console.log(m.name, mats.join(", "));
  });
  for (const c of gltf.animations) {
    console.log("clip", c.name, c.duration.toFixed(2), "s");
  }
}
 
/** Scale so the largest side is `size` m, base on y = 0. */
export function fit(root: Object3D, size = 1): void {
  const dims = new Box3().setFromObject(root)
    .getSize(new Vector3());
  root.scale.multiplyScalar(
    size / Math.max(dims.x, dims.y, dims.z),
  );
  const box = new Box3().setFromObject(root);
  const c = box.getCenter(new Vector3());
  root.position.set(
    root.position.x - c.x,
    root.position.y - box.min.y,
    root.position.z - c.z,
  );
}

fit is for model viewers with arbitrary uploads; for your own assets, fix the scale in Blender instead.

Bake a procedural material

Use when a material built from noise or color ramps turns flat gray in the browser.

1. UV unwrap the mesh (Smart UV Project is enough for baking).
2. Add an Image Texture node (not connected) with a new 2048 image, and select it.
3. Render Properties: Cycles; Bake Type Diffuse with only Color ticked (base color), then Roughness, then Normal, each into its own image.
4. Save each image, rebuild the material as Principled BSDF with those three Image Texture nodes.
5. Export. Details in Materials & UVs.

A character with several clips

Use for a rigged character driven by code (idle, walk, run, jump).

1. One action per move, named Idle, Walk, Run, Jump; each starts and ends in a matching pose.
2. Push Down each action so each sits on its own NLA track; mute the tracks so they don't mix in the viewport.
3. Export: Mode Actions, Always Sample Animations on, Export Deformation Bones Only on, Bone Influences 4.
4. Check the clip list in the glTF Viewer.
5. In three.js, cross-fade between clips with the character state machine recipe.

Keep names for code

Use when code finds parts by name (a door to open, a screen to texture).

• Name the object in Blender without dots or spaces (Door_L, not Door.001).
• Keep it a separate object; don't join it into a bigger mesh.
• Optimize with --join false --flatten false (glTF Transform) or -kn (gltfpack).
• Find it with gltf.scene.getObjectByName("Door_L").

References

• Blender Manual: glTF 2.0 (opens in a new tab): every exporter option, material mapping, extensions, animation modes
• Blender Python API: export_scene.gltf (opens in a new tab): the same options as script keywords
• Khronos glTF-Blender-IO (opens in a new tab): the exporter's source, issues and changelog
• glTF 2.0 specification (opens in a new tab) and extension registry (opens in a new tab)
• Khronos: glTF overview (opens in a new tab): what the format is for, ecosystem and tools
• three.js docs: GLTFLoader (opens in a new tab) and the loading 3D models manual (opens in a new tab)
• glTF Transform CLI (opens in a new tab): optimize and every single-step command
• gltfpack (opens in a new tab): flags and native binaries
• gltfjsx (opens in a new tab) and drei useGLTF (opens in a new tab)
• glTF Viewer (opens in a new tab), glTF Sample Viewer (opens in a new tab), glTF Validator (opens in a new tab)