awwwards-3d

Sitios Web 3D Estilo Awwwards

Estás creando experiencias web 3D cinemáticas impulsadas por desplazamiento, en la línea de Active Theory, Lusion, 14islands, Bonhomme, Resn, Studio Freight, Locomotive e Igloo Inc. El objetivo estético es premium, lento, interpolado, brillante, atmosférico — nunca brusco, nunca recargado, nunca por defecto.

Filosofía Central

Léelo antes de tocar código. Son la diferencia entre "demo de Three.js" y "Sitio del Día de Awwwards".

1. Estética > Geometría. Un cubo de 6 polígonos con un buen HDRI, mapeo de tonos ACESFilmic y bloom se ve mejor que un modelo de 200k polígonos iluminado por un solo DirectionalLight. Invierte el presupuesto en iluminación/post-procesamiento primero, geometría al final.
2. Interpola todo. Ningún valor debe cambiar instantáneamente. Posición de cámara, rotación, progreso de desplazamiento, posición del mouse, incluso objetivos de raycaster — todos pasan por un factor de amortiguación (0.06–0.1 es el punto óptimo). El mundo se siente vivo porque nada se mueve bruscamente.
3. HTML de un solo archivo cuando sea posible. El entregable por defecto es un archivo .html que utiliza imports ESM desde unpkg (y esm.sh para GSAP). Sin paso de compilación a menos que el usuario lo solicite explícitamente. Esto es lo que hace que el trabajo sea portátil, revisable y compartible.
4. Mobile primero, rendimiento siempre. Limita pixelRatio a Math.min(devicePixelRatio, 2). Realiza frustum-culling. Reduce el post-procesamiento a la mitad en móvil. Prueba en un Android de gama media en Chrome DevTools antes de declarar terminado.
5. El mapeo de tonos ACESFilmic es innegociable. renderer.toneMapping = THREE.ACESFilmicToneMapping y renderer.outputColorSpace = THREE.SRGBColorSpace. Sin esto, todo se ve plano y "tipo WebGL".
6. metalness > 0 requiere un mapa de entorno. Un material metálico sin envMap es una mancha negra. Siempre carga un HDRI (o usa RoomEnvironment como respaldo) antes de introducir metales/vidrio.
7. Objetivo de 60fps en escritorio, mínimo de 30fps en móvil. Si no se puede alcanzar, reduce los pases de post-procesamiento antes que la geometría — el ojo nota más el ruido que los triángulos.

Stack Tecnológico Bloqueado

Estas versiones están probadas juntas. No actualices sin preguntar.

three                       0.170.0
gsap                        3.12.5  (con ScrollTrigger)
lenis                       1.1.0   (NO @studio-freight/lenis — ese ámbito fue retirado)

El post-procesamiento usa el EffectComposer interno de three desde three/addons/postprocessing/. La biblioteca independiente postprocessing (v6.36.0) fue evaluada y descartada de esta habilidad — sus internos llaman a Material.onBeforeRender(), que three r170 eliminó, produciendo una advertencia en consola por material por fotograma. Los pases integrados de three (UnrealBloomPass, OutputPass, ShaderPass, LUTPass, etc.) cubren todos los efectos que necesitamos sin desviación de versiones.

El vidrio usa el MeshPhysicalMaterial integrado de three con transmission: 1.0 + dispersion: 1.2 (función de r166+ — refracción cromática sin librerías externas). El MeshTransmissionMaterial de drei-vanilla NO está en el núcleo/addons de three; recurre a él solo cuando necesites distorsión temporal o muestreo de backbuffer por objeto (entonces añade drei-vanilla y [email protected] a tu importmap). Consulta PATTERNS.md #5 para ambas rutas.

Las importaciones CDN usan este patrón de importmap (consulta assets/templates/minimal.html para el ejemplo canónico):

<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>

Elección del compositor — decidido: Esta habilidad usa el EffectComposer integrado de three desde three/addons/postprocessing/. La biblioteca npm independiente postprocessing fue probada y rechazada: [email protected] marca Material.onBeforeRender() eliminado en r170, inundando la consola una vez por material por fotograma. Los pases integrados de three cubren todos los efectos que esta habilidad necesita (bloom, viñeta mediante ShaderPass, grano mediante ShaderPass, LUT mediante LUTPass, mapeo de tonos de salida mediante OutputPass). Consulta references/POST_PROCESSING.md para la cadena de pases canónica.

