# threejs-practice

**Repository Path**: volatchange/threejs-practice

## Basic Information

- **Project Name**: threejs-practice
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-01-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Three.js 实践项目

一个基于 Three.js 的 3D 场景实践项目，包含樱花树场景、狼模型动画、粒子系统和完整的控制面板。

## 🌟 功能特性

### 场景展示
- **原始示例场景** - 包含立方体、球体、爱心等基础几何体
- **樱花树场景** - 3D 樱花树模型和飘落的樱花粒子
- **狼模型动画** - 狼绕樱花树奔跑的动画效果

### 控制面板
- **相机控制** - 调整相机位置和视角
- **立方体控制** - 旋转、位置、缩放控制
- **材质控制** - 颜色、粗糙度、金属度调节
- **灯光控制** - 方向光和环境光参数调节
- **渲染器控制** - 背景颜色和抗锯齿设置
- **球体控制** - 高级材质参数（清漆层、透射率）
- **地面控制** - 地面材质参数
- **爱心控制** - 爱心形状的旋转、位置、缩放
- **粒子系统** - 原始示例粒子效果参数
- **樱花树** - 樱花树位置和缩放控制
- **樱花粒子** - 飘落速度、数量、风力等参数

### 开发工具
- **代码检查** - ESLint + TypeScript 类型检查
- **提交规范** - Husky + Commitlint + Lint-staged
- **热更新** - Vite 开发服务器

## 🛠 技术栈

- **核心框架**: TypeScript 5.x
- **3D 引擎**: Three.js 0.182.x
- **构建工具**: Vite 7.x
- **GUI 库**: Tweakpane 4.x
- **代码规范**: ESLint
- **Git 钩子**: Husky 9.x + Commitlint
- **包管理器**: pnpm

## 📦 安装依赖

```bash
# 使用 pnpm 安装依赖（推荐）
pnpm install

# 或者使用 npm
npm install

# 或者使用 yarn
yarn install
```

## 🚀 启动开发服务器

```bash
# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 预览生产版本
pnpm preview
```

## 📝 代码规范

### 提交信息规范

项目遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：

```
<type>(<scope>): <subject>
```

**常用类型**：
- `feat` - 新功能
- `fix` - Bug 修复
- `docs` - 文档更新
- `style` - 代码格式（不影响功能）
- `refactor` - 重构
- `perf` - 性能优化
- `test` - 测试相关
- `chore` - 构建或辅助工具更改

**提交示例**：
```
feat(GUIManager): 添加樱花树控制面板

- 新增樱花树位置、旋转、缩放控制
- 新增樱花粒子系统参数控制

Closes #123
```

### 代码检查

```bash
# 运行 ESLint 检查
pnpm lint

# 自动修复 ESLint 问题
pnpm lint:fix

# TypeScript 类型检查
pnpm typecheck
```

## 📁 项目结构

```
threejs/
├── src/
│   ├── main.ts              # 应用入口
│   ├── Application.ts       # Three.js 应用主类
│   ├── World.ts             # 3D 场景管理
│   ├── GUIManager.ts        # 控制面板管理
│   ├── objects/             # 3D 对象
│   │   ├── CubeObject.ts        # 立方体
│   │   ├── SphereObject.ts      # 球体
│   │   ├── GradientCubeObject.ts # 渐变立方体
│   │   ├── ParticleSystem.ts    # 粒子系统
│   │   ├── CherryTree.ts        # 樱花树
│   │   ├── SakuraParticleSystem.ts # 樱花粒子
│   │   └── Wolf.ts              # 狼模型
│   ├── lights/              # 灯光
│   │   └── SceneLights.ts       # 场景灯光
│   ├── materials/           # 材质
│   │   └── SceneMaterials.ts    # 场景材质
│   ├── ground/              # 地面
│   │   └── Ground.ts             # 地面
│   ├── shapes/              # 形状
│   │   └── HeartShape.ts         # 爱心形状
│   ├── textures/            # 纹理
│   │   └── ProceduralTextures.ts # 程序化纹理
│   ├── style.css            # 样式
│   └── vite-env.d.ts        # Vite 类型声明
├── public/
│   └── models/              # 3D 模型
│       ├── Prunus_Pendula_OBJ/  # 樱花树模型
│       └── wolf/                 # 狼模型
├── .husky/                  # Git 钩子
│   ├── pre-commit           # 预提交检查
│   └── commit-msg           # 提交信息检查
├── .lintstagedrc.json       # Lint-staged 配置
├── commitlint.config.js     # Commitlint 配置
├── package.json             # 项目配置
├── tsconfig.json            # TypeScript 配置
└── vite.config.ts           # Vite 配置
```

## 🎮 使用说明

1. **启动项目**: 运行 `pnpm dev` 启动开发服务器
2. **切换场景**: 在控制面板中选择"原始示例"或"樱花树"
3. **调整参数**: 使用控制面板调整场景中的各种参数
4. **相机控制**: 
   - 左键拖拽旋转视角
   - 右键拖拽平移视角
   - 滚轮缩放

## 🔧 扩展开发

### 添加新的 3D 对象

1. 在 `src/objects/` 目录下创建新的对象类
2. 继承 `THREE.Group` 或实现相应接口
3. 在 `World.ts` 中初始化并添加到场景
4. 在 `GUIManager.ts` 中添加控制面板

### 添加新的控制参数

1. 在对应对象类中添加参数属性
2. 在 `GUIManager.ts` 的 `initXXXPanel` 方法中添加绑定
3. 使用 `TpChangeEvent` 监听参数变化

## 📄 许可证

MIT License

## 👤 作者

volatchange

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

- Gitee: [volatchange/threejs-practice](https://gitee.com/volatchange/threejs-practice)