vtj-input-system

vite-threejs Input System

Overview

本项目使用 三层输入系统：

• IMouse：鼠标/触摸位置追踪，提供多种坐标格式
• InputManager：键盘和鼠标按钮状态，通过 mitt 发送事件
• PointerLockManager：FPS 风格鼠标锁定

核心原则：永远使用 iMouse.normalizedMouse 进行射线拾取，永远通过 mitt 事件消费输入。

When to Use

• 实现鼠标交互（点击、拖拽、悬停）
• 添加键盘控制
• 进行射线拾取（Raycasting）
• 处理相机控制输入

输入架构

Window Events (keydown/mousemove/etc)
         │
         ▼
┌────────────────────────────────────────────────────────────┐
│                      Input Layer                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   IMouse     │  │ InputManager │  │ PointerLock  │      │
│  │ (positions)  │  │ (key states) │  │ (FPS mouse)  │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
└─────────┼─────────────────┼─────────────────┼──────────────┘
          │                 │                 │
          ▼                 ▼                 ▼
┌────────────────────────────────────────────────────────────┐
│                    mitt Event Bus                           │
│         input:update, input:jump, input:mouse_move          │
└────────────────────────────────────────────────────────────┘
          │
          ▼
┌────────────────────────────────────────────────────────────┐
│                   Consumer Layer                            │
│   Player, CameraRig, BlockInteraction, BlockRaycaster       │
└────────────────────────────────────────────────────────────┘

IMouse：位置追踪

访问方式

// 通过 Experience 单例访问
this.iMouse = this.experience.iMouse

可用属性

属性	类型	说明
normalizedMouse	Vector2	NDC 坐标 [-1, 1]，用于射线拾取
mouse	Vector2	左下角原点坐标
mouseDOM	Vector2	DOM 坐标 (clientX, clientY)
mouseScreen	Vector2	屏幕中心相对坐标
mouseDOMDelta	Vector2	帧间位移
isMouseMoving	boolean	鼠标是否移动中

射线拾取（MANDATORY PATTERN）

// ✅ ALWAYS: 使用 iMouse.normalizedMouse
const ndc = this.iMouse.normalizedMouse
this.raycaster.setFromCamera(ndc, this.camera)
const intersects = this.raycaster.intersectObjects(this.scene.children)

// ❌ NEVER: 手动计算 NDC
const x = (event.clientX / window.innerWidth) * 2 - 1   // 禁止！
const y = -(event.clientY / window.innerHeight) * 2 + 1 // 禁止！