Communitygithub.com

Narrativa 3D com Rolagem

Coreografe cenas 3D com a rolagem da página: movimentos de câmera vinculados à rolagem, narrativa de cena seção por seção, heróis fixos, rolagem suave e shaders/animações impulsionados pelo progresso da rolagem.

O que é Narrativa 3D com Rolagem?

Esta habilidade, 'Narrativa 3D com Rolagem', fornece uma arquitetura completa para criar experiências web imersivas onde a rolagem da página controla uma cena 3D. Em vez de mover o canvas, a rolagem define um valor de progresso que interpola o estado da cena — câmera, modelos, partículas e shaders — criando uma narrativa visual que se desenrola conforme o usuário desce a página. Ela suporta plataformas como Three.js, Lenis para rolagem suave acessível, e pode ser integrada com GSAP ScrollTrigger para sincronizar animações DOM. A abordagem enfatiza desempenho (limitando DPR, pausando fora da tela), acessibilidade (respeitando prefers-reduced-motion e fornecendo fallback sem WebGL) e boas práticas como storyboards, curvas de câmera CatmullRom e easing suave para evitar sensação mecânica. Erros comuns, como sequestrar eventos de rolagem ou causar thrash de layout, são explicitamente evitados.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Narrativa 3D com Rolagem faz?

A marca registrada dos sites AI de alto nível: a página rola, a cena 3D conta a história — a câmera desliza, modelos se montam, partículas se transformam. Esta habilidade é a arquitetura para isso.

Arquitetura: um canvas fixo, a rolagem impulsiona um número

O canvas está position: fixed atrás do DOM. A rolagem nunca move o canvas — ela move um valor de progresso que a cena interpola. Todo o resto é detalhe de implementação.

// O DOM rola normalmente; nós apenas lemos, nunca sequestramos.
let scrollProgress = 0;
addEventListener('scroll', () => {
  scrollProgress = scrollY / (document.body.scrollHeight - innerHeight);
}, { passive: true });

No loop RAF, interpole o estado da cena a partir de scrollProgress. Este é o jogo todo: construa um storyboard (abaixo), depois escreva um interpolador por batida.

O storyboard (sempre crie um primeiro)

Antes do código, mapeie os intervalos de rolagem para estados da cena em comentários ou uma tabela:

0.00–0.15  hero:    modelo flutua no centro, rotação lenta, câmera z=8
0.15–0.35  feature: câmera dolly para x=-4, modelo se divide em 3 partes
0.35–0.60  tech:    câmera orbita 90°, partículas se aglomeram, wireframe sobreposto aparece
0.60–0.80  proof:   câmera recua, cena escurece, cards DOM aparecem sobre o canvas
0.80–1.00  CTA:     modelo se remonta no centro, brilho floresce, câmera z=5

Implemente cada batida como pares (início, fim, aplicar(t)); limite o progresso em cada intervalo e aplique easing em t antes de aplicar. Interpole a posição da câmera, rotação e valores de uniform entre estados-chave — nunca teletransporte no meio da batida a menos que seja intencionalmente um snap.

Rolagem suave: Lenis, não sequestro de rolagem

Use Lenis para a sensação de inércia; ele ainda impulsiona a rolagem nativa (acessível):

const lenis = new Lenis({ lerp: 0.1 });
function raf(time) { lenis.raf(time); update3D(); requestAnimationFrame(raf); }
requestAnimationFrame(raf);
  • Nunca bloqueie a rolagem nativa (overflow: hidden no body) — mata usuários de teclado/mobile e SEO.
  • Se usar GSAP ScrollTrigger em vez de progresso manual: ainda mantenha o canvas fixo e direcione o estado da cena, não deixe o ScrollTrigger transformar o canvas.

Caminhos de câmera

Para movimentos com várias batidas, defina um THREE.CatmullRomCurve3 através de posições-chave e amostre-o com progresso com easing — mais suave do que lerpar pares de pontos. Os alvos de olhar (look-at) têm sua própria curva. Conecta-se a threejs-animation para detalhes de easing/curvas.

Sincronia DOM + 3D

  • O texto das seções é DOM normal; dê a ele mix-blend-mode ou painéis translúcidos sobre o canvas.
  • Sincronize as revelações das seções com as batidas da cena: dispare animações DOM (GSAP ou CSS) a partir dos mesmos intervalos de scrollProgress — uma única fonte de verdade.
  • Âncoras 3D no espaço da tela projetando posições mundiais a cada quadro; esconda quando estiver atrás da câmera.

Desempenho e mobile

  • Mantenha o canvas em um DPR (limite 1.5–2); cenas vinculadas à rolagem re-renderizam a cada quadro independentemente da rolagem — elimine outro trabalho por quadro.
  • Pause o render RAF quando a aba ou cena estiver longe da tela (document.visibilityState, IntersectionObserver nas seções).
  • Mobile: reduza batidas (não o comprimento da rolagem), diminua contagem de partículas, desabilite pós-processamento (veja as habilidades threejs-performance e threejs-postprocessing).
  • iOS Safari: o redimensionamento da barra de endereço muda innerHeight no meio da rolagem — debounce no resize, prefira altura com visualViewport para o cálculo do progresso se as batidas parecerem instáveis.

Acessibilidade e fallbacks

  • Respeite prefers-reduced-motion: renderize o estado final montado como uma cena estática, pule a coreografia da câmera; a rolagem permanece normal.
  • Fallback sem 3D (GPU fraca / failsIf): fundo gradiente + mesma história DOM. A história deve sobreviver sem WebGL.

Erros comuns

  • Sequestrar eventos de rolagem ou wheel — a razão #1 pela qual sites "premium" parecem quebrados.
  • Ler scrollHeight a cada quadro (layout thrash) — armazene em cache no resize.
  • Aplicar progresso linear bruto a movimentos de câmera — sempre aplique easing (slow-in-out) ou parece mecânico.
  • Muitos ScrollTriggers cada um mutando as mesmas propriedades da cena — eles competem; direcione tudo através de um valor de progresso.
  • Esquecer lenis.raf(time) no loop → a rolagem parece morta.

Habilidades relacionadas

  • threejs-animation — easing, curvas, morphing
  • ai-website-aesthetics — a aparência das batidas
  • threejs-postprocessing — bloom ramps entre batidas
  • 3d-hero-interactions — comportamento de clique/hover da batida hero

Habilidades Relacionadas