Communitygithub.com

Récit 3D piloté par le défilement

Chorégraphiez des scènes 3D avec le défilement de la page : mouvements de caméra liés au défilement, narration scène par scène, héros épinglés, défilement fluide et animations/shaders pilotés par la progression du défilement.

Qu'est-ce que Récit 3D piloté par le défilement ?

Cette compétence fournit l'architecture complète pour créer des expériences de narration web où le défilement de la page contrôle l'évolution d'une scène 3D. Elle utilise un canvas fixe en arrière-plan du DOM, le défilement normal du navigateur pilotant une valeur de progression qui anime la caméra, les modèles et les shaders. La compétence recommande Lenis pour un défilement fluide et accessible, et propose un système de storyboard pour découper la progression en séquences (héros, fonctionnalités, technique, preuve, CTA), chaque séquence étant implémentée via des interpolateurs `(start, end, apply(t))`. Elle gère également la synchronisation DOM/3D, les performances mobiles (DPR cap, pause RAF, réduction des particules), l'accessibilité (`prefers-reduced-motion`, fallback sans WebGL) et les pièges courants comme le détournement du défilement ou l'absence d'easing. Idéale pour les sites vitrine, portfolios ou landing pages premium, elle se combine avec `threejs-animation`, `ai-website-aesthetics` et `threejs-postprocessing`.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/BLACKNIGHT-cloud12/scroll-driven-3d-story/tree/HEAD

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait Récit 3D piloté par le défilement ?

La signature des sites web IA de premier ordre : la page défile, la scène 3D raconte l'histoire — la caméra glisse, les modèles s'assemblent, les particules se reforment. Cette compétence est l'architecture pour cela.

Architecture : un canvas fixe, le défilement pilote un nombre

Le canvas est en position: fixed derrière le DOM. Le défilement ne déplace jamais le canvas — il déplace une valeur de progression que la scène interpole. Tout le reste n'est que détail d'implémentation.

// Le DOM défile normalement ; nous lisons seulement, jamais de détournement.
let scrollProgress = 0;
addEventListener('scroll', () => {
  scrollProgress = scrollY / (document.body.scrollHeight - innerHeight);
}, { passive: true });

Dans la boucle RAF, interpolez l'état de la scène à partir de scrollProgress. C'est tout le jeu : construisez un storyboard (ci-dessous), puis écrivez un interpolateur par séquence.

Le storyboard (toujours en faire un d'abord)

Avant le code, mappez les plages de défilement aux états de la scène dans des commentaires ou un tableau :

0.00–0.15  héros :    modèle flotte au centre, rotation lente, caméra z=8
0.15–0.35  fonctionnalité : caméra effectue un travelling vers x=-4, modèle se divise en 3 parties
0.35–0.60  technique :    caméra orbite de 90°, particules affluent, superposition wireframe apparaît progressivement
0.60–0.80  preuve :   caméra recule, scène s'assombrit, cartes DOM apparaissent par-dessus le canvas
0.80–1.00  CTA :     modèle se réassemble au centre, lueur s'intensifie, caméra z=5

Implémentez chaque séquence sous forme de paires (début, fin, appliquer(t)) ; contraignez la progression dans chaque plage et appliquez un easing à t avant d'appliquer. Interpolez la position de la caméra, la rotation et les valeurs uniformes entre des états clés — ne téléportez jamais en milieu de séquence sauf pour un changement intentionnel.

Défilement fluide : Lenis, pas de détournement du défilement

Utilisez Lenis pour la sensation d'inertie ; il pilote toujours le défilement natif (accessible) :

const lenis = new Lenis({ lerp: 0.1 });
function raf(time) { lenis.raf(time); update3D(); requestAnimationFrame(raf); }
requestAnimationFrame(raf);
  • Ne bloquez jamais le défilement natif (overflow: hidden sur le body) — tue les utilisateurs clavier/mobile et le SEO.
  • Si vous utilisez GSAP ScrollTrigger à la place de la progression manuelle : gardez le canvas fixe et pilotez l'état de la scène, ne laissez pas ScrollTrigger transformer le canvas.

Trajectoires de caméra

Pour les mouvements multi-séquences, définissez un THREE.CatmullRomCurve3 à travers des positions clés et échantillonnez-le avec une progression adoucie — plus fluide que d'interpoler des paires de points. Les cibles du regard ont leur propre courbe. Cela s'intègre à threejs-animation pour les détails d'easing/courbes.

Synchronisation DOM + 3D

  • Le texte des sections est du DOM normal ; donnez-lui un mix-blend-mode ou des panneaux translucides par-dessus le canvas.
  • Synchronisez les révélations de section avec les séquences de la scène : déclenchez les animations DOM (GSAP ou CSS) à partir des mêmes plages de scrollProgress — une source de vérité unique.
  • Ancrez les étiquettes 3D à l'espace écran en projetant les positions du monde à chaque frame ; masquez-les lorsque la caméra est derrière.

Performances et mobile

  • Maintenez le canvas à un seul DPR (limite 1.5–2) ; les scènes liées au défilement se re-rendent à chaque frame indépendamment du défilement — réduisez les autres travaux par frame.
  • Mettez en pause le rendu RAF lorsque l'onglet ou la scène est loin de l'écran (document.visibilityState, IntersectionObserver sur les sections).
  • Mobile : réduisez les séquences (pas la longueur du défilement), diminuez le nombre de particules, désactivez le postprocessing (voir les compétences threejs-performance et threejs-postprocessing).
  • iOS Safari : le changement de taille de la barre d'adresse modifie innerHeight en cours de défilement — désactivez le redimensionnement, préférez une hauteur tenant compte de visualViewport pour le calcul de progression si les séquences semblent saccadées.

Accessibilité et solutions de repli

  • Respectez prefers-reduced-motion : rendez l'état final assemblé comme une scène statique, ignorez la chorégraphie de la caméra ; le défilement reste normal.
  • Repli sans 3D (GPU faible / failsIf) : fond dégradé + même histoire DOM. L'histoire doit survivre sans WebGL.

Erreurs courantes

  • Détourner les événements de défilement ou la molette — la raison n°1 pour laquelle les sites "premium" semblent cassés.
  • Lire scrollHeight à chaque frame (re-layout) — mettez en cache lors du redimensionnement.
  • Appliquer une progression linéaire brute aux mouvements de caméra — appliquez toujours un easing (ralenti-entrée-sortie) ou cela semble mécanique.
  • Plusieurs ScrollTriggers mutent chacun les mêmes propriétés de la scène — ils se battent ; acheminez tout via une seule valeur de progression.
  • Oublier lenis.raf(time) dans la boucle → le défilement semble mort.

Compétences associées

  • threejs-animation — easing, courbes, morphing
  • ai-website-aesthetics — l'apparence des séquences
  • threejs-postprocessing — bloom progressif entre les séquences
  • 3d-hero-interactions — le comportement au clic/survol de la séquence héros

Skills associés