Community코딩 & 개발github.com

3D 히어로 상호작용

히어로 3D가 사용자에게 반응하도록 만듭니다: 포인터 추적 시차, 호버 광택 및 커서 상태, 클릭 반응(충격, 입자 폭발, 모프), 드래그 회전, 마그네틱 버튼, 커서 반응형 배경을 제공합니다.

3D 히어로 상호작용란 무엇인가요?

3D 히어로 상호작용은 3D 히어로 모델이 단순히 회전만 하는 '스크린세이버' 수준을 넘어, 실제로 살아 움직이는 듯한 상호작용을 구현하기 위한 종합적인 스킬입니다. 이 스킬은 사용자의 포인터 추적, 호버, 클릭, 드래그 등 다양한 입력에 반응하는 3D 객체를 만드는 방법을 단계별로 제시합니다. Claude Code, Cursor, Codex와 같은 AI 에이전트 플랫폼에서 사용할 수 있으며, 사용자가 '3D가 클릭에 반응한다', '호버 효과', '마우스 시차', '드래그 회전', '클릭 폭발' 등을 요구할 때 자동으로 호출됩니다. `threejs-interaction`, `threejs-fundamentals`, `3d-physics-simulations`와 같은 관련 스킬과 함께 사용하도록 설계되어, Three.js 기반의 진보된 3D 상호작용을 원활하게 구현합니다.

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

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

3D 히어로 상호작용은(는) 무엇을 하나요?

단순히 회전만 하는 히어로 모델은 스크린세이버에 불과합니다. "살아있는 느낌"의 계층 구조: 커서에 반응(호버) > 입력에 반응(클릭) > 유휴 상태에 반응(주변 움직임). 이 순서대로 구축하세요.

포인터 추적: 하나의 정규화된 벡터, 모든 곳에서 감쇠 적용

포인터를 한 번 추적하고, 모든 반응은 동일한 NDC 벡터를 감쇠 추종자를 통해 읽습니다. 컴포넌트가 자체 리스너를 추가하지 못하게 하세요.

const pointer = new THREE.Vector2(0, 0);     // 원시값, -1..1
const smooth = new THREE.Vector2(0, 0);      // 감쇠됨
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)); // 프레임 속도와 무관한 감쇠
}
  • 시차: 카메라(또는 씬 그룹)를 응시점 주변으로 smooth * 0.3만큼 오프셋 — 깊이감, 단 3줄의 코드.
  • 기울기: 히어로 메시를 커서 방향으로 작은 각도 제한(±0.15 rad)으로 회전 — "당신을 바라보는" 느낌.
  • 감쇠 상수 ~0.001–0.01: 낮을수록 무겁고, 더 프리미엄하게 느껴집니다. 원시 추적은 싸구려로 보입니다.

호버: 짧은 목록에 레이캐스트, 커서 상태 설정

히어로의 상호작용 메시에만 레이캐스트(명시적 배열 전달), 전체 씬에 절대 하지 마세요 — pointermove당 200,000 삼각형 레이캐스트는 히어로 섹션의 프레임 드롭 원인입니다.

raycaster.setFromCamera(pointer, camera);
const hit = raycaster.intersectObjects(interactives, false)[0];
canvas.style.cursor = hit ? 'pointer' : 'default';
// 진입/이탈 시: emissiveIntensity 또는 scale 트윈 (1 → 1.04), threejs-interaction 참조

pointerenter/leave 전환에는 트윈(약 150ms 동안 lerp)으로 반응하고, 즉각적인 전환은 피하세요. 터치 기기에는 호버가 없습니다 — 탭을 클릭으로 처리하고 호버 상태는 완전히 건너뜁니다.

클릭 반응 (재미있는 계층)

의도에 따라 선택 — 클릭 ⇒ 해당 객체의 스크립트된 응답:

  1. 충격 (물리 바디 있음): applyImpulse — 3d-physics-simulations 참조.
  2. 스프링 킥 (엔진 없음): 변위 + 휴식 자세로 스프링백 (v += k*(rest - x); v *= damp). 가장 강력한 히어로 패턴.
  3. 입자 폭발: 충돌 지점에서 N개의 입자를 방사 속도 + 중력 + 페이드와 함께 방출, 하나의 InstancedMesh/Points 풀 사용 (재활용, 절대 새로 할당 안 함). 템플릿: 3d-physics-simulations → references/gpgpu-particles.md.
  4. 모프/조립: 블렌드 값을 진행하거나 조립 애니메이션 재실행 (GSAP on uniforms/morph targets).

클릭 후 16ms 이내에 피드백이 없으면 연결이 끊긴 느낌: click 해결 이후가 아닌 pointerdown에서 응답을 시작하세요.

드래그 회전

드래그와 클릭을 움직임 임계값(5px)과 포인터 다운 지속 시간으로 구분하세요. 메시의 부모 그룹을 감쇠 속도로 회전; 놓을 때 관성 적용 후 유휴 회전으로 부드럽게 복귀합니다. 히어로에서 OrbitControls 스타일의 자유 카메라는 비활성화 — 구도가 유지되어야 합니다.

마그네틱 DOM 요소

커서에서 약 80px 이내의 버튼이 커서 방향으로 이동(최대 6–8px)하고 이탈 시 다시 돌아옴 — 3D 시차와 함께 평면을 통합합니다. 동일한 감쇠 추종자를 transform: translate()에 적용합니다.

사용자 정의 커서

의미를 더할 때만 사용하세요(예: 히어로 위에서 "잡기" 힌트 역할): 작은 점 + 뒤따르는 링, mix-blend-mode: difference, 터치에서는 숨김. 사용자 정의가 필요함을 입증할 때까지 기본 커서를 보이게 유지하세요 — 사이트 자체 커서와 싸우는 사용자 정의 커서는 없는 것보다 나쁩니다.

흔한 실수

  • 매 pointermove마다 전체 씬에 레이캐스트 — 메시를 짧은 목록으로 만들거나, 프레임당으로 제한하세요.
  • 모든 핫 리로드/라우트 변경 시 리스너 추가 — 등록한 동일한 위치에서 정리하세요.
  • DOM용 클릭을 잡아먹는 캔버스 오버레이: 캔버스는 상호작용 표면이 아닌 한 pointer-events: none을 받고, DOM은 자체 z-index로 위에 떠 있습니다.
  • pointerdown 전용 기기에서 호버 효과가 깜빡임 — 호버 코드를 matchMedia('(hover: hover)') 뒤에 게이트하세요.
  • scroll-driven-3d-story의 스크롤 구동 카메라 위에 단일 소유자 없이 시차를 적용 — 한 곳(카메라 리그 그룹)에서 오프셋을 추가하거나, 비트가 충돌할 수 있습니다.

관련 스킬

  • threejs-interaction — raycaster/controls 기초
  • 3d-physics-simulations — 충격과 폭발
  • scroll-driven-3d-story — 이것이 연결되는 카메라 안무
  • ai-website-aesthetics — 히어로가 어떻게 보여야 하는지

관련 스킬