Interações de Herói 3D

Faça o herói 3D responder ao usuário: paralaxe de rastreamento do ponteiro, brilho ao passar o mouse e estados do cursor, reações a cliques (impulsos, explosões de partículas, morphs), arrastar para girar, botões magnéticos e planos de fundo reativos ao cursor.

O que é Interações de Herói 3D?

Este skill transforma um modelo 3D estático em uma experiência interativa e responsiva. Ele fornece uma hierarquia clara de interações: primeiro, o cursor deve rastrear e reagir a movimentos (paralaxe, inclinação), depois a entrada de clique (impulsos, explosões de partículas, morphs) e, por fim, movimentos ambientes suaves. É essencial para desenvolvedores que desejam criar heróis 3D que 'reajam a cliques', com efeitos de hover, paralaxe de mouse, rotação por arrasto e cursores personalizados. O skill é compatível com plataformas como Three.js, React Three Fiber e similares, e seu guia prático ensina a implementar rastreamento de ponteiro com damping, raycast otimizado, reações a cliques com física ou animações, e evitar erros comuns como raycasting em toda a cena a cada movimento do mouse. O resultado é uma experiência 3D que 'se sente viva', evitando a sensação de um protetor de tela.

Funciona com~Claude Code~Codex CLI✓Cursor
Part ofReact
npx skills add https://github.com/BLACKNIGHT-cloud12/3d-hero-interactions/tree/HEAD

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

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

Documentação

O que Interações de Herói 3D faz?

Um modelo de herói que apenas gira é um protetor de tela. A hierarquia de 'parece vivo': responder ao cursor (hover) > responder à entrada (clique) > responder ao ócio (movimento ambiente). Construa nessa ordem.

Rastreamento do ponteiro: um vetor normalizado, amortecido em todos os lugares

Rastreie o ponteiro uma vez; toda reação lê o mesmo vetor NDC através de um seguidor amortecido. Nunca deixe componentes adicionarem seus próprios ouvintes.

const pointer = new THREE.Vector2(0, 0);     // bruto, -1..1
const smooth = new THREE.Vector2(0, 0);      // amortecido
addEventListener('pointermove', e => {
  pointer.set((e.clientX / innerWidth) * 2 - 1, -(e.clientY / innerHeight) * 2 + 1);
});
function tick(dt) {
  smooth.lerp(pointer, 1 - Math.pow(0.001, dt)); // amortecimento independente de taxa de quadros
}
  • Paralaxe: desloque a câmera (ou grupo da cena) por smooth * 0.3 em torno de um ponto de mira — ilusão de profundidade, 3 linhas de código.
  • Inclinação: gire a malha do herói em direção ao cursor com um limite de ângulo pequeno (±0.15 rad) — lê-se como 'observando você'.
  • Constante de amortecimento ~0.001–0.01: menor = mais pesado, mais premium. Rastreamento bruto parece barato.

Hover: raycast em uma lista curta, defina estados do cursor

Raycast apenas as malhas interativas do herói (passe um array explícito), nunca a cena inteira — um raycast de 200k triângulos por pointermove é como seções de herói perdem quadros.

raycaster.setFromCamera(pointer, camera);
const hit = raycaster.intersectObjects(interactives, false)[0];
canvas.style.cursor = hit ? 'pointer' : 'default';
// Ao entrar/sair: tween emissiveIntensity ou escala (1 → 1.04), veja threejs-interaction

Reaja a transições pointerenter/leave com tweens (lerp por ~150ms), não mudanças instantâneas. Em dispositivos de toque não há hover — trate toques como cliques e pule estados de hover completamente.

Reações a clique (a camada divertida)

Escolha por intenção — clique ⇒ resposta roteirizada do objeto:

  1. Impulso (tem corpo físico): applyImpulse — veja 3d-physics-simulations.
  2. Chute com mola (sem motor): desloque + retorne à pose de descanso (v += k*(rest - x); v *= damp). Padrão de herói mais robusto.
  3. Explosão de partículas: emita N partículas do ponto de impacto com velocidades radiais + gravidade + desvanecimento, usando um pool InstancedMesh/Points (recicle, nunca aloque). Modelo: 3d-physics-simulations → references/gpgpu-particles.md.
  4. Morph/montagem: avance um valor de blend ou reexecute uma animação de montagem (GSAP em uniforms/alvos de morph).

Feedback ≤16ms após o clique ou parecerá desconectado: inicie a resposta em pointerdown, não após a resolução de click.

Arrastar para girar

Diferencie arrasto de clique por limiar de movimento (5px) e duração do pressionamento do ponteiro. Gire o grupo pai da malha com velocidade amortecida; ao soltar, aplique inércia e depois suavize de volta à rotação de ócio. Desabilite câmera livre ao estilo OrbitControls no herói — a composição deve sobreviver.

Elementos DOM magnéticos

Botões a ~80px do cursor se transladam em direção a ele (limite 6–8px) e retornam ao sair — combina com a paralaxe 3D para unificar o plano. Mesmo seguidor amortecido, aplicado a transform: translate().

Cursor personalizado

Apenas se adicionar significado (ex.: torna-se uma dica 'agarrar' sobre o herói): um pequeno ponto + anel ao redor, mix-blend-mode: difference, oculto em toque. Mantenha o cursor nativo visível até que os estados de hover provem que o personalizado é necessário — um cursor personalizado que luta contra o cursor do próprio site é pior do que nenhum.

Erros comuns

  • Raycasting por pointermove contra a cena inteira — faça uma lista curta de malhas, ou limite a um quadro.
  • Ouvintes adicionados a cada recarga a quente / mudança de rota — limpe no mesmo lugar onde registra.
  • Sobreposições de canvas consumindo cliques destinados ao DOM: canvas recebe pointer-events: none a menos que SEJA a superfície de interação; o DOM flutua acima com seu próprio z-index.
  • Efeitos de hover em dispositivos apenas pointerdown piscam — feche código de hover atrás de matchMedia('(hover: hover)').
  • Paralaxe sobre câmera acionada por rolagem de scroll-driven-3d-story sem um único proprietário — adicione deslocamentos em um lugar (grupo de rig da câmera), ou os ritmos vão brigar.

Skills relacionados

  • threejs-interaction — fundamentos de raycaster/controles
  • 3d-physics-simulations — impulsos e explosões
  • scroll-driven-3d-story — a coreografia da câmera na qual isso se encaixa
  • ai-website-aesthetics — a aparência que o herói deve ter

Habilidades Relacionadas