Community编程与开发github.com

3D英雄交互

让3D英雄模型响应用户操作:指针跟踪视差、悬停发光和光标状态、点击反应(冲量、粒子爆发、变形)、拖拽旋转、磁性按钮和光标反应背景。当用户想要3D物体“响应点击”、悬停效果、鼠标视差、交互式英雄模型、拖拽旋转、点击爆炸/爆发、自定义光标,或者询问为什么3D效果感觉死板/无生气时使用。

3D英雄交互 是什么?

该技能旨在将静态的3D英雄模型转变为动态交互元素,通过分层响应机制(悬停>点击>空闲)赋予其生命力。核心思想是统一管理指针跟踪,将归一化的NDC向量通过阻尼跟随器传递给所有交互组件,避免重复监听。技能覆盖了从基础的视差偏移、模型倾斜,到高级的悬停射线检测、点击后的冲量/粒子爆发/变形反馈,以及拖拽旋转和磁性按钮。特别强调了性能优化,如射线检测仅作用于可交互网格,避免全场景检测。同时提供了平台适配策略(如触摸设备跳过悬停状态)和常见错误避免指南,确保交互流畅、反馈迅速(<16ms),并与相关技能(如threejs交互、物理模拟、滚动驱动故事)协同工作,共同构建高质量的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 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 时对 20 万个三角形进行射线检测是导致英雄区域帧率下降的原因。

raycaster.setFromCamera(pointer, camera);
const hit = raycaster.intersectObjects(interactives, false)[0];
canvas.style.cursor = hit ? 'pointer' : 'default';
// 进入/离开时:对 emissiveIntensity 或 scale(1 → 1.04)进行补间,参见 threejs-interaction

通过补间(约 150ms 的 lerp)来处理 pointerenter/leave 过渡,而不是瞬间切换。在触摸设备上没有悬停状态——将点击视为点击,并完全跳过悬停状态。

点击反应(有趣的内容)

根据意图选择——点击 ⇒ 该对象的脚本化响应:

  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 作用于 uniform 或变形目标)。

点击后反馈响应时间必须 ≤16ms,否则用户会感觉脱节:从 pointerdown 事件开始响应,而不是等到 click 事件解析完成。

拖拽旋转

通过移动阈值(5px)和指针按下持续时间来区分拖拽和点击。旋转网格的父组,带有阻尼速度;释放时,施加惯性,然后缓和回空闲旋转。禁用英雄上的类似 OrbitControls 的自由摄像机——场景构图必须保持不变。

磁性 DOM 元素

距离光标约 80px 以内的按钮会向光标方向平移(上限 6–8px),离开时弹回——与 3D 视差配合,统一平面。使用相同的阻尼跟随器,应用于 transform: translate()。

自定义光标

仅在它能增加意义时才使用(例如,在英雄上方变成“抓取”提示):一个小圆点加一个拖尾环,mix-blend-mode: difference,在触摸设备上隐藏。保持原生光标可见,直到悬停状态证明自定义光标是必要的——一个与网站自身光标冲突的自定义光标比没有更糟糕。

常见错误

  • 每次 pointermove 都对整个场景进行射线检测——使用网格短列表,或者按帧节流。
  • 在每次热重载/路由变化时添加监听器——在注册的地方进行清理。
  • Canvas 叠加层拦截了原本属于 DOM 的点击事件:Canvas 应设置 pointer-events: none,除非它本身就是交互表面;DOM 元素通过自己的 z-index 浮在 Canvas 之上。
  • 在仅支持 pointerdown 的设备上,悬停效果会闪烁——在 matchMedia('(hover: hover)') 条件下才执行悬停代码。
  • 在由 scroll-driven-3d-story 驱动的滚动摄像机之上应用视差,而没有单一所有者——在一个地方(摄像机装备组)添加偏移量,否则这些效果会相互冲突。

相关技能

  • threejs-interaction —— 射线检测器/控件基础
  • 3d-physics-simulations —— 冲量与爆发
  • scroll-driven-3d-story —— 此技能所集成的摄像机编排
  • ai-website-aesthetics —— 英雄区域的外观设计

相关技能