# 3D俄罗斯方块小游戏

**Repository Path**: wang_shiyang123/3d-tetris-mini-game

## Basic Information

- **Project Name**: 3D俄罗斯方块小游戏
- **Description**: threejs+ts实现的3D俄罗斯方块小游戏，使用OOP的模式开发，小项目适合练手
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-18
- **Last Updated**: 2025-11-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3D 俄罗斯方块游戏

一个基于 Three.js 和 TypeScript 开发的 3D 俄罗斯方块游戏，支持完整的游戏机制，包括方块移动、旋转、满行消除和计分系统。

## 🎮 游戏特色

- **3D 视角**: 立体的游戏空间，提供更丰富的游戏体验
- **完整机制**: 包含方块移动、旋转、自动下落、满行消除等核心功能
- **实时计分**: 消除满行即可获得分数，实时显示当前得分
- **流畅动画**: 方块移动和消除都有平滑的动画效果
- **响应式控制**: 支持键盘控制，操作流畅

## 🚀 快速开始

### 环境要求

- Node.js (推荐 v16 或更高版本)
- npm 或 pnpm 包管理器

### 安装依赖

```bash
# 使用 npm
npm install

# 或使用 pnpm
pnpm install
```

### 启动开发服务器

```bash
# 使用 npm
npm run dev

# 或使用 pnpm
pnpm run dev
```

### 构建生产版本

```bash
# 使用 npm
npm run build

# 或使用 pnpm
pnpm run build
```

启动后，在浏览器中打开 `http://localhost:5173` 即可开始游戏。

## 🎯 游戏操作

### 移动控制

| 按键 | 功能 |
|------|------|
| **W** | 向上移动 |
| **A** | 向左移动 |
| **S** | 向下移动 |
| **D** | 向右移动 |
| **Shift (左)** | 快速下落 |

### 旋转控制

| 按键 | 功能 |
|------|------|
| **Q** | 绕 X 轴旋转 |
| **E** | 绕 Y 轴旋转 |
| **R** | 绕 Z 轴旋转 |

### 游戏规则

1. **目标**: 通过移动和旋转方块，填满水平层来消除方块并获得分数
2. **计分**: 每消除一个完整水平层获得 100 分
3. **游戏结束**: 当方块堆积到顶层时游戏结束
4. **重新开始**: 游戏结束后可以点击"重新开始"按钮重新游戏

## 🏗️ 项目结构

```
src/
├── core/                   # 核心游戏逻辑
│   ├── game.ts            # 游戏主控制器
│   ├── gridHandler.ts     # 网格状态管理
│   ├── squareFactory.ts   # 方块工厂
│   ├── sqaureGroup.ts     # 方块组
│   ├── squareMoveHandler.ts # 方块移动逻辑
│   └── GameConfig.ts      # 游戏配置
├── viewer/                # 渲染相关
│   ├── threeViewer.ts     # Three.js 场景管理
│   └── squareViewer.ts    # 方块渲染
├── assets/                # 静态资源
└── index.ts              # 入口文件
```

## 🎮 游戏机制

### 3D 空间

- 游戏空间大小: 8×12×8 (宽×高×深)
- 方块可以在三个维度上移动和旋转
- 满行检测基于水平层 (Y 轴固定)

### 方块系统

- 7 种经典俄罗斯方块形状
- 每个方块由多个小立方体组成
- 支持三轴旋转 (X、Y、Z 轴)

### 消除机制

- 当某个水平层 (Y 坐标相同) 被完全填满时自动消除
- 消除后，上方的方块会自动下落
- 支持同时消除多个水平层

## 🛠️ 技术栈

- **Three.js**: 3D 图形渲染
- **TypeScript**: 类型安全的 JavaScript
- **Vite**: 快速的构建工具
- **CSS3**: UI 样式和动画

## 🎯 开发说明

### 核心类说明

- **Game**: 游戏主控制器，管理游戏状态和流程
- **GridState**: 管理游戏网格数据，处理满行检测
- **SquareGroup**: 方块组，包含多个小方块
- **SquareMoveHandler**: 处理方块的移动和旋转逻辑
- **ThreeViewer**: Three.js 场景管理器

### 扩展开发

如需添加新功能，可以：

1. 在 `squareFactory.ts` 中添加新的方块形状
2. 在 `GameConfig.ts` 中调整游戏参数
3. 在 `game.ts` 中添加新的游戏机制
4. 在 CSS 中自定义 UI 样式

## 🐛 已知问题

- 在某些浏览器中可能需要启用硬件加速以获得最佳性能
- 移动端触控支持尚未实现

## 📝 更新日志

### v1.0.0
- 实现基础的 3D 俄罗斯方块游戏
- 支持方块移动、旋转和自动下落
- 实现满行检测和消除机制
- 添加计分系统和 UI 显示
- 支持游戏重新开始功能

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

## 📄 许可证

MIT License

---

**享受游戏！** 🎮✨