BINTORO99/ad-ave-skills

3D-Frontend – Scrollgesteuerte 3D-Websites

Erstelle immersive, einzelne HTML-Seiten, bei denen der Benutzer durch Scrollen durch eine mit Three.js gebaute 3D-Szene geht. Inhalte (Überschriften, Text, Bilder, CTAs) werden über die 3D-Welt gelegt oder darin eingebettet. Jede DreamWalk-Seite ist ein eigenständiges .html-Artefakt – keine Build-Tools, kein npm, kein React.

Tech-Stack

Alle Ausgaben sind einzelne HTML-Dateien. Keine Build-Tools, kein npm, kein React – nur eine eigenständige .html-Datei.

Bibliothek	CDN	Zweck
Three.js r128	https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js	3D-Rendering-Engine
GSAP 3.12.5	https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js	Animations-Engine
ScrollTrigger 3.12.5	https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js	Scroll-zu-Animation-Bindung

Warum dieser Stack? Three.js ist das dominierende WebGL-Framework mit dem größten Ökosystem. GSAP ScrollTrigger ist der Industriestandard, um die Scrollposition mit Animationszeitachsen zu verknüpfen. Zusammen treiben sie die Mehrheit preisgekrönter 3D-Scroll-Websites an (siehe Awwwards, FWA). Diese Kombination funktioniert in einer einzigen HTML-Datei ohne Build-Schritt – perfekt für Artefakte.

Wichtig: Three.js r128 API-Einschränkungen. Dies ist NICHT das neueste Three.js. Folgende Dinge gibt es in r128 NICHT und dürfen niemals verwendet werden: CapsuleGeometry, RoundedBoxGeometry, THREE.MathUtils.seededRandom, WebGPURenderer, THREE.ColorManagement. Verwende immer BufferGeometry-Primitive (BoxBufferGeometry, SphereBufferGeometry usw.) oder deren Aliase (BoxGeometry, SphereGeometry).

Architekturmuster

┌─────────────────────────────────────────┐
│  HTML-Seite                              │
│  ┌───────────────────────────────────┐  │
│  │ <canvas> - Three.js-Szene (fest)  │  │
│  │  • Kamera auf einem Pfad/Spline   │  │
│  │  • 3D-Objekte (Geometrie/Partikel) │  │
│  │  • Beleuchtung & Nebel             │  │
│  └───────────────────────────────────┘  │
│  ┌───────────────────────────────────┐  │
│  │ <div class="scroll-container">    │  │
│  │  Höhe: 500vh+ (scrollbar)         │  │
│  │  Abschnitte mit Text/Inhalt       │  │
│  │  überlagert via position:fixed    │  │
│  │  oder Opacity bei Scroll-Triggern │  │
│  └───────────────────────────────────┘  │
│                                         │
│  GSAP ScrollTrigger bildet Scroll% →    │
│  camera.position / camera.lookAt /      │
│  Objekt-Transformationen / Material-Par.│
└─────────────────────────────────────────┘

So baust du eine 3D-Scroll-Seite

Lies references/PATTERNS.md für detaillierte, kopierfertige Code-Muster, bevor du Code schreibst. Es enthält über 40 produktionsreife Muster für Kamera-Animation, Beleuchtung, Shader, Partikel, prozedurale Geometrie und Performance-Optimierung – alle kompatibel mit Three.js r128.

Schritt 1: Szenendesign

Entscheide den Erlebnistyp basierend auf der Benutzerabsicht:

Typ	Kamera-Verhalten	Am besten geeignet für
Tunnel / Korridor	Vorwärtsflug entlang der Z-Achse	Produkt-Enthüllungen, Storytelling
Orbit / Showcase	Drehung um ein zentrales Objekt	Produktseiten, Portfolios
Landschaftsflug	Überflug über Gelände/Stadt	Landingpages, Intros
Raum-Rundgang	Bewegung durch verbundene Räume	Virtuelle Touren, Präsentationen
Vertikaler Abstieg	Kamera fällt auf Y-Achse	Zeitleisten, Schicht-Enthüllungen
Spline-Pfad	Kamera folgt einem gekrümmten 3D-Pfad	Kinematografisch, Redaktionell

Schritt 2: HTML-Gerüst

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>3D-Erlebnis</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; /* für interaktive Elemente wieder aktivieren */ }
  </style>
