BINTORO99/ad-ave-skills

Site 3D Frontend — Sites Web 3D Pilotés par le Défilement

Créez des pages HTML autonomes et immersives où le défilement fait parcourir à l'utilisateur une scène 3D construite avec Three.js. Le contenu (titres, texte, images, appels à l'action) est superposé ou intégré dans le monde 3D. Chaque page DreamWalk est un artefact .html autonome — sans outils de build, sans npm, sans React.

Stack Technique

Tous les résultats sont des artefacts HTML fichier unique. Pas d'outils de build, pas de npm, pas de React — juste un fichier .html autonome.

Bibliothèque	CDN	But
Three.js r128	https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js	Moteur de rendu 3D
GSAP 3.12.5	https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js	Moteur d'animation
ScrollTrigger 3.12.5	https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js	Liaison défilement-animation

Pourquoi cette stack ? Three.js est le framework WebGL dominant avec le plus grand écosystème. GSAP ScrollTrigger est la norme de l'industrie pour mapper la position de défilement aux timelines d'animation. Ensemble, ils alimentent la majorité des sites Web 3D à défilement primés (voir Awwwards, FWA). Cette combinaison fonctionne dans un seul fichier HTML sans étape de build, parfait pour les artefacts.

Important : Contraintes de l'API Three.js r128. Ce n'est PAS la dernière version de Three.js. Les éléments suivants n'existent PAS dans r128 et ne doivent jamais être utilisés : CapsuleGeometry, RoundedBoxGeometry, THREE.MathUtils.seededRandom, WebGPURenderer, THREE.ColorManagement. Utilisez toujours les primitives BufferGeometry (BoxBufferGeometry, SphereBufferGeometry, etc.) ou leurs alias (BoxGeometry, SphereGeometry).

Patron d'Architecture

┌─────────────────────────────────────────┐
│  Page HTML                              │
│  ┌───────────────────────────────────┐  │
│  │ <canvas> - Scène Three.js (fixe) │  │
│  │  • Caméra sur un chemin/spline   │  │
│  │  • Objets 3D (géométrie/particules)│  │
│  │  • Éclairage & brouillard        │  │
│  └───────────────────────────────────┘  │
│  ┌───────────────────────────────────┐  │
│  │ <div class="scroll-container">    │  │
│  │  hauteur : 500vh+ (défilable)     │  │
│  │  Sections avec texte/contenu      │  │
│  │  superposées via position:fixed   │  │
│  │  ou opacité atténuée sur les      │  │
│  │  déclencheurs de défilement       │  │
│  └───────────────────────────────────┘  │
│                                         │
│  GSAP ScrollTrigger mappe % défilement →│
│  camera.position / camera.lookAt /      │
│  transformations d'objets / paramètres   │
│  de matériau                            │
└─────────────────────────────────────────┘

Comment Construire une Page 3D à Défilement

Lisez references/PATTERNS.md pour des patrons de code détaillés, prêts à copier-coller, avant d'écrire du code. Il contient plus de 40 patrons prêts à l'emploi pour l'animation de caméra, l'éclairage, les shaders, les particules, la géométrie procédurale et l'optimisation des performances — tous compatibles avec Three.js r128.

Étape 1 : Conception de la Scène

Décidez du type d'expérience en fonction de l'intention de l'utilisateur :

Type	Comportement de la Caméra	Idéal pour
Tunnel / Couloir	Vol vers l'avant le long de l'axe Z	Révélation de produit, narration
Orbite / Vitrine	Rotation autour d'un objet central	Pages produit, portfolios
Survol de Paysage	Balayage au-dessus d'un terrain/paysage urbain	Pages d'atterrissage, intros
Visite de Pièce	Déplacement à travers des espaces connectés	Visites virtuelles, présentations
Descente Verticale	La caméra descend le long de l'axe Y	Chronologie, révélations de calques
Chemin Spline	La caméra suit un chemin 3D courbe	Cinématographique, éditorial

Étape 2 : Échafaudage du HTML

<!DOCTYPE html>
<html lang="fr">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Expérience 3D</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    html, body { overflow-x: hidden; }
    canvas { position: fixed; top: 0; left: 0; z-index: 0; }
    .scroll-container { position: relative; z-index: 1; pointer-events: none; }
    .section { height: 100vh; display: flex; align-items: center; justify-content: center; }
    .content { pointer-events: auto; /* réactiver pour les éléments interactifs */ }
  </style>
