Third-Person-MC: Skill for Claude Code

vite-threejs Raycasting System

Overview

本项目的射线系统主要用于 方块交互（挖掘、放置）和 目标选择。

核心原则：始终使用 iMouse.normalizedMouse 获取 NDC 坐标，射线检测结果通过 mitt 事件通知。

When to Use

• 实现点击拾取功能
• 检测鼠标悬停对象
• 实现方块交互（挖掘、放置）
• 添加目标锁定功能

基础 Raycaster 模式

import * as THREE from 'three'
import Experience from './experience.js'
import emitter from './utils/event-bus.js'

export default class ObjectPicker {
  constructor() {
    this.experience = new Experience()
    this.scene = this.experience.scene
    this.camera = this.experience.camera.instance
    this.iMouse = this.experience.iMouse
    
    this.raycaster = new THREE.Raycaster()
    this.intersects = []
    
    // 配置
    this.params = {
      enabled: true,
      maxDistance: 100,
    }
    
    // 绑定事件
    this._handleClick = this._handleClick.bind(this)
    emitter.on('input:mouse_down', this._handleClick)
  }
  
  _handleClick({ button }) {
    if (button !== 0 || !this.params.enabled) return
    
    // 使用 IMouse 的 normalizedMouse（MANDATORY）
    const ndc = this.iMouse.normalizedMouse
    this.raycaster.setFromCamera(ndc, this.camera)
    
    // 检测交叉
    this.intersects = this.raycaster.intersectObjects(
      this.scene.children,
      true  // recursive
    )
    
    if (this.intersects.length > 0) {
      const hit = this.intersects[0]
      emitter.emit('game:object-picked', {
        object: hit.object,
        point: hit.point,
        distance: hit.distance,
      })
    }
  }
  
  destroy() {
    emitter.off('input:mouse_down', this._handleClick)
  }
}

屏幕中心射线（第一人称准星）

const CENTER_SCREEN = new THREE.Vector2(0, 0)

update() {
  // 第一人称：从屏幕中心发射
  this.raycaster.setFromCamera(CENTER_SCREEN, this.camera)
  
  // 或者第三人称：从鼠标位置发射
  // this.raycaster.setFromCamera(this.iMouse.normalizedMouse, this.camera)
  
  const intersects = this.raycaster.intersectObjects(this.targets, true)
  // ...
}

方块交互模式

本项目的 BlockRaycaster 实现了体素方块的射线检测：

// src/js/interaction/block-raycaster.js
export default class BlockRaycaster {
  constructor() {
    this.experience = new Experience()
    this.camera = this.experience.camera.instance
    this.iMouse = this.experience.iMouse
    
    this.raycaster = new THREE.Raycaster()
    this.raycaster.far = 8  // 最大交互距离
    
    this.params = {
      useMouse: false,  // false = 屏幕中心, true = 鼠标位置
    }
    
    this.result = {
      hit: false,
      blockPos: null,
      faceNormal: null,
      adjacentPos: null,  // 放置方块的位置
    }
  }
  
  update(terrainMeshes) {
    // 选择射线原点
    const ndc = this.params.useMouse
      ? this.iMouse.normalizedMouse
      : new THREE.Vector2(0, 0)
    
    this.raycaster.setFromCamera(ndc, this.camera)
    
    const intersects = this.raycaster.intersectObjects(terrainMeshes, false)
    
    if (intersects.length > 0) {
      const hit = intersects[0]
      
      // 计算方块坐标（向下取整到格子中心）
      const blockX = Math.floor(hit.point.x - hit.face.normal.x * 0.5)
      const blockY = Math.floor(hit.point.y - hit.face.normal.y * 0.5)
      const blockZ = Math.floor(hit.point.z - hit.face.normal.z * 0.5)
      
      // 计算相邻方块位置（放置用）
      const adjacentX = blockX + Math.round(hit.face.normal.x)
      const adjacentY = blockY + Math.round(hit.face.normal.y)
      const adjacentZ = blockZ + Math.round(hit.face.normal.z)
      
      this.result = {
        hit: true,
        blockPos: new THREE.Vector3(blockX, blockY, blockZ),
        faceNormal: hit.face.normal.clone(),
        adjacentPos: new THREE.Vector3(adjacentX, adjacentY, adjacentZ),
        distance: hit.distance,
      }
    } else {
      this.result.hit = false
    }
    
    return this.result
  }
}