CommunityCodierung & Entwicklunggithub.com

3d-hero-interactions

Lasse Helden-3D auf Benutzereingaben reagieren: Pointer-Tracking-Parallaxe, Hover-Glow und Cursor-Zustände, Klickreaktionen (Impulse, Partikel-Bursts, Morphs), Drag-to-Rotate, magnetische Buttons und cursor-reaktive Hintergründe.

Was ist 3d-hero-interactions?

Diese Fähigkeit verwandelt ein statisches 3D-Heldenmodell in eine lebendige, interaktive Erfahrung, die auf Mauszeiger und Klicks reagiert. Sie stellt eine Hierarchie der Interaktivität auf: Reaktion auf den Cursor (Hover) > Reaktion auf Eingabe (Klick) > Reaktion auf Leerlauf (Bewegung). Die Implementierung beginnt mit einem einzelnen, gedämpften NDC-Vektor für das Pointer-Tracking, der von allen Komponenten gemeinsam genutzt wird. Hover-Effekte werden durch Raycasting auf einer vordefinierten Liste interaktiver Meshes realisiert, um Performance-Einbußen zu vermeiden. Klickreaktionen umfassen Impulse für Physik-Körper, Feder-Rückstell-Bewegungen, Partikel-Bursts und Morph-Animationen, die innerhalb von 16ms nach dem Klick ausgelöst werden müssen. Drag-to-Rotate wird durch Bewegungsschwellenwerte von echten Klicks unterschieden. Die Fähigkeit behandelt auch magnetische DOM-Elemente, einen benutzerdefinierten Cursor und gängige Fehler wie unnötiges Raycasting oder Hover-Effekte auf Touch-Geräten. Sie ist mit den Fähigkeiten 'threejs-interaction', '3d-physics-simulations' und 'scroll-driven-3d-story' kombinierbar und setzt voraus, dass das Heldenmodell zunächst statisch oder drehend ist.

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

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

3D Helden Interaktionen

Ein Heldenmodell, das sich nur dreht, ist ein Bildschirmschoner. Die Hierarchie von "fühlt sich lebendig an": Auf den Cursor reagieren (Hover) > auf Eingabe reagieren (Klick) > auf Leerlauf reagieren (Bewegung). Baue in dieser Reihenfolge.

Pointer-Tracking: Ein normalisierter Vektor, überall gedämpft

Verfolge den Pointer einmal; jede Reaktion liest denselben NDC-Vektor durch einen gedämpften Folger. Lass niemals Komponenten eigene Listener hinzufügen.

const pointer = new THREE.Vector2(0, 0);     // roh, -1..1
const smooth = new THREE.Vector2(0, 0);      // gedämpft
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-unabhängige Dämpfung
}
  • Parallaxe: Versetze die Kamera (oder die Szenengruppe) um smooth * 0.3 um einen Betrachtungspunkt — Tiefenillusion, 3 Zeilen Code.
  • Neigung: Rotiere das Helden-Mesh in Richtung des Cursors mit einem kleinen Winkel-Limit (±0.15 rad) — wirkt wie "beobachtet dich".
  • Dämpfungskonstante ~0.001–0.01: niedriger = schwerer, hochwertiger. Rohes Tracking wirkt billig.

Hover: Raycasting einer Shortlist, Cursor-Zustände setzen

Führe Raycasting nur auf den interaktiven Meshes des Helden durch (übergib ein explizites Array), niemals auf der gesamten Szene — ein Raycast über 200k Dreiecke pro Pointermove ist der Grund, warum Heldenabschnitte Frames verlieren.

raycaster.setFromCamera(pointer, camera);
const hit = raycaster.intersectObjects(interactives, false)[0];
canvas.style.cursor = hit ? 'pointer' : 'default';
// Bei Enter/Leave: sänftige emissiveIntensity oder Skalierung (1 → 1.04), siehe threejs-interaction