</head>
<body>
  <!-- Le canvas Three.js est créé par programmation -->
  <div class="scroll-container">
    <!-- Les sections génèrent la hauteur de défilement ; le contenu se superpose à la scène 3D -->
    <div class="section" id="section-1">...</div>
    <div class="section" id="section-2">...</div>
    <!-- Ajoutez plus de sections = plus de distance de défilement = voyage de caméra plus long -->
  </div>
  <script src="THREE_CDN"></script>
  <script src="GSAP_CDN"></script>
  <script src="SCROLLTRIGGER_CDN"></script>
  <script>
    // Configuration de la scène, animation, liaisons ScrollTrigger
  </script>
</body>
</html>

Étape 3 : Configuration de Base de Three.js

Incluez toujours ces fondamentaux :

1. Scène + Caméra + Rendu — Utilisez PerspectiveCamera avec un FOV de 60-75 pour une sensation immersive
2. Éclairage — Au minimum : une AmbientLight + une DirectionalLight. Ajoutez PointLight ou SpotLight pour le drame
3. Brouillard — scene.fog = new THREE.FogExp2(couleur, densité) ajoute de la profondeur et cache l'apparition d'éléments
4. Gestionnaire de redimensionnement — Gérez toujours window.resize
5. Boucle de rendu — requestAnimationFrame avec renderer.render(scene, camera)

Étape 4 : Animation Caméra → Défilement avec GSAP

Le patron de liaison critique :

gsap.registerPlugin(ScrollTrigger);

// Stockez les cibles d'animation de la caméra comme un objet simple
const camAnim = { x: 0, y: 2, z: 10, lookX: 0, lookY: 0, lookZ: 0 };

const tl = gsap.timeline({
  scrollTrigger: {
    trigger: ".scroll-container",
    start: "top top",
    end: "bottom bottom",
    scrub: 1,  // 1 seconde de lissage
  }
});

// Enchaînez les images clés de la caméra
tl.to(camAnim, { x: 0, y: 2, z: 5, lookX: 0, lookY: 0, lookZ: 0, duration: 1 })
  .to(camAnim, { x: 3, y: 1, z: 0, lookX: 2, lookY: 0, lookZ: -5, duration: 1 })
  .to(camAnim, { x: 0, y: 5, z: -10, lookX: 0, lookY: 0, lookZ: -15, duration: 1 });

// Dans la boucle de rendu, appliquez les valeurs animées
function animate() {
  requestAnimationFrame(animate);
  camera.position.set(camAnim.x, camAnim.y, camAnim.z);
  camera.lookAt(camAnim.lookX, camAnim.lookY, camAnim.lookZ);
  renderer.render(scene, camera);
}

Étape 5 : Superposition de Contenu

Superposez du contenu HTML qui apparaît/disparaît à des positions de défilement :

// Faire apparaître une section lorsque la caméra atteint un point de passage
gsap.fromTo("#section-2 .content", 
  { opacity: 0, y: 50 },
  { opacity: 1, y: 0,
    scrollTrigger: {
      trigger: "#section-2",
      start: "top center",
      end: "top 20%",
      scrub: true
    }
  }
);

Étape 6 : Polissage Visuel

Appliquez ces éléments pour passer du basique à l'impressionnant :

• Particules — THREE.Points avec THREE.BufferGeometry pour de la poussière/des étoiles flottantes
• Lueur post-traitement — Utilisez des matériaux émissifs + des couleurs vives de type bloom
• Transitions de couleurs — Animez scene.background et scene.fog.color le long du défilement
• Révélations d'objets — Les objets passent de l'échelle 0 ou apparaissent lorsque la caméra s'approche
• Calques de parallaxe — Les objets à différentes distances se déplacent à des vitesses différentes
• Rotation subtile — Faites tourner lentement les objets décoratifs dans la boucle de rendu (indépendant du défilement)
• Parallaxe à la souris — Léger décalage de la caméra basé sur la position de la souris pour une sensation de profondeur

Principes de Conception

1. Performance d'abord — Gardez la géométrie simple. Utilisez BufferGeometry, limitez les appels de dessin, utilisez fog pour cacher les objets lointains. Visez 60fps
2. Défilement fluide — scrub: 1 ou scrub: 2 dans ScrollTrigger pour un mouvement soyeux. N'utilisez jamais scrub: true (instantané, saccadé)
3. Contenu lisible — Les superpositions de texte ont besoin de contraste. Utilisez des panneaux sombres semi-transparents derrière un texte clair, ou assurez-vous que l'arrière-plan 3D est sombre/flou derrière les zones de texte
4. Alternative mobile — Le défilement tactile fonctionne avec ScrollTrigger. Envisagez de réduire le nombre de particules et la complexité de la géométrie sur mobile via des vérifications window.innerWidth
5. Chargement élégant — Affichez un écran de chargement CSS simple, cachez-le lorsque la scène Three.js est prête

