@anov/3d-controller

ANOV 3D 控制器模块

功能概述

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

通用控制器 (UniversalControls)

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

安装

npm install @anov/3d-controller

使用示例

通用控制器 (UniversalControls)

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文档

UniversalControls

构造函数

constructor(
  scene: Scene,
  camera: PerspectiveCamera | OrthographicCamera,
  domElement: HTMLElement,
  mode: EControlMode = EControlMode.Orbit,
  options = {}
)

控制模式枚举

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

方法

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

注意事项

• 需要预加载角色GLTF模型资源
• 模型需要具备基本的动画功能，动画名称必须为：

'idle'    - 空闲
'walking' - 行走
'running' - 跑步

• 在使用UniversalControls时，如果需要使用第一/第三人称模式，必须提供characterModelUrl
• 在组件卸载时调用dispose()方法清理资源，避免内存泄漏
• 使用deltaTime参数确保在不同帧率下行为一致

性能优化建议

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

许可证

MIT License