Reagiere auf pointerenter/leave-Übergänge mit Tweens (Lerp über ~150ms), nicht mit sofortigen Umschaltungen. Auf Touch-Geräten gibt es keinen Hover — behandle Taps als Klicks und überspringe Hover-Zustände vollständig.

Klickreaktionen (die lustige Stufe)

Wähle pro Absicht — Klick ⇒ die skriptgesteuerte Antwort des Objekts:

  1. Impuls (mit Physik-Körper): applyImpulse — siehe 3d-physics-simulations.
  2. Feder-Rückstoß (ohne Engine): verschieben + zurückfedern in Ruhepose (v += k*(rest - x); v *= damp;). Das robusteste Helden-Muster.
  3. Partikel-Burst: Emittiere N Partikel vom Treffpunkt mit radialen Geschwindigkeiten + Schwerkraft + Verblassen, unter Verwendung eines InstancedMesh/Points-Pools (recyceln, niemals allozieren). Vorlage: 3d-physics-simulations → references/gpgpu-particles.md.
  4. Morph/Assembly: Erhöhe einen Blend-Wert oder führe eine Assembly-Animation erneut aus (GSAP auf Uniforms/Morph-Targets).

Rückmeldung ≤16ms nach dem Klick, sonst fühlt es sich unzusammenhängend an: Starte die Reaktion bei pointerdown, nicht nach Auflösung von click.

Drag-to-Rotate

Unterscheide Drag von Klick durch einen Bewegungsschwellenwert (5px) und Pointer-Down-Dauer. Rotiere die übergeordnete Gruppe des Meshes mit gedämpfter Geschwindigkeit; beim Loslassen Trägheit anwenden, dann sanft zur Ruheposition zurückführen. Deaktiviere OrbitControls-artige freie Kamera auf dem Helden — die Komposition muss erhalten bleiben.

Magnetische DOM-Elemente

Buttons innerhalb von ~80px um den Cursor verschieben sich in seine Richtung (Begrenzung 6–8px) und springen beim Verlassen zurück — paart sich mit der 3D-Parallaxe, um die Ebene zu vereinheitlichen. Derselbe gedämpfte Folger, angewendet auf transform: translate().

Benutzerdefinierter Cursor

Nur, wenn er eine Bedeutung hinzufügt (z. B. wird er zu einem "Greifen"-Hinweis über dem Helden): ein kleiner Punkt + nachlaufender Ring, mix-blend-mode: difference, auf Touch-Geräten versteckt. Behalte den nativen Cursor sichtbar, bis Hover-Zustände zeigen, dass ein benutzerdefinierter benötigt wird — ein benutzerdefinierter Cursor, der mit dem eigenen Cursor der Seite kämpft, ist schlimmer als keiner.

Häufige Fehler

  • Raycasting pro Pointermove gegen die gesamte Szene — erstelle eine Shortlist von Meshes oder drossele auf pro Frame.
  • Listener, die bei jedem Hot Reload / Routenwechsel hinzugefügt werden — räume an derselben Stelle auf, an der du sie registrierst.
  • Canvas-Overlays, die für DOM bestimmte Klicks verschlucken: Canvas erhält pointer-events: none, es sei denn, es IST die Interaktionsfläche; DOM schwebt mit eigenem z-index darüber.
  • Hover-Effekte auf pointerdown-nur-Geräten flackern — sperre Hover-Code hinter matchMedia('(hover: hover)').
  • Parallaxe zusätzlich zu scrollgesteuerter Kamera aus scroll-driven-3d-story ohne einen einzigen Besitzer — füge Offsets an einer Stelle hinzu (Kamera-Rig-Gruppe), sonst bekämpfen sich die Bewegungen.

Verwandte Fähigkeiten

  • threejs-interaction — Grundlagen von Raycaster/Controls
  • 3d-physics-simulations — Impulse und Bursts
  • scroll-driven-3d-story — die Kamerachoreographie, an die dies angeschlossen wird
  • ai-website-aesthetics — wie der Held aussehen sollte

Verwandte Skills