Three.js de A à Z

Définition simple

Three.js est une bibliothèque JavaScript open source (licence MIT) qui permet d'afficher et d'animer de la 3D en temps réel dans une page web. Elle s'appuie sur les interfaces graphiques du navigateur, WebGL hier et WebGPU aujourd'hui, et vous évite d'avoir à leur parler directement : là où l'API brute demande une centaine de lignes pour afficher un triangle, Three.js affiche un cube qui tourne en une quinzaine.

Le résultat tient dans un lien. Pas d'application à installer, pas de store, pas de plugin : la même scène tourne sur un PC, un téléphone, une tablette ou un casque de réalité virtuelle, à partir du même code.

Trois objets, et tout le reste en découle

Chaque objet visible est un Mesh : une géométrie (la forme, faite de triangles) habillée d'un matériau (la façon dont la surface réagit à la lumière). Le reste de la bibliothèque, chargeurs de modèles, contrôles de caméra, animation, réalité virtuelle, n'est que de l'outillage autour de ce noyau.

Les chiffres du projet Vérifiés le 8 septembre 2026

Le rythme de publication est soutenu : une version toutes les six à dix semaines ces derniers mois, chacune identifiée par un numéro précédé d'un r (pour release). Sur npm, r186 s'appelle 0.186.0. Ce n'est pas du versionnage sémantique : n'importe quelle version peut changer une API, d'où l'importance d'épingler la version que vous utilisez (voir la section 5).

Ce que Three.js n'est pas

• Pas un moteur de jeu complet. Pas de physique intégrée, pas d'éditeur de niveaux, pas de gestion de sauvegardes ni de réseau. Three.js dessine ; le reste se choisit à côté (section 10).
• Pas un logiciel de modélisation. Les modèles se fabriquent dans Blender ou équivalent, puis s'importent (au format glTF de préférence).
• Pas de la magie. Une page 3D consomme du processeur graphique et de la batterie. Savoir ce qui coûte cher est la moitié du métier (section 9).

Tout est triangle

Un processeur graphique ne sait dessiner que trois choses : des points, des lignes et des triangles. Une sphère « lisse » à l'écran est en réalité une mosaïque de quelques centaines à quelques milliers de triangles, dont les arêtes sont gommées par le calcul de l'éclairage. Plus il y a de triangles, plus la forme est fidèle, et plus la carte graphique travaille. Activez le mode filaire dans la démo ci-dessous pour les voir.

Chaque triangle est défini par trois sommets (vertices), et chaque sommet porte des données : sa position dans l'espace, sa normale (la direction vers laquelle la surface « regarde », indispensable pour calculer la lumière) et ses coordonnées UV (où piocher dans l'image plaquée dessus).

Le pipeline de rendu, étape par étape

