ANOV 3D 控制器模块

功能概述

该模块提供了基于Three.js的多种3D场景控制器，包括通用控制器和角色控制器，支持多种交互模式和视角切换。

$3

- 多模式支持：轨道控制、地图控制、第一人称、第三人称和飞行模式
- 无缝切换：在不同控制模式之间轻松切换
- 统一接口：提供一致的API接口，简化开发
- 角色控制：WASD键控制前后左右移动，Shift加速跑动
- 视角控制：鼠标拖拽/触摸滑动控制摄像机环绕观察/滚轮缩放
- 动画系统：支持多种动作状态的切换与过渡（站立、行走、奔跑）
- 视角切换：支持第一人称/第三人称视角切换（V键）
- 速度调节：支持使用+/-键调整移动速度
- 飞行模式：在第一人称模式下可启用飞行能力（Q/E键上下移动）

!项目结构图

安装

``bash
npm install @anov/3d-controller
`

使用示例

$3

`typescript
import { Scene, PerspectiveCamera } from '@anov/3d-core';
import { UniversalControls, EControlMode } from '@anov/3d-controller';

// 创建场景和相机
const scene = new Scene();
const camera = new PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);

// 初始化通用控制器
const controls = new UniversalControls(
scene,
camera,
document.body,
EControlMode.Orbit, // 初始模式：轨道控制
{
characterModelUrl: 'assets/character.glb', // 角色模型（用于第一/第三人称模式）
spawnPoint: {
position: new Vector3(0, 0, 0),
rotation: new Euler(0, Math.PI/2, 0)
}
}
);

// 切换控制模式
controls.setMode(EControlMode.Third); // 切换到第三人称模式

// 在动画循环中更新控制器
function animate() {
requestAnimationFrame(animate);
controls.update();
renderer.render(scene, camera);
}
animate();

// 资源清理
function dispose() {
controls.dispose();
}
`




API文档

$3

#### 构造函数
`typescript
constructor(
scene: Scene,
camera: PerspectiveCamera | OrthographicCamera,
domElement: HTMLElement,
mode: EControlMode = EControlMode.Orbit,
options = {}
)
`

#### 控制模式枚举
`typescript
enum EControlMode {
Orbit = 0, // 轨道控制器
Map = 1, // 地图控制器
First = 2, // 第一人称控制器
Third = 3, // 第三人称控制器
Fly = 4 // 飞行控制器
}
`

#### 方法
- setMode(mode: EControlMode): void - 设置控制器模式
- update(): void - 更新控制器状态
- dispose(): void - 清理资源

注意事项


1. 需要预加载角色GLTF模型资源
2. 模型需要具备基本的动画功能，动画名称必须为：
`
'idle' - 空闲
'walking' - 行走
'running' - 跑步
``
3. 在使用UniversalControls时，如果需要使用第一/第三人称模式，必须提供characterModelUrl
4. 在组件卸载时调用dispose()方法清理资源，避免内存泄漏
5. 使用deltaTime参数确保在不同帧率下行为一致

性能优化建议

1. 使用适当的模型多边形数量，避免过于复杂的模型
2. 合理设置相机距离范围，避免渲染过多不必要的场景
3. 在不需要时禁用控制器（设置enabled = false）
4. 使用deltaTime参数确保在不同帧率下行为一致

许可证

MIT License