Vue3 + Three.js 实战：用GSAP和射线拾取，打造一个可点击移动的3D角色（保姆级避坑指南）

Vue3 + Three.js 实战：用GSAP和射线拾取打造可交互3D角色全流程指南

当3D技术遇上现代前端框架，一场视觉与交互的盛宴就此展开。本文将带您深入探索如何利用Vue3的响应式特性与Three.js的强大3D渲染能力，结合GSAP动画库和射线拾取技术，打造一个具备完整交互逻辑的3D角色控制系统。不同于简单的功能堆砌，我们将从项目架构设计出发，揭示如何优雅地管理复杂动画状态和相机逻辑，避开那些让新手头疼的性能陷阱。

1. 环境搭建与基础配置

在开始3D冒险之前，我们需要搭建一个稳健的开发环境。Vue3的Composition API与Vite的快速构建是完美组合，而Three.js则为我们打开了3D世界的大门。

首先创建一个Vite项目：

npm create vite@latest 3d-character-demo --template vue cd 3d-character-demo npm install three @types/three gsap

基础场景配置是3D应用的骨架。在Vue组件中，我们需要初始化Three.js的核心三要素：场景(Scene)、相机(Camera)和渲染器(Renderer)。

import * as THREE from 'three' import { onMounted, ref } from 'vue' const scene = new THREE.Scene() scene.background = new THREE.Color(0xa0a0a0) const camera = new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 ) camera.position.set(0, 5, 10) const renderer = new THREE.WebGLRenderer({ antialias: true }) renderer.setSize(window.innerWidth, window.innerHeight) renderer.shadowMap.enabled = true

提示：在Vue中使用Three.js时，务必在组件卸载时手动清理资源，避免内存泄漏。可以将渲染器DOM元素的挂载和清理放在onMounted和onUnmounted生命周期钩子中。

环境光和平行光的合理配置能让3D场景更具层次感：

const ambientLight = new THREE.AmbientLight(0x404040) scene.add(ambientLight) const directionalLight = new THREE.DirectionalLight(0xffffff, 0.5) directionalLight.position.set(0, 10, 5) directionalLight.castShadow = true scene.add(directionalLight)

2. 3D角色加载与动画系统

一个生动的3D角色是交互的核心。我们通常使用GLTF格式的模型，它支持包含骨骼动画在内的完整3D场景数据。

首先，我们需要设置GLTF加载器：

import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader' import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader' const loader = new GLTFLoader() const dracoLoader = new DRACOLoader() dracoLoader.setDecoderPath('https://www.gstatic.com/draco/v1/decoders/') loader.setDRACOLoader(dracoLoader)

加载角色模型并初始化动画混合器：