1. Le vertex shader reçoit chaque sommet et le projette sur l'écran. Mathématiquement, c'est une multiplication par trois matrices 4×4 : la matrice modèle (où est l'objet dans le monde), la matrice vue (où est la caméra) et la matrice projection (la perspective, qui rapetisse ce qui est loin). Three.js les calcule pour vous à chaque image.
2. La rastérisation découpe chaque triangle projeté en pixels candidats, appelés fragments.
3. Le fragment shader calcule la couleur de chaque fragment : lumière reçue, couleur du matériau, texture, ombres. C'est ici que se joue le réalisme, et le coût.
4. Le test de profondeur compare la distance de chaque fragment à celle déjà stockée pour ce pixel, et ne garde que le plus proche. C'est ce qui fait qu'un objet en cache un autre sans que personne n'ait à trier quoi que ce soit.

Le budget : 16,7 millisecondes

Un écran à 60 Hz se rafraîchit toutes les 16,7 ms ; à 120 Hz, toutes les 8,3 ms. Tout doit tenir dans ce budget : votre JavaScript (mise à jour des positions, logique), la préparation des ordres de dessin par le processeur, puis leur exécution par le GPU. Dépassez, et l'image suivante est sautée : c'est la saccade. Toute la discipline de performance (section 9) consiste à rester sous cette barre sur la machine la plus faible que vous visez, pas sur la vôtre.

La caméra perspective a quatre paramètres : l'angle de vue (fov, en degrés), le ratio largeur/hauteur, et deux distances, near et far, entre lesquelles les objets sont visibles. Ces quatre valeurs définissent une pyramide tronquée, le frustum. Ce qui est en dehors n'est tout simplement pas envoyé au GPU : c'est le frustum culling, automatique dans Three.js.

Trois façons d'installer Fondamental

1. Sans outil de build : une import map et un CDN

C'est la méthode de ce guide. Le navigateur lit un bloc JSON qui associe le nom three à une URL, puis vos scripts l'importent comme un module normal. Épinglez toujours la version.

<script type="importmap">
{
  "imports": {
    "three":         "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.186.0/examples/jsm/"
  }
}
</script>

<script type="module">
  import * as THREE from 'three';
  import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
  // ... votre scène
</script>

2. Avec npm et un bundler (Vite)

npm install three          # installe la version courante, épinglée dans package.json
npm create vite@latest     # un projet moderne en une commande

Même code ensuite, avec en prime l'auto-complétion de l'éditeur, le tree-shaking (seul le code réellement importé part en production) et le rechargement à chaud.

3. Via un framework

React Three Fiber, Threlte ou TresJS (section 10) enveloppent Three.js dans la syntaxe de React, Svelte ou Vue. Utile si votre application est déjà écrite avec l'un d'eux ; inutile pour apprendre.

Le programme minimal, ligne par ligne

import * as THREE from 'three';

// 1. Une caméra : angle de vue 70°, ratio de l'écran, visible entre 0,01 et 10 unités
const camera = new THREE.PerspectiveCamera(70, innerWidth / innerHeight, 0.01, 10);
camera.position.z = 1;

// 2. Une scène, et un cube dedans
const scene    = new THREE.Scene();
const geometry = new THREE.BoxGeometry(0.2, 0.2, 0.2);
const material = new THREE.MeshNormalMaterial();
const mesh     = new THREE.Mesh(geometry, material);
scene.add(mesh);

// 3. Un moteur de rendu, qui crée son propre <canvas>
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setSize(innerWidth, innerHeight);
document.body.appendChild(renderer.domElement);

// 4. La boucle : le navigateur rappelle cette fonction avant chaque rafraîchissement
renderer.setAnimationLoop((time) => {
    mesh.rotation.x = time / 2000;   // time est en millisecondes
    mesh.rotation.y = time / 1000;
    renderer.render(scene, camera);
});

• Les unités sont arbitraires. Un cube de 0,2 est petit parce que la caméra est à 1 unité. Convention courante : 1 unité = 1 mètre, ce qui simplifie l'import de modèles et la physique.
• Les angles sont en radians partout, sauf le fov de la caméra, en degrés. Un tour complet vaut 2 * Math.PI.
• Le repère est droitier : X vers la droite, Y vers le haut, Z vers vous (hors de l'écran). La caméra regarde vers les Z négatifs.
• setAnimationLoop s'appuie sur requestAnimationFrame : la boucle se cale sur l'écran et se met en pause quand l'onglet est caché. Elle est aussi obligatoire pour la réalité virtuelle, où c'est le casque qui impose la cadence.
• Utilisez time plutôt qu'un compteur incrémenté à chaque image : à 120 Hz, votre cube tournerait deux fois plus vite qu'à 60 Hz.

Les briques que vous ajouterez ensuite

Tout ce qui vit sous three/addons/ vient du dossier examples/jsm du dépôt : maintenu par le projet, mais hors du cœur, ce qui garde ce dernier léger.

Pourquoi le rendu « physique » a gagné

Jusqu'au début des années 2010, un matériau 3D se décrivait par des paramètres esthétiques : une couleur diffuse, une couleur spéculaire, une « brillance ». Ça marchait sous une lumière, et c'était faux sous une autre. Le rendu physiquement réaliste (PBR) remplace ces réglages par des propriétés mesurables sur de vrais matériaux, ce qui donne un rendu cohérent quel que soit l'éclairage. Three.js l'implémente dans MeshStandardMaterial et son extension MeshPhysicalMaterial.

D'où vient la lumière ?

Les ombres portées ne sont pas gratuites : pour chaque lumière qui en projette, le GPU rend la scène une fois de plus, depuis le point de vue de la lumière, pour savoir ce qui est caché. Une lumière avec ombres, rarement plus.

Le CV le plus conduit du web

bruno-simon.com : vous arrivez sur un terrain vague miniature au volant d'une petite voiture, et vous renversez le nom du propriétaire pour comprendre que tout se déplace. La version 2019 tournait sur un moteur physique (Cannon.js) synchronisé image par image avec la scène Three.js. La version 2025-2026, refaite pendant plus d'un an et documentée sur YouTube, ajoute la manette, des succès à débloquer, un circuit avec classement quotidien, et publie son code sous licence MIT. Un portfolio devenu jeu, devenu cours, devenu référence.

Et aussi, dans la vitrine officielle

• putt.day : un trou de mini-golf par jour, le même pour tout le monde, à finir en un minimum de coups.
• Choo-Choo World : un constructeur de circuits de train en bois, à la campagne, dont on partage les créations.
• HexGL : le jeu de course de 2012, toujours jouable, dont le code est un excellent cas d'école.
• Les exemples officiels : plusieurs centaines de scènes, chacune avec son code source visible, du plus simple au plus expérimental. Le meilleur terrain de jeu qui soit.

Règle n°1 : compter les appels de dessin, pas les triangles

Chaque Mesh déclenche au moins un appel de dessin (draw call). Avant chaque appel, le processeur prépare l'état du GPU : quelle géométrie, quel matériau, quelles matrices. Ce travail a un coût fixe, quelle que soit la taille de l'objet. Mille cubes de douze triangles coûtent donc bien plus cher qu'un seul objet de douze mille triangles. La règle empirique : quelques centaines d'appels par image sont confortables, quelques milliers deviennent le goulot d'étranglement, surtout sur mobile.

Les trois remèdes classiques :

• Instancing (InstancedMesh) : N copies de la même géométrie, chacune avec sa matrice et sa couleur, en un appel. Démo ci-dessous.
• Fusion de géométries (BufferGeometryUtils.mergeGeometries) : plusieurs formes statiques deviennent un seul objet.
• Atlas de textures et matériaux partagés : deux objets qui partagent géométrie et matériau ne forcent pas le GPU à changer d'état entre les deux.

Les autres postes de dépense

Mesurer avant d'optimiser

• renderer.info : appels, triangles, textures et géométries en mémoire, lus après chaque rendu. C'est ce qu'affichent les tableaux de bord de ce guide.
• stats.js (dans les addons) : le petit compteur d'images par seconde que l'on voit sur tous les exemples officiels.
• L'onglet Performance des outils de développement du navigateur : sépare le temps JavaScript du temps GPU, et montre les images manquées.
• Spector.js : capture une image WebGL et liste chaque appel, avec son état. L'outil pour comprendre pourquoi une scène fait 400 appels alors qu'elle en devrait 40.

Autour de Three.js

Three.js face aux alternatives Comparatif

La couverture réelle des navigateurs Chiffres caniuse.com, septembre 2026

Conclusion pratique : en 2026, une scène WebGPU sans repli WebGL exclut encore un visiteur sur huit. Le repli n'est pas une option, c'est une obligation.

Ce que dit le projet lui-même

• WebGLRenderer reste maintenu et reste le choix recommandé pour une application purement WebGL 2, mais le projet indique qu'il n'y ajoutera plus de grandes fonctionnalités : l'effort va au WebGPURenderer.
• WebGPURenderer se replie automatiquement sur WebGL 2 quand WebGPU n'est pas disponible. Vous n'avez rien à écrire pour cela.
• TSL, le Three Shading Language, est la façon d'écrire des matériaux et des effets pour ce nouveau moteur : du JavaScript composable, compilé en WGSL sur WebGPU et en GLSL sur WebGL. Un seul code, deux cibles.
• Ce qui ne passe pas tel quel sur WebGPURenderer : les matériaux ShaderMaterial et RawShaderMaterial, les modifications par onBeforeCompile(), et l'ancienne chaîne de post-processing EffectComposer. Tout cela se réécrit en TSL et en nœuds.

La décision, selon votre situation

Phase 1 : les fondations Quelques semaines

1. JavaScript moderne : modules (import), fonctions fléchées, async/await, classes. Three.js est écrit ainsi, ses exemples aussi.
2. Un peu de géométrie : vecteurs (position, direction), radians, ce qu'est une matrice de transformation. Pas de calcul à la main : comprendre ce que Three.js fait pour vous.
3. Le cube : reproduire le programme de la section 5 sans le copier. Puis changer la caméra, la forme, la vitesse.
4. OrbitControls et les lumières : une DirectionalLight, une HemisphereLight, un MeshStandardMaterial. Comprendre pourquoi un objet est noir.

Phase 2 : le pipeline réel 1 à 2 mois

1. Blender : modéliser un objet simple, le texturer, l'exporter en glTF, le charger avec GLTFLoader.
2. Environnement et PBR : une image HDR ou RoomEnvironment, rugosité et métallicité, espaces colorimétriques.
3. Interaction : Raycaster pour cliquer sur un objet, survol, drag.
4. Animation : AnimationMixer pour les animations glTF, GSAP pour le reste.
5. Un panneau de réglages (lil-gui) sur chaque projet, dès la première heure.

Phase 3 : le niveau professionnel 3 à 6 mois

1. Performance : instancing, fusion, LOD, textures KTX2, renderer.info, tests sur mobile.
2. Shaders : les bases de GLSL, puis TSL. Comprendre un vertex shader et un fragment shader en les écrivant.
3. Intégration : React Three Fiber si votre application est en React ; sinon, Three.js nu suffit.
4. Physique : Rapier ou cannon-es, synchronisation corps physique / mesh à chaque image.
5. Chargement : barre de progression, chargement différé, gestion des erreurs, poids total sous contrôle.

Phase 4 : l'expertise 6 mois et plus

1. WebGPU et compute shaders : simulations de particules, GPGPU, post-processing en nœuds.
2. Post-processing sur mesure et effets de rendu (SSAO, réflexions écran, profondeur de champ), avec leur coût.
3. WebXR : réalité virtuelle et augmentée, contrôleurs, suivi des mains.
4. Architecture : scènes de grande taille, streaming, mémoire, outils de diagnostic.
5. Contribuer : un exemple, une correction de documentation, un ticket bien décrit. Le projet a plus de 2 000 contributeurs, et une place pour vous.