CommunityCoding & Developmentgithub.com

3d-hero-interactions

Make hero 3D respond to the user: pointer-tracking parallax, hover glow and cursor states, click reactions (impulses, particle bursts, morphs), drag-to-rotate, magnetic buttons, and cursor-reactive backgrounds. Use whenever the user wants 3D that 'reacts to clicks', hover effects on 3D objects, mouse parallax, interactive hero models, drag rotation, click explosions/bursts, custom cursors, or asks why the 3D feels static/dead. Pair with threejs-interaction, threejs-fundamentals, and 3d-physics-simulations.

What is 3d-hero-interactions?

3d-hero-interactions is a Cursor agent skill that make hero 3D respond to the user: pointer-tracking parallax, hover glow and cursor states, click reactions (impulses, particle bursts, morphs), drag-to-rotate, magnetic buttons, and cursor-reactive backgrounds. Use whenever the user wants 3D that 'reacts to clicks', hover effects on 3D objects, mouse parallax, interactive hero models, drag rotation, click explosions/bursts, custom cursors, or asks why the 3D feels static/dead. Pair with threejs-interaction, threejs-fundamentals, and 3d-physics-simulations.

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

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

3D Hero Interactions

A hero model that only spins is a screensaver. The hierarchy of "feels alive": respond to the cursor (hover) > respond to input (click) > respond to idle (ambient motion). Build in that order.

Pointer tracking: one normalized vector, damped everywhere

Track the pointer once; every reaction reads the same NDC vector through a damped follower. Never let components add their own listeners.

const pointer = new THREE.Vector2(0, 0);     // raw, -1..1
const smooth = new THREE.Vector2(0, 0);      // damped
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)); // frame-rate independent damping
}
  • Parallax: offset camera (or scene group) by smooth * 0.3 around a look-at point — depth illusion, 3 lines of code.
  • Tilt: rotate hero mesh toward cursor with a small angle cap (±0.15 rad) — reads as "watching you".
  • Damping constant ~0.001–0.01: lower = heavier, more premium. Raw tracking feels cheap.

Hover: raycast a shortlist, set cursor states

Raycast only the hero's interactive meshes (pass an explicit array), never the whole scene — a 200k-triangle raycast per pointermove is how hero sections drop frames.

raycaster.setFromCamera(pointer, camera);
const hit = raycaster.intersectObjects(interactives, false)[0];
canvas.style.cursor = hit ? 'pointer' : 'default';
// On enter/leave: tween emissiveIntensity or scale (1 → 1.04), see threejs-interaction

React to pointerenter/leave transitions with tweens (lerp over ~150ms), not instant flips. On touch devices there is no hover — treat taps as clicks and skip hover states entirely.

Click reactions (the fun tier)

Pick per intent — click ⇒ that object's scripted response:

  1. Impulse (has physics body): applyImpulse — see 3d-physics-simulations.
  2. Spring-kick (no engine): displace + spring back to rest pose (v += k*(rest - x); v *= damp). Most robust hero pattern.
  3. Particle burst: emit N particles from hit point with radial velocities + gravity + fade, using one InstancedMesh/Points pool (recycle, never allocate). Template: 3d-physics-simulations → references/gpgpu-particles.md.
  4. Morph/assembly: advance a blend value or re-run an assembly animation (GSAP on uniforms/morph targets).

Feedback ≤16ms after the click or it feels disconnected: start the response on pointerdown, not after click resolution.

Drag-to-rotate

Distinguish drag from click by movement threshold (5px) and pointer down-duration. Rotate the mesh's parent group with damped velocity; on release, apply inertia then ease back to idle rotation. Disable OrbitControls-style free camera on hero — the composition must survive.

Magnetic DOM elements

Buttons within ~80px of the cursor translate toward it (cap 6–8px) and snap back on leave — pairs with the 3D parallax to unify the plane. Same damped follower, applied to transform: translate().

Custom cursor

Only if it adds meaning (e.g., becomes a "grab" hint over the hero): a small dot + trailing ring, mix-blend-mode: difference, hidden on touch. Keep native cursor visible until hover states prove custom is needed — a custom cursor that fights the site's own cursor is worse than none.

Common mistakes

  • Raycasting per pointermove against the full scene — shortlist meshes, or throttle to per-frame.
  • Listeners added on every hot reload / route change — cleanup in the same place you register.
  • Canvas overlays eating clicks meant for DOM: canvas gets pointer-events: none unless it IS the interaction surface; DOM floats above with its own z-index.
  • Hover effects on pointerdown-only devices flicker — gate hover code behind matchMedia('(hover: hover)').
  • Parallax on top of scroll-driven camera from scroll-driven-3d-story without a single owner — add offsets in one place (camera rig group), or the beats will fight.

Related skills

  • threejs-interaction — raycaster/controls fundamentals
  • 3d-physics-simulations — impulses and bursts
  • scroll-driven-3d-story — the camera choreography this plugs into
  • ai-website-aesthetics — what the hero should look like

Related Skills