Objets 3D Courants à Construire (aucun modèle externe nécessaire)

Tous peuvent être créés avec la géométrie intégrée de Three.js — aucun fichier GLTF requis :

• Formes géométriques flottantes — BoxGeometry, IcosahedronGeometry, TorusKnotGeometry avec MeshStandardMaterial
• Terrain — PlaneGeometry avec déplacement de sommets (ondes sinusoïdales, bruit)
• Champs de particules — BufferGeometry + Points pour étoiles, poussière, neige, visualisation de données
• Sols en grille — GridHelper ou géométrie de ligne personnalisée
• Tubes/tunnels — TubeGeometry le long d'un chemin CatmullRomCurve3
• Texte — Textures Canvas rendues sur PlaneGeometry, ou basées sur des sprites
• Objets fil de fer — Toute géométrie avec un matériau wireframe: true pour un esthétique techno
• Faisceaux lumineux — CylinderGeometry avec un matériau émissif transparent

Étape 7 : Parallaxe à la Souris (Optionnelle mais Recommandée)

Ajoutez un léger décalage de la caméra lors du déplacement de la souris pour la perception de la profondeur :

const mouse = { x: 0, y: 0 };
document.addEventListener('mousemove', (e) => {
  mouse.x = (e.clientX / window.innerWidth - 0.5) * 2;  // -1 à 1
  mouse.y = (e.clientY / window.innerHeight - 0.5) * 2;
});

// Dans la boucle de rendu, ajoutez un léger décalage à la caméra
const parallaxStrength = 0.3;
camera.position.x = camAnim.x + mouse.x * parallaxStrength;
camera.position.y = camAnim.y - mouse.y * parallaxStrength * 0.5;

Patron de Visite de Pièce

Pour les visites architecturales / immobilières, construisez des pièces à partir de géométrie simple :

// Créez une pièce avec BoxGeometry pour les murs, le sol, le plafond
function createRoom(width, height, depth, position, color) {
  const mat = new THREE.MeshStandardMaterial({ color, side: THREE.BackSide });
  const room = new THREE.Mesh(new THREE.BoxGeometry(width, height, depth), mat);
  room.position.copy(position);
  scene.add(room);
  return room;
}

// Créez des meubles avec des formes géométriques simples
// Canapé = boîte large et plate, Table = boîte fine sur cylindres, Lampe = cylindre + sphère
// Utilisez des PointLights émissives à l'intérieur des pièces pour une sensation chaleureuse

Principes clés pour les visites de pièces :

• Utilisez THREE.BackSide sur les matériaux pour que les murs rendent depuis l'intérieur
• Placez des sources PointLight chaudes à l'intérieur de chaque pièce (couleur 0xffeedd, intensité 0.8)
• Le chemin de la caméra doit passer par les ouvertures de porte, ne pas traverser les murs
• Animez camera.lookAt pour scanner naturellement chaque pièce en y entrant
• Ajoutez des rectangles de fenêtre avec un matériau émissif lumineux pour simuler la lumière du jour

Anti-Patrons à Éviter

• ❌ N'utilisez PAS OrbitControls — le défilement doit être la seule navigation
• ❌ Ne chargez PAS de modèles GLTF/GLB externes — restez autonome dans le fichier HTML
• ❌ N'utilisez PAS THREE.CapsuleGeometry — pas disponible dans r128
• ❌ Ne définissez PAS le canvas pointer-events: none globalement — la boucle de rendu a besoin du canvas
• ❌ N'oubliez PAS renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)) — évite la surcharge GPU sur Retina
• ❌ N'animez PAS la caméra avec camera.rotation directement — utilisez camera.lookAt() avec des coordonnées cibles animées pour des résultats stables
• ❌ Ne rendez PAS le conteneur de défilement trop court — 400vh minimum pour un voyage significatif, 600vh+ préféré

Direction Esthétique

Appliquez la même audace créative que la compétence frontend-design. Chaque page 3D à défilement doit être unique :

• Choisissez une ambiance colorée : cyberpunk néon, coucher de soleil chaud, océan profond, glace cristalline, vide sombre avec des accents émissifs, etc.
• Choisissez un langage géométrique : courbes organiques vs bords durs, sparse vs dense, grands monolithes vs minuscules particules
• Typographie en superposition : importez des polices Google distinctives. Utilisez une police large et cinématographique. Animez l'opacité et la transformation au défilement
• La scène 3D et le contenu HTML doivent ressembler à une expérience cohérente, et non à un arrière-plan 3D avec du texte plaqué dessus

Référence Rapide : URLs CDN

Three.js r128:     https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js
GSAP 3.12.5:       https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js
ScrollTrigger:     https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js