# three-vue-vite

**Repository Path**: withoutRock/three-vue-vite

## Basic Information

- **Project Name**: three-vue-vite
- **Description**: three+vue+vite
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-01-07
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vite Three Vue - 3D 可视化项目

一个基于 Vue 3、TypeScript 和 Vite 构建的 3D 可视化项目模板，集成了 Three.js 和高级碰撞检测系统。

## 🚀 特性

- **Vue 3** + **TypeScript** + **Vite** 现代前端技术栈
- **Three.js** 强大的 3D 渲染引擎
- **碰撞检测系统** 完整的 AABB 碰撞检测和响应
- **物理模拟** 真实的车辆物理和碰撞反馈
- **视觉特效** 碰撞粒子、屏幕震动、闪光效果
- **调试工具** 完整的可视化调试界面
- **性能优化** 空间分区和缓存策略

## 🎮 演示场景

### 夜间村庄场景
一个完整的交互式 3D 夜间村庄，包含：
- 🚗 可控制的车辆（WASD 移动，空格刹车，L 开关车灯）
- 🏠 程序化生成的村庄建筑
- 💡 动态光照系统（车灯、环境光、窗户灯光）
- 💥 完整的碰撞检测和视觉反馈
- 🎮 多种相机模式（第三人称、第一人称、俯视）

访问地址：`http://localhost:3030/htmls/nightScene.html`

## 🛠️ 安装和运行

### 环境要求
- Node.js >= 18.x
- pnpm（推荐）或 npm

### 安装依赖
```bash
pnpm install
# 或
npm install
```

### 开发模式
```bash
pnpm run start
# 或
npm run start
```
服务器将在 `http://localhost:3030` 启动

### 构建生产版本
```bash
pnpm run build
# 或
npm run build
```

### 预览构建结果
```bash
pnpm run preview
# 或
npm run preview
```

## 🏗️ 碰撞检测系统

本项目实现了一个完整的 3D 碰撞检测系统，包含以下核心组件：

### 核心架构

```
CollisionSystem (主系统)
├── CollisionDetector (检测器)
│   ├── AABB 碰撞检测算法
│   ├── 空间网格优化
│   └── 建筑物边界管理
├── CollisionResponse (响应器)
│   ├── 物理响应计算
│   ├── 位置修正
│   └── 速度调整
├── CollisionDebugger (调试器)
│   ├── 边界框可视化
│   ├── 碰撞点显示
│   ├── 法向量显示
│   └── 性能统计
└── CollisionEffects (特效系统)
    ├── 粒子特效
    ├── 屏幕震动
    ├── 闪光效果
    └── 音效播放
```

### 主要特性

#### 1. 高性能碰撞检测
- **AABB（轴对齐边界框）算法**：快速准确的碰撞检测
- **空间网格分区**：减少不必要的碰撞检测计算
- **距离预筛选**：只检测车辆附近的建筑物

#### 2. 真实物理响应
- **位置修正**：防止对象穿透
- **弹性碰撞**：支持可配置的弹性系数
- **摩擦力模拟**：真实的摩擦效果
- **速度阻尼**：自然的减速效果

#### 3. 丰富的视觉反馈
- **粒子特效**：碰撞时的火花效果
- **屏幕震动**：增强碰撞感
- **闪光特效**：瞬间的视觉冲击
- **音效系统**：碰撞音效反馈

#### 4. 完整的调试工具
- **边界框显示**：可视化碰撞边界
- **碰撞点标记**：精确显示碰撞位置
- **法向量显示**：碰撞方向可视化
- **性能监控**：实时统计和FPS监控

## 🎛️ 调试面板

### 场景设置
- 显示辅助线
- 雾效距离调整
- 时间变化控制

### 车辆设置
- 速度倍率调整
- 相机模式切换

### 灯光设置
- 车灯强度调整
- 车灯开关控制

### 碰撞检测
- 启用/禁用碰撞检测
- 调试模式开关
- 边界框显示
- 碰撞点和法向量显示
- 空间网格可视化
- 响应强度调整
- 弹性强度调整
- 碰撞统计信息

### 碰撞特效
- 粒子特效开关
- 屏幕震动开关
- 闪光特效开关
- 音效开关
- 粒子数量调整
- 震动强度调整

### 性能监控
- 实时 FPS 显示
- 碰撞统计

## 📁 项目结构