let characterMixer let animations = {} loader.load('/models/character.glb', (gltf) => { const model = gltf.scene model.scale.set(0.5, 0.5, 0.5) scene.add(model) // 初始化动画系统 characterMixer = new THREE.AnimationMixer(model) // 提取动画片段 animations = { idle: gltf.animations.find(a => a.name === 'Idle'), walk: gltf.animations.find(a => a.name === 'Walk'), run: gltf.animations.find(a => a.name === 'Run') } // 播放默认待机动画 playAnimation('idle') })

动画状态管理是交互流畅的关键。我们需要一个平滑过渡系统：

let currentAnimation = 'idle' const animationActions = {} function playAnimation(name) { if (currentAnimation === name) return // 淡出当前动画 if (animationActions[currentAnimation]) { animationActions[currentAnimation].fadeOut(0.2) } // 淡入新动画 const action = characterMixer.clipAction(animations[name]) action.reset().fadeIn(0.2).play() animationActions[name] = action currentAnimation = name }

3. 射线拾取与点击交互实现

射线拾取(Raycasting)是3D交互的核心技术，它能将2D屏幕坐标转换为3D世界中的交互点。

首先设置射线拾取系统：

const raycaster = new THREE.Raycaster() const mouse = new THREE.Vector2() function onMouseClick(event) { // 将鼠标位置归一化为设备坐标 (-1到+1) mouse.x = (event.clientX / window.innerWidth) * 2 - 1 mouse.y = -(event.clientY / window.innerHeight) * 2 + 1 // 更新射线 raycaster.setFromCamera(mouse, camera) // 计算与地面的交点 const groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0) const intersection = new THREE.Vector3() raycaster.ray.intersectPlane(groundPlane, intersection) // 移动角色到点击位置 moveCharacterTo(intersection) }

角色移动需要结合GSAP实现平滑动画：

import gsap from 'gsap' function moveCharacterTo(targetPosition) { // 计算朝向角度 const direction = new THREE.Vector3() direction.subVectors(targetPosition, character.position).normalize() const angle = Math.atan2(direction.x, direction.z) // 旋转角色朝向目标 gsap.to(character.rotation, { y: angle, duration: 0.3 }) // 计算距离决定移动动画类型 const distance = character.position.distanceTo(targetPosition) const isRunning = distance > 5 // 播放相应动画 playAnimation(isRunning ? 'run' : 'walk') // 使用GSAP移动角色 gsap.to(character.position, { x: targetPosition.x, z: targetPosition.z, duration: distance / (isRunning ? 5 : 2), ease: 'power1.out', onComplete: () => { playAnimation('idle') } }) }

4. 键盘控制与相机跟随系统

完整的角色控制需要支持多种输入方式。键盘WASD控制提供了更精确的移动方式。

首先设置键盘状态跟踪：

const keys = { w: false, a: false, s: false, d: false } function onKeyDown(event) { const key = event.key.toLowerCase() if (keys.hasOwnProperty(key)) { keys[key] = true updateMovement() } } function onKeyUp(event) { const key = event.key.toLowerCase() if (keys.hasOwnProperty(key)) { keys[key] = false updateMovement() } }

角色移动逻辑需要结合帧率无关的更新：

const moveSpeed = 0.1 let lastUpdateTime = 0 function updateMovement(time) { // 计算时间增量确保不同帧率下移动速度一致 const deltaTime = time - lastUpdateTime lastUpdateTime = time // 计算移动向量 const moveVector = new THREE.Vector3() if (keys.w) moveVector.z -= 1 if (keys.s) moveVector.z += 1 if (keys.a) moveVector.x -= 1 if (keys.d) moveVector.x += 1 // 标准化向量并应用速度 if (moveVector.length() > 0) { moveVector.normalize() moveVector.multiplyScalar(moveSpeed * deltaTime) // 更新角色位置 character.position.add(moveVector) // 更新角色朝向 if (moveVector.x !== 0 || moveVector.z !== 0) { character.rotation.y = Math.atan2(moveVector.x, moveVector.z) } // 根据移动速度选择动画 playAnimation(moveVector.length() > 0.05 ? 'walk' : 'idle') } else { playAnimation('idle') } // 更新相机位置 updateCamera() }

智能相机跟随能让体验更加自然：

const cameraOffset = new THREE.Vector3(0, 3, -5) function updateCamera() { const targetPosition = character.position.clone().add(cameraOffset) // 使用GSAP平滑过渡相机位置 gsap.to(camera.position, { x: targetPosition.x, y: targetPosition.y, z: targetPosition.z, duration: 0.5 }) // 相机始终看向角色 camera.lookAt(character.position) }

5. 性能优化与常见问题解决

3D应用的性能优化至关重要。以下是几个关键优化点：

渲染性能优化：

• 使用requestAnimationFrame进行渲染循环
• 在不可见时暂停渲染
• 合理使用dispose()方法释放资源

let animationId let lastTime = 0 function animate(time) { const delta = time - lastTime lastTime = time // 更新动画混合器 if (characterMixer) { characterMixer.update(delta * 0.001) } renderer.render(scene, camera) animationId = requestAnimationFrame(animate) } onMounted(() => { animate(0) }) onUnmounted(() => { cancelAnimationFrame(animationId) // 清理所有资源 scene.traverse(object => { if (object.isMesh) { object.geometry.dispose() if (object.material) { if (Array.isArray(object.material)) { object.material.forEach(m => m.dispose()) } else { object.material.dispose() } } } }) })

常见问题解决方案：

1. 模型加载缓慢

   • 使用Draco压缩减少模型大小
   • 实现加载进度指示器
   • 考虑使用低模版本先展示

2. 动画卡顿

   • 确保在requestAnimationFrame中更新动画
   • 减少场景中不必要的复杂几何体
   • 使用stats.js监控帧率

3. 点击不准确

   • 确保射线计算考虑了设备像素比
   • 为交互对象设置合理的边界框
   • 添加点击反馈效果增强用户体验

注意：在移动设备上，需要额外处理触摸事件并考虑性能限制。可以通过降低渲染分辨率或简化场景来提升移动端体验。

6. 进阶技巧与扩展思路

当基础功能实现后，可以考虑以下进阶功能提升用户体验：

路径寻找与障碍规避：

// 简单的路径寻找示例 function findPath(start, end) { // 这里可以实现A*等路径寻找算法 // 返回路径点数组 return [start, end] } // 沿路径移动 function followPath(path) { path.forEach((point, index) => { gsap.to(character.position, { x: point.x, z: point.z, delay: index * 0.5, duration: 0.5, onStart: () => { const nextPoint = path[index + 1] || point const angle = Math.atan2( nextPoint.x - character.position.x, nextPoint.z - character.position.z ) gsap.to(character.rotation, { y: angle, duration: 0.3 }) } }) }) }

状态机管理复杂交互：

class CharacterState { constructor() { this.current = 'idle' this.states = { idle: { transitions: ['walk', 'run'] }, walk: { transitions: ['idle', 'run'] }, run: { transitions: ['idle', 'walk'] } } } transitionTo(newState) { if (this.states[this.current].transitions.includes(newState)) { console.log(`Transition from ${this.current} to ${newState}`) this.current = newState return true } return false } } const characterState = new CharacterState()

多人联机扩展：

• 使用Socket.io实现实时位置同步
• 为每个玩家创建独立的3D角色实例
• 实现简单的碰撞检测避免角色重叠

// 伪代码示例 socket.on('playerMoved', (data) => { if (!otherPlayers[data.id]) { otherPlayers[data.id] = createOtherPlayer() } gsap.to(otherPlayers[data.id].position, { x: data.x, y: data.y, z: data.z, duration: 0.2 }) })

在实现这些功能时，保持代码模块化非常重要。可以将角色控制、动画管理、输入处理等分离为独立的Composable函数或类，这样不仅能提高代码可维护性，也便于后续扩展新功能。