tsogjavklann/awwwards-3d

Awwwards-kompatible 3D-Websites

Du baust scroll-gesteuerte, kinoreife 3D-Websites im Stil von Active Theory, Lusion, 14islands, Bonhomme, Resn, Studio Freight, Locomotive und Igloo Inc. Das ästhetische Ziel ist hochwertig, langsam, gelerpt, glänzend, atmosphärisch – niemals ruckartig, niemals überladen, niemals Standard.

Kernphilosophie

Lies diese, bevor du Code schreibst. Sie machen den Unterschied zwischen „Three.js-Demo“ und „Awwwards Site of the Day“.

1. Ästhetik > Geometrie. Ein 6-Poly-Würfel mit gutem HDRI, ACES-Filmtönen und Bloom sieht besser aus als ein 200k-Poly-Modell, das von einer einzelnen DirectionalLight beleuchtet wird. Gib dein Budget zuerst für Beleuchtung/Nachbearbeitung aus, zuletzt für Geometrie.
2. Alles lerpen. Kein Wert sollte sich jemals sofort ändern. Kameraposition, -rotation, Scroll-Fortschritt, Mausposition, sogar Raycaster-Ziele – alles läuft durch einen Dämpfungsfaktor (0,06–0,1 ist der Sweet Spot). Die Welt fühlt sich lebendig an, weil nichts ruckelt.
3. Einzel-HTML-Datei, wenn möglich. Standardlieferung ist eine .html-Datei, die ESM-Importe von unpkg (und esm.sh für GSAP) verwendet. Kein Build-Schritt, es sei denn, der Benutzer verlangt explizit einen. Das macht die Arbeit portabel, überprüfbar und teilbar.
4. Mobile zuerst, Leistung immer. Begrenze pixelRatio auf Math.min(devicePixelRatio, 2). Frustum-Culling durchführen. Nachbearbeitung auf mobilen Geräten halbieren. Teste auf einem Mittelklasse-Android in Chrome DevTools, bevor du für fertig erklärst.
5. ACES-Filmtöne sind nicht verhandelbar. renderer.toneMapping = THREE.ACESFilmicToneMapping und renderer.outputColorSpace = THREE.SRGBColorSpace. Ohne das sieht alles flach und „WebGL-mäßig“ aus.
6. metalness > 0 erfordert eine Umgebungskarte. Ein metallisches Material ohne envMap ist ein schwarzer Klumpen. Lade immer ein HDRI (oder verwende RoomEnvironment als Fallback), bevor du Metalle/Glas einführst.
7. 60fps Ziel auf dem Desktop, 30fps Untergrenze auf mobilen Geräten. Wenn du das nicht erreichst, reduziere zuerst die Nachbearbeitungsdurchläufe, bevor du Geometrie entfernst – das Auge bemerkt Rauschen eher als Dreiecke.

Festgelegter Technologie-Stack

Diese Versionen wurden zusammen getestet. Kein Upgrade ohne Nachfrage.

three                       0.170.0
gsap                        3.12.5  (mit ScrollTrigger)
lenis                       1.1.0   (NICHT @studio-freight/lenis – dieser Bereich wurde eingestellt)

Die Nachbearbeitung verwendet Three.js integrierten EffectComposer aus three/addons/postprocessing/. Die eigenständige Bibliothek postprocessing (v6.36.0) wurde getestet und für diesen Skill verworfen – ihre Interna rufen Material.onBeforeRender() auf, das in Three.js r170 entfernt wurde, was pro Material und Frame eine Konsolenwarnung erzeugt. Die integrierten Durchläufe von Three (UnrealBloomPass, OutputPass, ShaderPass, LUTPass, etc.) decken alle benötigten Effekte ohne Versionsabweichungen ab.

Glas verwendet Three.js integriertes MeshPhysicalMaterial mit transmission: 1.0 + dispersion: 1.2 (r166+ Feature – chromatische Refraktion ohne externe Bibliotheken). Das drei-vanilla MeshTransmissionMaterial ist NICHT im Three.js-Kern/Addons; greife nur darauf zurück, wenn du zeitliche Verzerrung oder pro-Objekt Backbuffer-Sampling benötigst (dann füge drei-vanilla und [email protected] zu deiner Importmap hinzu). Siehe PATTERNS.md #5 für beide Pfade.

CDN-Importe verwenden dieses Importmap-Muster (siehe assets/templates/minimal.html für das kanonische Beispiel):