```
vite-three-vue/
├── src/
│   ├── components/
│   │   ├── initScene.ts         # 场景初始化
│   │   ├── nightScene.ts        # 夜间村庄场景
│   │   └── ...
│   ├── utils/
│   │   ├── collisionSystem.ts   # 碰撞系统主类
│   │   ├── collisionDetector.ts # 碰撞检测器
│   │   ├── collisionResponse.ts # 碰撞响应器
│   │   ├── collisionDebugger.ts # 碰撞调试器
│   │   ├── collisionEffects.ts  # 碰撞特效系统
│   │   ├── carControls.ts       # 车辆控制器
│   │   ├── lightingSystem.ts    # 光照系统
│   │   ├── villageGenerator.ts  # 村庄生成器
│   │   └── ...
│   ├── pages/
│   │   ├── nightScene.ts        # 夜间场景页面
│   │   └── ...
│   └── shader/                  # GLSL 着色器
├── htmls/
│   ├── nightScene.html          # 夜间场景HTML
│   └── ...
├── public/
│   └── draco/                   # Draco 压缩库
└── ...
```

## 🎯 使用示例

### 基础集成

```typescript
import { CollisionSystem } from './utils/collisionSystem';
import { CollisionEffects } from './utils/collisionEffects';

// 初始化碰撞系统
const collisionSystem = new CollisionSystem(scene, {
  enableCollision: true,
  showBoundingBoxes: false,
  responseStrength: 1.0,
  bounceStrength: 0.3
});

// 初始化特效系统
const collisionEffects = new CollisionEffects(scene, camera, {
  enableParticles: true,
  enableScreenShake: true,
  enableFlash: true
});

// 注册建筑物
buildings.forEach(building => {
  collisionSystem.addBuilding(building);
});

// 在渲染循环中更新
function animate() {
  const deltaTime = clock.getDelta();
  
  // 更新碰撞检测
  const { collisions } = collisionSystem.update(carGroup, carController, deltaTime);
  
  // 更新特效
  collisionEffects.update(deltaTime);
  
  // 触发碰撞特效
  if (collisions.length > 0) {
    collisionEffects.triggerCollisionEffects(collisions);
  }
}
```

### 高级配置

```typescript
// 自定义碰撞响应
collisionSystem.updateConfig({
  responseStrength: 1.5,
  bounceStrength: 0.4
});

// 自定义特效
collisionEffects.updateConfig({
  particleCount: 30,
  shakeIntensity: 0.2,
  flashDuration: 0.3
});

// 事件监听
const collisionSystem = new CollisionSystem(scene, config, {
  onCollisionStart: (collisions) => {
    console.log('碰撞开始！');
    // 自定义处理逻辑
  },
  onCollisionEnd: () => {
    console.log('碰撞结束');
  }
});
```

## 🎮 控制说明

### 车辆控制
- **W** / **↑** - 前进
- **S** / **↓** - 后退
- **A** / **←** - 左转
- **D** / **→** - 右转
- **空格** - 刹车
- **L** - 开关车灯

### 相机控制
- **鼠标拖拽** - 调整视角（俯视模式）
- **滚轮** - 缩放（俯视模式）

## 🔧 技术细节

### 碰撞检测算法
- **AABB（Axis-Aligned Bounding Box）**：快速的轴对齐边界框检测
- **空间分区**：10x10 网格分区减少检测复杂度
- **距离筛选**：只检测车辆附近 3x3 网格内的建筑物

### 性能优化
- **建筑物边界框缓存**：避免重复计算
- **更新频率控制**：约 60fps 的更新频率
- **空间网格索引**：O(1) 的空间查询
- **早期退出**：碰撞冷却机制避免过度计算

### 物理模拟
- **弹性碰撞**：基于碰撞法向量的反射计算
- **摩擦力**：切向速度衰减
- **位置修正**：防止对象穿透的推出算法
- **速度阻尼**：自然的减速效果

## 🤝 贡献指南

1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [Three.js](https://threejs.org/) - 强大的 3D 图形库
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Vite](https://vitejs.dev/) - 下一代前端构建工具
- [Tweakpane](https://cocopon.github.io/tweakpane/) - 轻量级调试面板

## 📞 联系方式

如有问题或建议，请通过以下方式联系：
- 提交 [Issue](../../issues)
- 发起 [Discussion](../../discussions)