Communitygithub.com

Scroll-gesteuerte 3D-Geschichte

Choreografiere 3D-Szenen mit Seiten-Scroll: scroll-verknüpfte Kamerabewegungen, abschnittsweise Szenenerzählung, fixierte Helden, sanftes Scrollen und scrollfortschrittsgesteuerte Shader/Animationen.

Was ist Scroll-gesteuerte 3D-Geschichte?

Diese Fähigkeit definiert die Architektur für Premium-Agenten-Websites, bei denen sich die 3D-Szene beim Scrollen des Benutzers entfaltet und eine Geschichte erzählt. Anstatt das Scrollen zu kapern, wird ein fest positionierter Canvas verwendet, während der DOM normal scrollt. Die Scroll-Position wird in einen Fortschrittswert übersetzt, der die Szene antreibt: Kameraposition, Rotation, Modell-Transformationen, Partikeleffekte und Shader-Uniformen werden alle über einen einzigen `scrollProgress`-Wert zwischen Storyboard-Beats interpoliert. Die Fähigkeit schreibt die Verwendung eines Storyboard-Ansatzes vor, bei dem Scrollbereiche vor dem Programmieren auf Szenenzustände abgebildet werden, die Implementierung jeder Beat-Phase als `(start, end, apply(t))`-Paare erfolgt und die Kamerapfade über `THREE.CatmullRomCurve3`-Kurven erfolgen. Sie unterstützt Lenis für geschmeidiges, zugängliches Scrollen, GSAP ScrollTrigger (als Alternative zur manuellen Fortschrittsberechnung) und lässt sich natürlich in die Fähigkeiten threejs-animation, ai-website-aesthetics und threejs-postprocessing integrieren. Zu den entscheidenden Leistungsaspekten gehören das Begrenzen der DPR auf 1,5-2, das Pausieren des Renderings bei Inaktivität des Tabs, die Reduzierung von Beats für Mobilgeräte und die Verwendung von `visualViewport` für iOS Safari. Barrierefreiheit ist mit `prefers-reduced-motion`-Unterstützung (statische Szene rendern) und einem WebGL-freien Fallback eingebaut; häufige Fehler sind das Kapert von Scroll-Ereignissen, Layout-Thrashing und die direkte Anwendung von linearem Fortschritt ohne Easing.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht Scroll-gesteuerte 3D-Geschichte?

Das Markenzeichen erstklassiger KI-Websites: Die Seite scrollt, die 3D-Szene erzählt die Geschichte — die Kamera gleitet, Modelle setzen sich zusammen, Partikel formieren sich neu. Diese Fähigkeit ist die Architektur dafür.

Architektur: Ein fixierter Canvas, Scroll steuert eine Zahl

Der Canvas ist position: fixed hinter dem DOM. Scrollen bewegt den Canvas nie — es bewegt einen Fortschrittswert, den die Szene interpoliert. Alles andere ist Implementierungsdetail.

// DOM scrollt normal; wir lesen nur, übernehmen nie die Kontrolle.
let scrollProgress = 0;
addEventListener('scroll', () => {
  scrollProgress = scrollY / (document.body.scrollHeight - innerHeight);
}, { passive: true });

In der RAF-Schleife den Szenenzustand aus scrollProgress interpolieren. Das ist das ganze Spiel: Baue ein Storyboard (unten), dann schreibe für jeden Beat einen Interpolator.

Das Storyboard (immer zuerst erstellen)

Vor dem Code Scrollbereiche in Kommentaren oder einer Tabelle auf Szenenzustände abbilden:

0.00–0.15  Held:    Modell schwebt mittig, langsame Drehung, Kamera z=8
0.15–0.35  Feature: Kamera fährt auf x=-4 zu, Modell teilt sich in 3 Teile
0.35–0.60  Technik: Kamera kreist um 90°, Partikel strömen herein, Drahtgitter-Overlay blendet ein
0.60–0.80  Beweis:  Kamera zieht zurück, Szene dimmt, DOM-Karten blenden über den Canvas
0.80–1.00  CTA:     Modell setzt sich mittig wieder zusammen, Glühen entfaltet sich, Kamera z=5

