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.3around 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:
- Impulse (has physics body):
applyImpulse— see 3d-physics-simulations. - Spring-kick (no engine): displace + spring back to rest pose (
v += k*(rest - x); v *= damp). Most robust hero pattern. - 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.
- 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: noneunless it IS the interaction surface; DOM floats above with its own z-index. - Hover effects on
pointerdown-only devices flicker — gate hover code behindmatchMedia('(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