CommunityProgramación y desarrollogithub.com

interacciones-hero-3d

Haz que el héroe 3D responda al usuario: paralaje de seguimiento del puntero, brillo hover y estados del cursor, reacciones al clic (impulsos, ráfagas de partículas, morphs), arrastrar para rotar, botones magnéticos y fondos reactivos al cursor. Úsalo cuando quieras 3D que 'reaccione a los clics', efectos hover en objetos 3D, paralaje con el ratón, modelos héroe interactivos, rotación por arrastre, explosiones/ráfagas al clic, cursores personalizados o te preguntes por qué el 3D se siente estático/muerto. Combínalo con threejs-interaction, threejs-fundamentals y 3d-physics-simulations.

¿Qué es interacciones-hero-3d?

Esta skill define una jerarquía y metodología para hacer que modelos 3D en escenas héroe se sientan vivos y receptivos. La prioridad es: responder al cursor (hover) > responder a la entrada (clic) > responder al estado inactivo (movimiento ambiental). Implementa un vector de puntero normalizado único con amortiguación para todas las reacciones, paralaje de cámara, inclinación del modelo 3D hacia el cursor, raycasting optimizado solo sobre mallas interactivas, y transiciones suaves en hover (tweens en lugar de cambios instantáneos). Para los clics, ofrece respuestas como impulsos físicos, desplazamiento con resorte de retorno, ráfagas de partículas y morphs de ensamblaje, iniciando la respuesta inmediatamente en 'pointerdown'. También maneja arrastrar para rotar, botones magnéticos en DOM y cursores personalizados con sentido contextual. Incluye advertencias sobre errores comunes como raycasting contra toda la escena, listeners que no se limpian, y conflictos de superposición del canvas. Está diseñada para plataformas como Three.js y se complementa con skills de interacción, fundamentos y simulaciones físicas.

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

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

Documentación

Interacciones Héroe 3D

Un modelo héroe que solo gira es un salvapantallas. La jerarquía de "se siente vivo": responder al cursor (hover) > responder a la entrada (clic) > responder al estado inactivo (movimiento ambiental). Construye en ese orden.

Seguimiento del puntero: un vector normalizado, amortiguado en todas partes

Rastrea el puntero una vez; cada reacción lee el mismo vector NDC a través de un seguidor amortiguado. Nunca dejes que los componentes añadan sus propios listeners.

const pointer = new THREE.Vector2(0, 0);     // crudo, -1..1
const smooth = new THREE.Vector2(0, 0);      // amortiguado
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)); // amortiguación independiente de la frecuencia de cuadros
}
  • Paralaje: desplaza la cámara (o el grupo de la escena) mediante smooth * 0.3 alrededor de un punto de mira — ilusión de profundidad, 3 líneas de código.
  • Inclinación: rota la malla héroe hacia el cursor con un límite de ángulo pequeño (±0.15 rad) — se lee como "mirándote".
  • Constante de amortiguación ~0.001–0.01: más bajo = más pesado, más premium. El seguimiento crudo se siente barato.

Hover: lanzar un rayo a una lista corta, establecer estados del cursor

Lanza el rayo solo a las mallas interactivas del héroe (pasa un array explícito), nunca a toda la escena — un lanzamiento de rayo de 200k triángulos por cada pointermove es cómo las secciones héroe pierden cuadros.

raycaster.setFromCamera(pointer, camera);
const hit = raycaster.intersectObjects(interactives, false)[0];
canvas.style.cursor = hit ? 'pointer' : 'default';
// Al entrar/salir: interpolar emissiveIntensity o escala (1 → 1.04), ver threejs-interaction

Reacciona a las transiciones pointerenter/leave con interpolaciones (lerp durante ~150ms), no cambios instantáneos. En dispositivos táctiles no hay hover — trata los toques como clics y omite los estados hover por completo.

Reacciones al clic (el nivel divertido)

Elige según la intención — clic ⇒ la respuesta guionizada de ese objeto:

  1. Impulso (tiene cuerpo físico): applyImpulse — ver 3d-physics-simulations.
  2. Patada con resorte (sin motor): desplazar + volver a la pose de reposo (v += k*(rest - x); v *= damp). El patrón héroe más robusto.
  3. Ráfaga de partículas: emite N partículas desde el punto de impacto con velocidades radiales + gravedad + desvanecimiento, usando un pool InstancedMesh/Points (recicla, nunca asignes). Plantilla: 3d-physics-simulations → references/gpgpu-particles.md.
  4. Morph/ensamblaje: avanza un valor de mezcla o vuelve a ejecutar una animación de ensamblaje (GSAP sobre uniforms o morph targets).

Retroalimentación ≤16ms después del clic o se siente desconectado: inicia la respuesta en pointerdown, no después de resolver click.

Arrastrar para rotar

Diferencia arrastre de clic mediante un umbral de movimiento (5px) y duración del pointer down. Rota el grupo padre de la malla con velocidad amortiguada; al soltar, aplica inercia y luego vuelve suavemente a la rotación inactiva. Desactiva el control libre tipo OrbitControls en el héroe — la composición debe sobrevivir.

Elementos DOM magnéticos

Los botones a ~80px del cursor se traducen hacia él (límite 6–8px) y vuelven de golpe al salir — se combina con el paralaje 3D para unificar el plano. Mismo seguidor amortiguado, aplicado a transform: translate().

Cursor personalizado

Solo si añade significado (por ejemplo, se convierte en una pista de "agarrar" sobre el héroe): un pequeño punto + anillo trasero, mix-blend-mode: difference, oculto en táctil. Mantén el cursor nativo visible hasta que los estados hover demuestren que el personalizado es necesario — un cursor personalizado que lucha contra el cursor del propio sitio es peor que ninguno.

Errores comunes

  • Lanzar un rayo por pointermove contra toda la escena — haz una lista corta de mallas, o limita a un por cuadro.
  • Listeners añadidos en cada recarga en caliente / cambio de ruta — limpia en el mismo lugar donde los registras.
  • Superposiciones de canvas que se comen los clics destinados al DOM: el canvas recibe pointer-events: none a menos que SEA la superficie de interacción; el DOM flota encima con su propio z-index.
  • Efectos hover en dispositivos solo con pointerdown parpadean — protege el código hover detrás de matchMedia('(hover: hover)').
  • Paralaje sobre una cámara impulsada por desplazamiento de scroll-driven-3d-story sin un único propietario — añade desplazamientos en un solo lugar (grupo rig de cámara), o los beats competirán.

Skills relacionadas

  • threejs-interaction — fundamentos de raycaster/controles
  • 3d-physics-simulations — impulsos y ráfagas
  • scroll-driven-3d-story — la coreografía de cámara en la que esto se integra
  • ai-website-aesthetics — cómo debería verse el héroe

Skills relacionados