</head>
<body>
  <!-- Three.js-Canvas wird programmatisch erstellt -->
  <div class="scroll-container">
    <!-- Abschnitte treiben die Scrollhöhe; Inhalt überlagert die 3D-Szene -->
    <div class="section" id="section-1">...</div>
    <div class="section" id="section-2">...</div>
    <!-- Weitere Abschnitte = mehr Scrollstrecke = längere Kamerafahrt -->
  </div>
  <script src="THREE_CDN"></script>
  <script src="GSAP_CDN"></script>
  <script src="SCROLLTRIGGER_CDN"></script>
  <script>
    // Szeneneinrichtung, Animation, ScrollTrigger-Bindungen
  </script>
</body>
</html>

Schritt 3: Kern-Three.js-Einrichtung

Füge immer diese Grundlagen ein:

1. Szene + Kamera + Renderer – Verwende PerspectiveCamera mit Sichtfeld 60-75 für ein immersives Gefühl
2. Beleuchtung – Mindestens: ein AmbientLight + ein DirectionalLight. Füge PointLight oder SpotLight für Dramatik hinzu
3. Nebel – scene.fog = new THREE.FogExp2(farbe, dichte) verleiht Tiefe und versteckt plötzliches Einblenden
4. Resize-Handler – Behandle immer window.resize
5. Render-Schleife – requestAnimationFrame mit renderer.render(scene, camera)

Schritt 4: Scroll → Kamera-Animation mit GSAP

Das entscheidende Bindungsmuster:

gsap.registerPlugin(ScrollTrigger);

// Kamera-Animationsziele als einfaches Objekt speichern
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 Sekunde Glättung
  }
});

// Kamera-Keyframes verketten
tl.to(camAnim, { x: 0, y: 2, z: 5, lookX: 0, lookY: 0, lookZ: 0, dauer: 1 })
  .to(camAnim, { x: 3, y: 1, z: 0, lookX: 2, lookY: 0, lookZ: -5, dauer: 1 })
  .to(camAnim, { x: 0, y: 5, z: -10, lookX: 0, lookY: 0, lookZ: -15, dauer: 1 });

// In der Render-Schleife die animierten Werte anwenden
function animiere() {
  requestAnimationFrame(animiere);
  kamera.position.set(camAnim.x, camAnim.y, camAnim.z);
  kamera.lookAt(camAnim.lookX, camAnim.lookY, camAnim.lookZ);
  renderer.render(szene, kamera);
}

Schritt 5: Inhaltsüberlagerung

Überlagere HTML-Inhalte, die an Scrollpositionen ein-/ausblenden:

// Abschnitt einblenden, wenn die Kamera einen Wegpunkt erreicht
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
    }
  }
);

Schritt 6: Visuelle Verfeinerung

Wende diese Dinge an, um von einfach zu beeindruckend zu gelangen:

• Partikel – Verwende THREE.Points mit THREE.BufferGeometry für schwebenden Staub/Sterne
• Post-Processing-Glühen – Verwende emittierende Materialien + leuchtende, helle Farben
• Farbübergänge – Animiere scene.background und scene.fog.color entlang des Scrollens
• Objekt-Enthüllungen – Objekte skalieren von 0 oder blenden ein, wenn die Kamera näher kommt
• Parallaxen-Ebenen – Objekte in unterschiedlichen Entfernungen bewegen sich mit unterschiedlichen Geschwindigkeiten
• Subtile Rotation – Dekorative Objekte in der Render-Schleife langsam rotieren lassen (unabhängig vom Scrollen)
• Maus-Parallaxe – Leichter Kamera-Offset basierend auf Mausposition für Tiefengefühl

Gestaltungsprinzipien

1. Leistung zuerst – Halte Geometrie einfach. Verwende BufferGeometry, begrenze Draw-Calls, verwende fog, um entfernte Objekte zu verstecken. Ziel: 60fps
2. Sanftes Scrollen – Verwende scrub: 1 oder scrub: 2 in ScrollTrigger für butterweiche Bewegung. Verwende niemals scrub: true (sofortig, ruckelig)
3. Lesbare Inhalte – Textüberlagerungen benötigen Kontrast. Verwende halbtransparente, dunkle Paneele hinter hellem Text oder stelle sicher, dass der 3D-Hintergrund hinter Textbereichen dunkel/unscharf ist
4. Mobile Fallbacks – Touch-Scrolling funktioniert mit ScrollTrigger. Reduziere Partikelanzahl und Geometriekomplexität auf Mobilgeräten durch window.innerWidth-Prüfungen
5. Ladezustände elegant gestalten – Zeige einen einfachen CSS-Ladebildschirm, verstecke ihn, wenn die Three.js-Szene bereit ist

Häufige 3D-Objekte zum Bauen (keine externen Modelle nötig)

Diese können alle mit den integrierten Three.js-Geometrien erstellt werden – keine GLTF-Dateien erforderlich:

