Communitygithub.com

Narrativa 3D impulsada por scroll

Coreografía de escenas 3D sincronizadas con el desplazamiento de página: movimientos de cámara vinculados al scroll, narración por secciones, héroes fijos, desplazamiento suave y shaders/animaciones basados en progreso de scroll.

¿Qué es Narrativa 3D impulsada por scroll?

Esta habilidad proporciona la arquitectura completa para crear experiencias web narrativas donde el desplazamiento de la página controla una escena 3D. El núcleo del enfoque es mantener un lienzo fijo (position: fixed) detrás del DOM, mientras que el scroll solo actualiza un valor de progreso que la escena interpola. Se recomienda el uso de Lenis para un desplazamiento suave y accesible, y una estructura clara de storyboard que asigna rangos de progreso a estados de la escena (posiciones de cámara, rotaciones, valores de uniformes). La habilidad cubre aspectos clave como curvas de cámara con CatmullRomCurve3, sincronización DOM-3D, rendimiento en móviles (reducción de beats, partículas, postprocesado), accesibilidad (prefers-reduced-motion, fallback sin WebGL) y errores comunes (no secuestrar el scroll, evitar layout thrash, aplicar easing siempre). Está pensada para plataformas como Claude Code, Cursor o Codex, y se complementa con otras habilidades como threejs-animation, ai-website-aesthetics y threejs-postprocessing.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Narrativa 3D impulsada por scroll?

El sello distintivo de los sitios web AI de primer nivel: la página se desplaza, la escena 3D cuenta la historia — la cámara se desliza, los modelos se ensamblan, las partículas se reforman. Esta habilidad es la arquitectura para lograrlo.

Arquitectura: un lienzo fijo, el scroll impulsa un número

El lienzo tiene position: fixed detrás del DOM. El scroll nunca mueve el lienzo — mueve un valor de progreso que la escena interpola. Todo lo demás son detalles de implementación.

// El DOM se desplaza normalmente; solo leemos, nunca secuestramos.
let scrollProgress = 0;
addEventListener('scroll', () => {
  scrollProgress = scrollY / (document.body.scrollHeight - innerHeight);
}, { passive: true });

En el bucle RAF, interpola el estado de la escena desde scrollProgress. Este es el juego completo: construye un storyboard (abajo), luego escribe un interpolador por beat.

El storyboard (siempre haz uno primero)

Antes del código, mapea rangos de scroll a estados de la escena en comentarios o una tabla:

0.00–0.15  hero:    modelo flota en el centro, giro lento, cámara z=8
0.15–0.35  feature: cámara se desplaza a x=-4, modelo se divide en 3 partes
0.35–0.60  tech:    cámara orbita 90°, partículas entran en enjambre, superposición wireframe aparece gradualmente
0.60–0.80  proof:   cámara retrocede, escena se oscurece, tarjetas DOM aparecen sobre el lienzo
0.80–1.00  CTA:     modelo se reensambla en el centro, resplandor florece, cámara z=5

Implementa cada beat como pares (inicio, fin, aplicar(t)); recorta el progreso en cada rango y aplica easing a t antes de aplicar. Interpola posición de cámara, rotación y valores de uniformes entre estados clave — nunca teletransportes a mitad del beat a menos que sea intencionalmente un salto.

Scroll suave: Lenis, no secuestro del scroll

Usa Lenis para la sensación de inercia; aún impulsa el scroll nativo (seguro para accesibilidad):

const lenis = new Lenis({ lerp: 0.1 });
function raf(time) { lenis.raf(time); update3D(); requestAnimationFrame(raf); }
requestAnimationFrame(raf);
  • Nunca bloquees el scroll nativo (overflow: hidden en body) — mata a usuarios de teclado/móvil y al SEO.
  • Si usas GSAP ScrollTrigger en lugar de progreso manual: mantén el lienzo fijo y controla el estado de la escena, no dejes que ScrollTrigger transforme el lienzo.

Rutas de cámara

Para movimientos de múltiples beats, define un THREE.CatmullRomCurve3 a través de posiciones clave y muéstralo con progreso con easing — más suave que interpolar pares de puntos. Los objetivos de mirada obtienen su propia curva. Esto se conecta con threejs-animation para detalles de easing/curvas.

Sincronización DOM + 3D

  • El texto de las secciones es DOM normal; dale mix-blend-mode o paneles translúcidos sobre el lienzo.
  • Sincroniza las revelaciones de secciones con los beats de la escena: dispara animaciones DOM (GSAP o CSS) desde los mismos rangos de scrollProgress — una única fuente de verdad.
  • Ancla etiquetas 3D al espacio de pantalla proyectando posiciones mundiales en cada frame; ocúltalas cuando estén detrás de la cámara.

Rendimiento y móvil

  • Mantén el lienzo a un DPR (límite 1.5–2); las escenas vinculadas al scroll redibujan cada frame independientemente del scroll — elimina otro trabajo por frame.
  • Pausa el renderizado RAF cuando la pestaña o la escena esté fuera de pantalla (document.visibilityState, IntersectionObserver en las secciones).
  • Móvil: reduce los beats (no la longitud del scroll), disminuye el recuento de partículas, desactiva el postprocesado (consulta las habilidades threejs-performance y threejs-postprocessing).
  • iOS Safari: el cambio de tamaño de la barra de direcciones modifica innerHeight a mitad del scroll — desbanca el resize, prefiere altura consciente de visualViewport para el cálculo de progreso si los beats se ven entrecortados.

Accesibilidad y alternativas

  • Respeta prefers-reduced-motion: renderiza el estado final ensamblado como escena estática, omite la coreografía de cámara; el scroll permanece normal.
  • Alternativa sin 3D (GPU débil / failsIf): fondo degradado + misma historia DOM. La historia debe sobrevivir sin WebGL.

Errores comunes

  • Secuestrar eventos de scroll o rueda — la razón #1 por la que los sitios "premium" se sienten rotos.
  • Leer scrollHeight en cada frame (layout thrash) — almacena en caché al redimensionar.
  • Aplicar progreso lineal sin procesar a los movimientos de cámara — siempre aplica easing (slow-in-out) o se siente mecánico.
  • Muchos ScrollTriggers mutando las mismas propiedades de la escena — compiten; canaliza todo a través de un único valor de progreso.
  • Olvidar lenis.raf(time) en el bucle → el scroll se siente muerto.

Habilidades relacionadas

  • threejs-animation — easing, curvas, morphing
  • ai-website-aesthetics — el aspecto de los beats
  • threejs-postprocessing — resplandores que varían entre beats
  • 3d-hero-interactions — el comportamiento de clic/hover del beat hero

Skills relacionados