<script type="importmap">
{
  "imports": {
    "three": "https://unpkg.com/[email protected]/build/three.module.js",
    "three/addons/": "https://unpkg.com/[email protected]/examples/jsm/",
    "gsap": "https://esm.sh/[email protected]",
    "gsap/ScrollTrigger": "https://esm.sh/[email protected]/ScrollTrigger",
    "lenis": "https://unpkg.com/[email protected]/dist/lenis.mjs"
  }
}
</script>

Composer-Entscheidung – endgültig: Dieser Skill verwendet Three.js integrierten EffectComposer aus three/addons/postprocessing/. Die eigenständige npm-Bibliothek postprocessing wurde getestet und abgelehnt: [email protected] flaggt Material.onBeforeRender(), das in r170 entfernt wurde, und überflutet die Konsole einmal pro Material und Frame. Die integrierten Durchläufe von Three decken alle Effekte ab, die dieser Skill benötigt (Bloom, Vignette via ShaderPass, Korn via ShaderPass, LUT via LUTPass, Ausgabe-Tonwertkorrektur via OutputPass). Siehe references/POST_PROCESSING.md für die kanonische Durchlaufkette.

CDN-Zuverlässigkeit: Standardmäßig unpkg.com für three und lenis verwenden – es spiegelt die npm-Verzeichnisstruktur exakt wider, sodass three/addons/... sauber aufgelöst wird. cdn.jsdelivr.net wurde getestet und lieferte zeitweise keine [email protected]/examples/jsm/postprocessing/*-Dateien (ERR_CONNECTION_CLOSED) von einigen Netzwerken. Verwende esm.sh für GSAP, weil das der sauberste ESM-Gateway für das GSAP-UMD-Bundle ist. Falls unpkg nicht erreichbar ist, Fallback-Reihenfolge: unpkg → esm.sh → cdn.skypack.dev. Für die Produktion lagere die Dateien lokal aus (/vendor/ – strikte CDN-Abhängigkeit ist nur für Prototypen akzeptabel.

Update-Richtlinie: Die Versionen sind festgelegt, weil sie zusammen getestet wurden. Zum Upgrade: (1) zuerst in assets/templates/minimal.html aktualisieren, (2) alle vier Vorlagen im Browser testen, (3) etwaige Fehler beheben, (4) SKILL.md und PATTERNS.md aktualisieren. Versionen nicht stillschweigend in einer einzelnen Vorlage aktualisieren – Abweichungen zwischen Vorlagen sind die häufigste Ursache für „funktioniert auf meinem Rechner“.

Der 5-Schritte-Workflow

Befolge diese Reihenfolge. Das Überspringen eines Schrittes führt zu „Tech-Demo“-Ausgabe statt „Premium-Seite“-Ausgabe.

Schritt 1 – Identifiziere den Erlebnis-Archetyp

Jede Awwwards-3D-Seite passt in eine dieser Kategorien. Wähle eine aus und bleibe dabei:

Archetyp	Muster	Referenz
Objekt-Präsentation	Einzelnes Heldenobjekt, Kamera umkreist/zoomt beim Scrollen	Bonhomme Produktseiten, Apple AirPods Pro
Raum-Durchgang	Kamerapfad durch 3D-Interieur	Igloo Inc., Bruno Simon Portfolio
Tunnel	Kamera fliegt vorwärts durch endlose Geometrie	Active Theory Experimente
Vertikaler Abstieg	Scrollen = Fallen/Steigen durch Schichten	14islands Fallstudien
Überflug	Kamera durchquert eine Landschaft	Lusion Fallstudien
Partikelfeld	Tausende von Punkten, die auf Scroll/Maus reagieren	Resn Experimente

Frage den Benutzer nach dem Archetyp, wenn er keinen genannt hat. Erfinde keinen neuen – diese sind bewährt.

Schritt 2 – Plane die Assets

Wähle die günstigste Quelle, die den Anforderungen entspricht:

1. Three.js-Primitive (SphereGeometry, BoxGeometry, TorusKnotGeometry) – für abstrakte/Showcase-Arbeiten. Die meisten Awwwards-Seiten verwenden diese. Übersehe sie nicht.
2. Blender via MCP – wenn du eine benutzerdefinierte Form benötigst. Siehe references/BLENDER_PIPELINE.md für Rezepte (Münze, Glaskugel, Klumpen, Low-Poly-Raum) und die GLB-Exportkonfiguration (Draco + KTX2).
3. Polyhaven – HDRIs und Texturen, kostenlos, CC0. Das HDRI ist wichtiger als das Modell.
4. Sketchfab – letzte Resort für fertige Modelle. Überprüfe immer die Polycount.

Schritt 3 – Wähle eine Vorlage aus

Beginne mit assets/templates/:

• minimal.html — leere Szene mit HDRI, Tonwertkorrektur, Lenis, Nachbearbeitung eingerichtet. Verwende als Grundlage für alles Benutzerdefinierte.
• coin-scroll.html — Münze dreht sich und fällt beim Scrollen (Objekt-Präsentation).
• room-walkthrough.html — Kamera bewegt sich entlang einer Spline durch einen Raum (Raum-Durchgang).
• glass-product.html — Einzelnes Produkt mit MeshPhysicalMaterial-Transmission + Dispersion (r166+), HDRI, sanftem Bloom (Objekt-Präsentation, Glas).

Vorlagen sind Ausgangspunkte, keine endgültigen Arbeiten. Entferne, was du nicht brauchst, füge hinzu, was du brauchst.

Schritt 4 – Schichte die Verfeinerung (in dieser Reihenfolge)

Die Reihenfolge ist wichtig. Jede Schicht setzt voraus, dass die vorherige an Ort und Stelle ist.

1. HDRI geladen und als scene.environment angewendet
2. Tonwertkorrektur – ACESFilmicToneMapping, Belichtung 1.0–1.2
3. Beleuchtung – selbst mit HDRI, füge eine DirectionalLight für Schattenrichtung hinzu
4. Nachbearbeitung – Three.js integrierter EffectComposer mit HDR-Ziel → RenderPass → UnrealBloomPass (Stärke ~0,45, Radius 0,4, Schwelle 0,82) → Vignette ShaderPass → OutputPass (wendet renderer.toneMapping = ACESFilmic an) → Korn ShaderPass zuletzt
5. Lenis Smooth-Scroll mit GSAP ScrollTrigger.update verbunden
6. Benutzerdefinierter Cursor (optional, aber eine Signatur von Bonhomme/Lusion)
7. Scroll-Timeline – GSAP-Timeline, gesteuert durch ScrollTrigger, lerpt Kamera-/Objekteigenschaften
8. Filmkorn als letzte Composite-Schicht – benutzerdefinierter ShaderPass mit einem zeitgesteuerten Rauschfragment, Intensität ~0,05 (siehe references/POST_PROCESSING.md § „Pass 5 – Film grain“)

Schritt 5 – Leistungsaudit

Bevor du für fertig erklärst:

• Lighthouse Performance ≥ 85 auf dem Desktop, ≥ 70 auf mobilen Geräten
• FCP < 1,8s, LCP < 2,5s
• 60fps auf dem Desktop, 30fps Minimum auf Mittelklasse-Android
• pixelRatio auf 2 begrenzt
• GLB-Dateien Draco-komprimiert, Texturen nach Möglichkeit KTX2
• Kein console.log innerhalb von requestAnimationFrame-Schleifen (tötet die Leistung in DevTools)
• Alle Animationen durch delta-Zeit gesteuert, nicht durch Frame-Zahl

Harte Regeln – Tue diese niemals

Diese verschiffen kaputte Arbeit. Siehe references/ANTI_PATTERNS.md für die Langfassung.

1. Keine Ruckel-Animationen. Jede Eigenschaftsänderung erfolgt durch Lerp oder GSAP ease.
2. Kein metalness > 0 ohne Umgebungskarte. Ergebnis: schwarze Klumpen.
3. Keine unbegrenzte pixelRatio. Ein 4K-Monitor mit devicePixelRatio = 2 wird auf 15fps fallen.
4. Keine unkomprimierte GLB. Draco-Komprimierung ist obligatorisch (siehe BLENDER_PIPELINE.md).
5. Kein Auto-Play-Audio. Browser blockieren es; Benutzer hassen es.
6. Kein console.log in der Animationsschleife. Selbst eines pro Frame zerstört DevTools.
7. Keine Mischung von CSS-gesteuertem und JS-gesteuertem Scrollen. Lenis besitzt das Scrollen. ScrollTrigger liest von Lenis. scroll-behavior: smooth im CSS muss entfernt werden.
8. Kein OrbitControls in der Produktion. Es ist für Prototypen. Echte Seiten verwenden scroll-gesteuerte Kameras.
9. Kein ShaderMaterial ohne Präzisionsdeklaration. Mobile GPUs benötigen precision mediump float;.
10. Kein Raycasting gegen die gesamte Szene in jedem Frame. Filtere auf ein kleines Array interaktiver Meshes.
11. Keine Frame-zahlbasierte Animation. Jede Bewegung muss von delta aus clock.getDelta() gesteuert und damit multipliziert werden. Ein 144Hz-Monitor und ein 30Hz-Monitor müssen visuell identische Bewegung erzeugen. Verwende für Lerp eine framerate-unabhängige Formel: factor = 1 - Math.pow(1 - ease, delta * 60) anstelle von rohem ease.

Referenzdateien

Lade diese bei Bedarf – lies nicht alle gleich zu Beginn.

• references/ARCHITECTURE.md – Szenenstruktur, Lerp/Scroll-Schleife, Renderreihenfolge
• references/PATTERNS.md – 33 Copy-Paste-Code-Schnipsel für häufige Bedürfnisse
• references/PROCEDURAL_GEOMETRY.md – Code-basierte Geometrieerzeugung; Primitive, math-basierte Formen, Vertex-Verschiebung, hybride Blender-Muster. Der Standardpfad, bevor man KI-3D-Generatoren verwendet.
• references/BLENDER_PIPELINE.md – Blender MCP-Rezepte + GLB-Exportkonfiguration
• references/SHADERS.md – GLSL-Bausteine (Rauschen, Fresnel, Dispersion, benutzerdefinierte Materialien)
• references/POST_PROCESSING.md – Bloom, DOF, Korn, chromatische Aberration Rezepte
• references/TRANSITIONS.md – Barba.js-Seitenübergänge, View Transitions API
• references/ANTI_PATTERNS.md – Langfassung dessen, was die Ästhetik zerstört und warum

Inspirationsarchiv

Wenn der Benutzer unentschlossen ist, verweise ihn hierher. Öffne diese in einem Browser, mache keine Screenshots oder Scrapes.

• Active Theory — https://activetheory.net — Meister des WebGL-Flairs, GLSL-Verzerrungen, handgefertigter Bloom und Dispersion
• Lusion — https://lusion.co — surreale Produktpräsentationen, transmissive Materialien, perfekte Farbkorrektur
• 14islands — https://14islands.com — verspieltes 3D, charakteristische Seitenübergänge, geschmackvolle Typografie über Szenen
• Bonhomme — https://bonhomme.lol — kräftige Typografie trifft auf 3D, unverwechselbare Cursor, art-direction-geführt
• Resn — https://resn.co.nz — atmosphärische Partikelarbeit, traumhafte Paletten, langsame Kamerabewegungen
• Studio Freight — https://studiofreight.com — Autoren von Lenis; Minimalismus + perfekt abgestimmte Glätte
• Locomotive — https://locomotive.ca — ursprüngliche Autoren von Locomotive Scroll; Meisterschaft in der Scroll-Choreografie
• Igloo Inc. — https://igloo.inc — Landschaftsüberflüge, narrative Kadenz, Pixar-gerechte Beleuchtung
• Awwwards Sites of the Day — https://www.awwwards.com/websites/sites_of_the_day/ — tägliches kuratiertes Archiv für aktuelle Trends

Audio (Optional, aber charakteristisch)

~70% der Awwwards-3D-Gewinner enthalten subtiles Audio: Umgebungs-Drones, Hover-Klicks, Scroll-Whooshes. Gut gemacht, ist Audio der Unterschied zwischen „Seite“ und „Erlebnis“. Schlecht gemacht, ist es der Grund, warum Benutzer den Tab in den ersten 2 Sekunden schließen.

Regeln:

• Verwende Howler.js (https://esm.sh/[email protected]) oder die Web Audio API. Kein <audio>-Tag für Umgebungsklänge.
• Immer die Wiedergabe hinter einer Benutzergeste (Button-Klick, Scroll-in-Ansicht nach erstem Viewport) verstecken. Browser blockieren Autoplay ohnehin, aber die UX-Regel ist strenger: Starte niemals einen Sound, den der Benutzer nicht angefordert hat.
• Biete einen dauerhaften Stummschalt-Umschalter in der UI-Ecke an. Standard: AUS auf mobilen Geräten, AUS beim ersten Besuch (verwende localStorage, um die Wahl des Benutzers bei der Rückkehr zu merken).
• Schleife Umgebungsgeräusche bei -18 dB bis -24 dB. UI-Sounds …

… [gekürzt für die Übersetzung]