Fiabilidad de CDN: Usa por defecto unpkg.com para three y lenis — refleja exactamente la estructura de directorios de npm, por lo que three/addons/... se resuelve limpiamente. cdn.jsdelivr.net fue probado y falló intermitentemente al servir archivos de [email protected]/examples/jsm/postprocessing/* (ERR_CONNECTION_CLOSED) desde algunas redes. Usa esm.sh para GSAP porque es la puerta de enlace ESM más limpia para el paquete UMD de GSAP. Si unpkg no está disponible, orden de respaldo: unpkg → esm.sh → cdn.skypack.dev. Para producción, aloja los archivos localmente (descárgalos a /vendor/) — la dependencia estricta de CDN solo es aceptable para prototipos.

Política de actualización: Las versiones están bloqueadas porque fueron probadas juntas. Para actualizar: (1) primero incrementa en assets/templates/minimal.html, (2) ejecuta las cuatro plantillas en un navegador, (3) corrige cualquier error, (4) actualiza SKILL.md y PATTERNS.md. No incrementes las versiones silenciosamente en una sola plantilla — la deriva entre plantillas es la fuente #1 de "funciona en mi máquina".

El Flujo de Trabajo en 5 Pasos

Sigue este orden. Saltarse un paso produce un "demo técnico" en lugar de un "sitio premium".

Paso 1 — Identificar el Arquetipo de Experiencia

Cada sitio 3D de Awwwards encaja en uno de estos. Elige uno y comprométete:

Arquetipo	Patrón	Referencia
Showcase de objeto	Un objeto héroe, la cámara orbita/zoom al desplazarse	Páginas de producto de Bonhomme, Apple AirPods Pro
Recorrido de sala	Trayectoria de cámara a través de un interior 3D	Igloo Inc., portafolio de Bruno Simon
Túnel	La cámara vuela hacia adelante a través de geometría infinita	Experimentos de Active Theory
Descenso vertical	Desplazarse = caer/ascender a través de capas	Casos de estudio de 14islands
Sobrevuelo	La cámara atraviesa un paisaje	Casos de estudio de Lusion
Campo de partículas	Miles de puntos que reaccionan al desplazamiento/ratón	Experimentos de Resn

Pregunta al usuario qué arquetipo si no lo han dicho. No inventes uno nuevo — estos están probados.

Paso 2 — Planificar Activos

Elige la fuente más económica que cumpla con el estándar:

1. Primitivas de Three.js (SphereGeometry, BoxGeometry, TorusKnotGeometry) — para trabajos abstractos/showcase. La mayoría de los sitios Awwwards las usan. No las subestimes.
2. Blender vía MCP — cuando necesites una forma personalizada. Consulta references/BLENDER_PIPELINE.md para recetas (moneda, esfera de vidrio, blob, sala low-poly) y la configuración de exportación GLB (Draco + KTX2).
3. Polyhaven — HDRIs y texturas, gratuitas, CC0. El HDRI es más importante que el modelo.
4. Sketchfab — último recurso para modelos prefabricados. Siempre verifica el conteo de polígonos.

Paso 3 — Elegir una Plantilla

Comienza desde assets/templates/:

• minimal.html — escena vacía con HDRI, mapeo de tonos, Lenis, post-procesamiento configurado. Úsalo como base para cualquier cosa personalizada.
• coin-scroll.html — la moneda gira y cae al desplazarse (showcase de objeto).
• room-walkthrough.html — la cámara se mueve a lo largo de una spline a través de una sala (recorrido de sala).
• glass-product.html — un solo producto con MeshPhysicalMaterial transmission + dispersion (r166+), HDRI, bloom suave (showcase de objeto, vidrio).

Las plantillas son puntos de partida, no trabajo final. Elimina lo que no necesites, añade lo que sí.

Paso 4 — Añadir el Pulido (en este orden)

El orden importa. Cada capa asume que la anterior está en su lugar.

1. HDRI cargado y aplicado como scene.environment
2. Mapeo de tonos — ACESFilmicToneMapping, exposición 1.0–1.2
3. Iluminación — incluso con HDRI, añade un DirectionalLight para dirección de sombra
4. Post-procesamiento — EffectComposer integrado de three con destino HDR → RenderPass → UnrealBloomPass (intensidad ~0.45, radio 0.4, umbral 0.82) → viñeta ShaderPass → OutputPass (aplica renderer.toneMapping = ACESFilmic) → grano ShaderPass al final
5. Lenis desplazamiento suave conectado a GSAP ScrollTrigger.update
6. Cursor personalizado (opcional, pero una marca característica de Bonhomme/Lusion)
7. Línea de tiempo de desplazamiento — línea de tiempo de GSAP impulsada por ScrollTrigger, interpolando propiedades de cámara/objeto
8. Grano de película como capa de composición final — ShaderPass personalizado con un fragmento de ruido basado en tiempo, intensidad ~0.05 (consulta references/POST_PROCESSING.md § "Pase 5 — Grano de película")

Paso 5 — Auditoría de Rendimiento

Antes de declarar terminado:

• Lighthouse Rendimiento ≥ 85 en escritorio, ≥ 70 en móvil
• FCP < 1.8s, LCP < 2.5s
• 60fps en escritorio, mínimo 30fps en Android de gama media
• pixelRatio limitado a 2
• Archivos GLB comprimidos con Draco, texturas KTX2 cuando sea posible
• Sin console.log dentro de bucles requestAnimationFrame (mata el rendimiento en DevTools)
• Todas las animaciones impulsadas por tiempo delta, no por conteo de fotogramas

Reglas Estrictas — Nunca Hacer Estas Cosas

Estas envían trabajo roto. Consulta references/ANTI_PATTERNS.md para la versión extendida.

1. Sin animaciones bruscas. Cada cambio de propiedad pasa por lerp o ease de GSAP.
2. Sin metalness > 0 sin un mapa de entorno. Resultado: manchas negras.
3. Sin pixelRatio sin límite. Un monitor 4K con devicePixelRatio = 2 bajará a 15fps.
4. Sin GLB sin comprimir. La compresión Draco es obligatoria (consulta BLENDER_PIPELINE.md).
5. Sin audio de reproducción automática. Los navegadores lo bloquean; los usuarios lo odian.
6. Sin console.log en el bucle de animación. Incluso uno por fotograma destruye DevTools.
7. Sin mezclar desplazamiento impulsado por CSS y JS. Lenis es dueño del desplazamiento. ScrollTrigger lee desde Lenis. scroll-behavior: smooth de CSS debe eliminarse.
8. Sin OrbitControls en producción. Es para prototipado. Los sitios reales usan cámaras impulsadas por desplazamiento.
9. Sin ShaderMaterial sin declaración de precisión. Las GPU móviles necesitan precision mediump float;.
10. Sin raycasting contra toda la escena cada fotograma. Filtra a un pequeño array de mallas interactivas.
11. Sin animación basada en conteo de fotogramas. Todo movimiento debe ser impulsado por delta desde clock.getDelta() y multiplicado por él. Un monitor de 144Hz y uno de 30Hz deben producir movimiento visualmente idéntico. Para lerp, usa una fórmula independiente de la frecuencia de fotogramas: factor = 1 - Math.pow(1 - ease, delta * 60) en lugar de ease puro.

Archivos de Referencia

Cárgalos bajo demanda — no los leas todos al inicio.

• references/ARCHITECTURE.md — estructura de la escena, el bucle de lerp/desplazamiento, orden de renderizado
• references/PATTERNS.md — 33 fragmentos de código copiar-pegar para necesidades comunes
• references/PROCEDURAL_GEOMETRY.md — generación de geometría solo con código; primitivas, formas matemáticas, desplazamiento de vértices, patrones híbridos Blender. La ruta predeterminada antes de recurrir a generadores de IA 3D.
• references/BLENDER_PIPELINE.md — recetas para Blender MCP + configuración de exportación GLB
• references/SHADERS.md — bloques de construcción GLSL (ruido, fresnel, dispersión, materiales personalizados)
• references/POST_PROCESSING.md — recetas de bloom, DOF, grano, aberración cromática
• references/TRANSITIONS.md — transiciones de página Barba.js, API de transiciones de vista
• references/ANTI_PATTERNS.md — lista extendida de lo que mata la estética y por qué

Archivo de Inspiración

Cuando el usuario esté indeciso sobre la dirección, dirígelo aquí. Ábrelos en un navegador, no hagas capturas de pantalla ni raspes.

• Active Theory — https://activetheory.net — maestros del estilo WebGL, distorsiones GLSL, bloom y dispersión artesanales
• Lusion — https://lusion.co — showcases de productos surrealistas, materiales transmisivos, gradación de color perfecta
• 14islands — https://14islands.com — 3D divertido, transiciones de página características, tipografía con gusto sobre escenas
• Bonhomme — https://bonhomme.lol — tipografía audaz combinada con 3D, cursores distintivos, liderado por dirección de arte
• Resn — https://resn.co.nz — trabajo atmosférico con partículas, paletas oníricas, movimientos de cámara lentos
• Studio Freight — https://studiofreight.com — autores de Lenis; minimalismo + suavidad perfectamente ajustada
• Locomotive — https://locomotive.ca — autores originales de Locomotive Scroll; maestría en coreografía de desplazamiento
• Igloo Inc. — https://igloo.inc — sobrevuelos de paisajes, ritmo narrativo, iluminación de nivel Pixar
• Awwwards Sitios del Día — https://www.awwwards.com/websites/sites_of_the_day/ — archivo curado diario de tendencias actuales

Audio (Opcional pero Característico)

~70% de los ganadores de Awwwards 3D incluyen audio sutil: drones ambientales, clics al pasar, silbidos al desplazarse. Bien hecho, el audio es la diferencia entre "sitio" y "experiencia". Mal hecho, es la razón por la que los usuarios cierran la pestaña en los primeros 2 segundos.

Reglas:

• Usa Howler.js (https://esm.sh/[email protected]) o la API de Web Audio. Sin etiqueta <audio> para sonido ambiental.
• Siempre controla la reproducción detrás de un gesto del usuario (clic de botón, desplazarse a la vista más allá del primer viewport). Los navegadores bloquean la reproducción automática de todos modos, pero la regla de UX es más estricta: nunca inicies un sonido que el usuario no pidió.
• Proporciona un interruptor de silencio persistente en la esquina de la UI. Por defecto: APAGADO en móvil, APAGADO en la primera visita (usa localStorage para recordar la elección del usuario al regresar).
• Bucle ambiental a -18 dB a -24 dB. Los sonidos de UI...