• Schwebende geometrische Formen – BoxGeometry, IcosahedronGeometry, TorusKnotGeometry mit MeshStandardMaterial
• Gelände – PlaneGeometry mit Vertex-Verschiebung (Sinuswellen, Rauschen)
• Partikelfelder – BufferGeometry + Points für Sterne, Staub, Schnee, Datenvisualisierung
• Gitterböden – GridHelper oder benutzerdefinierte Liniengeometrie
• Röhren/Tunnel – TubeGeometry entlang eines CatmullRomCurve3-Pfads
• Text – Canvas-Texturen, die auf PlaneGeometry gerendert werden, oder sprite-basiert
• Drahtgitter-Objekte – Beliebige Geometrie mit wireframe: true-Material für einen Tech-Look
• Lichtstrahlen – CylinderGeometry mit emittierendem, transparentem Material

Schritt 7: Maus-Parallaxe (Optional, aber empfohlen)

Füge subtilen Kamera-Offset bei Mausbewegung für Tiefenwahrnehmung hinzu:

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

// In der Render-Schleife einen leichten Offset zur Kamera hinzufügen
const parallaxStaerke = 0.3;
kamera.position.x = camAnim.x + maus.x * parallaxStaerke;
kamera.position.y = camAnim.y - maus.y * parallaxStaerke * 0.5;

Raum-Rundgang-Muster

Für architektonische / Immobilien-Rundgänge baue Räume aus einfacher Geometrie:

// Einen Raum mit BoxGeometry für Wände, Boden, Decke erstellen
function erstelleRaum(breite, hoehe, tiefe, position, farbe) {
  const mat = new THREE.MeshStandardMaterial({ farbe, side: THREE.BackSide });
  const raum = new THREE.Mesh(new THREE.BoxGeometry(breite, hoehe, tiefe), mat);
  raum.position.copy(position);
  szene.add(raum);
  return raum;
}

// Möbelplatzhalter mit einfacher Geometrie erstellen
// Sofa = breite, flache Box, Tisch = dünne Box auf Zylindern, Lampe = Zylinder + Kugel
// Verwende emittierende PointLights in Räumen für warmes Innenraumgefühl

Wichtige Prinzipien für Raumrundgänge:

• Verwende THREE.BackSide auf Materialien, damit Wände von innen gerendert werden
• Platziere warme PointLight-Quellen in jedem Raum (Farbe 0xffeedd, Intensität 0.8)
• Der Kamerapfad sollte durch Türöffnungen eintreten, nicht durch Wände schneiden
• Animiere camera.lookAt, um jeden Raum beim Betreten natürlich zu scannen
• Füge Fensterrechtecke mit emittierendem, hellem Material hinzu, um Tageslicht zu simulieren

Anti-Patterns, die vermieden werden sollten

• ❌ Verwende NICHT OrbitControls – Scrollen sollte die einzige Navigation sein
• ❌ Lade KEINE externen GLTF/GLB-Modelle – bleibe in der HTML-Datei eigenständig
• ❌ Verwende NICHT THREE.CapsuleGeometry – nicht in r128 verfügbar
• ❌ Setze canvas pointer-events: none NICHT global – die Render-Schleife benötigt das Canvas
• ❌ Vergiss NICHT renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)) – verhindert GPU-Überlastung auf Retina-Displays
• ❌ Animiere die Kamera NICHT direkt mit camera.rotation – verwende camera.lookAt() mit animierten Zielkoordinaten für stabile Ergebnisse
• ❌ Mache den Scroll-Container NICHT zu kurz – mindestens 400vh für eine sinnvolle Reise, 600vh+ bevorzugt

Ästhetische Richtung

Wende die gleiche kreative Kühnheit aus dem frontend-design-Skill an. Jede 3D-Scroll-Seite sollte sich einzigartig anfühlen:

• Wähle eine Farbstimmung: Neon-Cyberpunk, warmer Sonnenuntergang, tiefer Ozean, kristallines Eis, dunkle Leere mit emittierenden Akzenten usw.
• Wähle eine Geometrie-Sprache: organische Kurven vs. harte Kanten, spärlich vs. dicht, große Monolithen vs. winzige Partikel
• Typografie-Überlagerung: Importiere charakteristische Google Fonts. Verwende große, filmische Schrift. Animiere Opazität und Transformation beim Scrollen
• Die 3D-Szene und die HTML-Inhalte sollten sich wie eine zusammenhängende Erfahrung anfühlen, nicht wie ein 3D-Hintergrund mit aufgesetztem Text

Kurzreferenz: CDN-URLs

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