Jeden Beat als (start, end, apply(t))-Paare implementieren; Fortschritt in jeden Bereich klemmen und t vor dem Anwenden mit Easing versehen. Kameraposition, Rotation und Uniform-Werte zwischen keyframed Zuständen interpolieren — niemals mitten im Beat teleportieren, es sei denn, es ist bewusstes Snappen beabsichtigt.

Sanftes Scrollen: Lenis, kein Scroll-Hijacking

Lenis für das Trägheitsgefühl verwenden; es treibt dennoch natives Scrollen (barrierefreiheitssicher):

const lenis = new Lenis({ lerp: 0.1 });
function raf(time) { lenis.raf(time); update3D(); requestAnimationFrame(raf); }
requestAnimationFrame(raf);
  • Niemals natives Scrollen blockieren (overflow: hidden auf Body) — tötet Tastatur-/Mobilnutzer und SEO.
  • Wenn GSAP ScrollTrigger anstelle von manuellem Fortschritt verwendet wird: den Canvas dennoch fixiert lassen und den Szenenzustand antreiben, nicht ScrollTrigger den Canvas transformieren lassen.

Kamerapfade

Bei Multi-Beat-Bewegungen einen THREE.CatmullRomCurve3 durch keyframed Positionen definieren und ihn durch erleichterten Fortschritt abtasten — glatter als Punktpaare zu interpolieren. Look-At-Ziele erhalten ihre eigene Kurve. Bindet an threejs-animation für Easing-/Kurvendetails an.

DOM + 3D-Synchronisation

  • Abschnittstexte sind normales DOM; ihnen mix-blend-mode oder durchscheinende Panels über dem Canvas geben.
  • Abschnitts-Enthüllungen mit Szenen-Beats synchronisieren: DOM-Animationen (GSAP oder CSS) aus denselben scrollProgress-Bereichen auslösen — eine einzige Quelle der Wahrheit.
  • 3D-Beschriftungen im Bildschirmraum verankern, indem Weltpositionen jeden Frame projiziert werden; verstecken, wenn sie hinter der Kamera sind.

Leistung & Mobilgeräte

  • Den Canvas bei einer DPR halten (auf 1,5–2 begrenzen); scroll-verknüpfte Szenen rendern unabhängig vom Scrollen jeden Frame neu — andere Frame-Arbeit reduzieren.
  • Die RAF-Renderung pausieren, wenn der Tab oder die Szene weit außerhalb des Bildschirms ist (document.visibilityState, IntersectionObserver auf Abschnitten).
  • Mobilgeräte: Beats reduzieren (nicht die Scroll-Länge), Partikelanzahlen senken, Nachbearbeitung deaktivieren (siehe Fähigkeiten threejs-performance und threejs-postprocessing).
  • iOS Safari: Die Größenänderung der Adressleiste ändert innerHeight mitten im Scrollen — Größenänderung entprellen, visualViewport-bewusste Höhe für Fortschrittsberechnungen bevorzugen, wenn Beats ruckeln.

Barrierefreiheit & Fallbacks

  • prefers-reduced-motion beachten: den endgültigen zusammengesetzten Zustand als statische Szene rendern, Kamerachoreografie überspringen; Scrollen bleibt normal.
  • 3D-aus Fallback (schwache GPU / failsIf): Gradientenhintergrund + dieselbe DOM-Geschichte. Die Geschichte muss ohne WebGL überleben.

Häufige Fehler

  • Scroll-Ereignisse oder Wheel kapern — der #1 Grund, warum sich „Premium“-Seiten kaputt anfühlen.
  • scrollHeight pro Frame lesen (Layout-Thrashing) — bei Größenänderung cachen.
  • Rohen linearen Fortschritt auf Kamerabewegungen anwenden — immer mit Easing (langsam-ein-aus) versehen, sonst fühlt es sich mechanisch an.
  • Viele ScrollTrigger, die dieselben Szeneneigenschaften mutieren — sie bekämpfen sich; alles über einen einzigen Fortschrittswert leiten.
  • lenis.raf(time) in der Schleife vergessen → Scrollen fühlt sich tot an.

Verwandte Fähigkeiten

  • threejs-animation — Easing, Kurven, Morphing
  • ai-website-aesthetics — das Aussehen der Beats
  • threejs-postprocessing — Bloom-Rampen zwischen Beats
  • 3d-hero-interactions — das Klick-/Hover-Verhalten des Helden-Beats

Verwandte Skills