🎮 俄罗斯方块游戏 (Tetris Game)

一个基于现代 Web 技术构建的完整俄罗斯方块游戏，采用规范驱动开发(Spec-Driven Development)方法论。

✨ 特性亮点

🎯 完整游戏体验

经典俄罗斯方块玩法 - 7 种标准方块类型，完整的旋转和移动机制
智能游戏逻辑 - 行消除、等级提升、分数计算系统
流畅动画效果 - 60FPS 高性能渲染，平滑的方块移动
响应式设计 - 适配不同屏幕尺寸，支持移动端

🎵 多媒体体验

Web Audio 音效引擎 - 程序化生成的音效，无需外部音频文件
背景音乐支持 - 支持循环播放，音量控制
视觉特效 - 行消除动画、等级提升效果

🎮 多平台控制

键盘控制 - 完整的方向键和快捷键支持
触摸控制 - 移动设备手势识别
游戏手柄支持 - 现代浏览器游戏手柄 API
自定义按键映射 - 可配置的控制方案

🔧 开发者友好

性能监控 - 实时 FPS、帧时间、内存使用统计
调试工具 - 内置开发者工具和状态查看
模块化架构 - 清晰的组件分离，易于扩展
完整测试 - 全面的功能验证

🚀 快速开始

在线体验

直接在浏览器中打开 index.html 文件即可开始游戏。

本地运行

# 克隆项目
git clone <repository-url>
cd eluosi-demo

# 启动本地服务器（推荐）
python3 -m http.server 8000
# 或者使用 Node.js
npx serve .

# 在浏览器中访问
open http://localhost:8000

🎮 游戏控制

键盘控制

按键	功能
`←` / `A`	向左移动
`→` / `D`	向右移动
`↓` / `S`	软降落
`↑` / `W`	旋转方块
`空格`	硬降落
`P`	暂停/继续
`R`	重新开始

触摸控制

左右滑动 - 移动方块
向下滑动 - 软降落
点击 - 旋转方块

开发者快捷键

按键	功能
`F1`	显示帮助
`F5`	重新开始游戏
`Ctrl/Cmd + P`	切换性能统计
`Ctrl/Cmd + D`	开发者信息

� 游戏规则

加分系统

游戏采用经典的俄罗斯方块计分规则，不同的操作和成就会获得不同的分数：

基础得分

操作	得分规则	说明
自动下落	0 分	游戏循环自动下落，不计分
软降落	1 分/格	按 ↓ 键主动加速下落，每下降一格得 1 分
硬降落	2 分/格	按空格键瞬间降到底部，每格得 2 分

消行得分

消除方块行会获得基础分数乘以当前等级的分数：

消除行数	基础分数	实际得分（基础分 × 等级）	称号
1 行	100	100 × level	Single
2 行	300	300 × level	Double
3 行	500	500 × level	Triple
4 行	800	800 × level	Tetris 🎉

示例计算：

在第 1 关消除 4 行（Tetris）：800 × 1 = 800 分
在第 5 关消除 4 行（Tetris）：800 × 5 = 4000 分
在第 10 关消除 2 行：300 × 10 = 3000 分

等级系统

起始等级：第 1 级
升级条件：每消除 10 行提升 1 级
最高等级：第 15 级
下落速度：等级越高，方块自动下落速度越快

等级与速度对照表：

等级	下落间隔（毫秒）	每秒下落格数
1-2	1000ms	1 格/秒
3-4	800ms	1.25 格/秒
5-6	600ms	1.67 格/秒
7-8	400ms	2.5 格/秒
9-10	300ms	3.33 格/秒
11-12	200ms	5 格/秒
13-15	100ms	10 格/秒

方块类型

游戏包含 7 种标准俄罗斯方块（Tetromino）：

方块	形状	颜色	特点
I	████	青色	直线型，最利于消 4 行
O	▄▄	黄色	正方形，无法旋转
T	▀█▀	紫色	T 型，最常用
S	▄▀▄	绿色	S 型，左高右低
Z	▄▀▄	红色	Z 型，右高左低
J	▄▀	蓝色	J 型，左转角
L	▀▄	橙色	L 型，右转角

游戏结束

当新生成的方块无法放置在游戏区域顶部时，游戏结束。

记录保存：

最高分数
最高等级
总游戏时长
消除行数统计

高分策略

追求 Tetris：尽量一次消除 4 行获得最高分数
等级优先：快速提升等级来增加消行分数倍率
软降得分：适度使用软降增加基础分数
速度控制：在高等级保持冷静，避免失误

�🏗️ 项目架构

目录结构

eluosi-demo/
├── 📄 index.html              # 主页面
├── 📄 main.js                 # 应用入口
├── 📁 src/                    # 源代码
│   ├── 📄 tetris-engine.js    # 游戏引擎
│   ├── 📁 models/             # 数据模型
│   │   ├── game-state.js      # 游戏状态管理
│   │   ├── game-board.js      # 游戏板逻辑
│   │   ├── tetromino.js       # 方块模型
│   │   └── score-system.js    # 分数系统
│   ├── 📁 services/           # 服务层
│   │   ├── renderer.js        # 渲染引擎
│   │   ├── input-handler.js   # 输入处理
│   │   ├── storage-service.js # 数据存储
│   │   └── sound-service.js   # 音效服务
│   └── 📁 utils/              # 工具函数
│       └── constants.js       # 常量定义
├── 📁 assets/                 # 资源文件
│   └── 📁 styles/
│       └── main.css           # 样式文件
├── 📁 specs/                  # 规范文档
└── 📁 tests/                  # 测试文件

核心组件

🎮 TetrisEngine (游戏引擎)

职责: 整合所有组件，管理游戏循环
特性: 事件驱动、性能监控、错误处理
接口: 公共 API for 游戏控制和状态查询

🎯 GameState (游戏状态)

职责: 游戏逻辑和状态管理
特性: 状态机模式、事件发射、数据验证
包含: 当前方块、游戏板、分数、等级

🎨 Renderer (渲染器)

职责: Canvas2D 渲染和视觉效果
特性: 双缓冲、动画系统、响应式缩放
支持: 方块渲染、网格显示、特效动画

🎮 InputHandler (输入处理)

职责: 多平台输入统一处理
特性: 事件映射、手势识别、按键重复
支持: 键盘、触摸、游戏手柄

💾 StorageService (存储服务)

职责: 数据持久化和管理
特性: 自动保存、数据验证、迁移支持
存储: 游戏设置、统计数据、最高分

🎵 SoundService (音效服务)

职责: 音效和音乐播放
特性: Web Audio API、程序化音效
支持: 背景音乐、游戏音效、音量控制

🎯 规范驱动开发

本项目采用规范驱动开发(Spec-Driven Development)方法论：

开发阶段

📋 Phase 1 - 项目设置和基础结构
🎯 Phase 2 - 核心数据模型实现
🔧 Phase 3 - 服务层组件开发
🎮 Phase 4 - 游戏引擎集成和测试

规范文档

specs/001-tetris-game/spec.md - 完整功能规范
specs/001-tetris-game/plan.md - 开发计划
specs/001-tetris-game/tasks.md - 任务分解

🛠️ 技术栈

前端技术

ES2020+ JavaScript - 现代 JavaScript 特性
Canvas 2D API - 高性能图形渲染
Web Audio API - 音频处理和生成
CSS3 - 现代样式和动画
HTML5 - 语义化标记

开发工具

Git - 版本控制
ESLint - 代码质量检查
Live Server - 开发时热重载

架构模式

MVC 模式 - 模型-视图-控制器分离
事件驱动 - 组件间松耦合通信
服务模式 - 功能服务化
模块化 - ES6 模块系统

📊 性能特性

渲染性能

60FPS 目标 - 流畅的游戏体验
智能渲染 - 只渲染变化的部分
性能监控 - 实时 FPS 和帧时间统计
内存管理 - 避免内存泄漏

优化策略

事件节流 - 防止过度渲染
资源复用 - 减少对象创建
缓存机制 - 优化重复计算
异步加载 - 非阻塞初始化

🎨 自定义配置

游戏设置

// 获取游戏引擎实例
const engine = window.getTetrisEngine();

// 修改游戏配置
engine.setConfig({
  targetFPS: 60, // 目标帧率
  autoSave: true, // 自动保存
  autoSaveInterval: 30000, // 保存间隔(ms)
  showPerformanceStats: false, // 性能统计
  enableEffects: true, // 视觉效果
  enableSound: true, // 音效开关
});

渲染器配置

// 获取渲染器实例
const renderer = engine.renderer;

// 设置渲染选项
renderer.setConfig({
  showGrid: true, // 显示网格
  showGhost: true, // 显示幽灵方块
  blockSize: 30, // 方块大小
  gridColor: "#333333", // 网格颜色
  backgroundColor: "#000000", // 背景颜色
});

🧪 测试验证

功能测试

✅ 游戏初始化和启动
✅ 方块移动和旋转
✅ 行消除逻辑
✅ 分数计算系统
✅ 等级提升机制
✅ 游戏结束检测

性能测试

✅ 60FPS 稳定渲染
✅ 内存使用优化
✅ 响应时间< 16ms
✅ 多平台兼容性

用户体验测试

✅ 响应式布局
✅ 触摸控制
✅ 键盘快捷键
✅ 错误处理

🔧 开发指南

添加新功能

在 specs/ 中更新规范文档
在相应的模型或服务中实现功能
更新游戏引擎集成
添加测试验证
更新文档

调试技巧

// 在浏览器控制台中
const engine = window.getTetrisEngine();

// 查看游戏状态
console.log(engine.getGameState());

// 查看性能统计
console.log(engine.getPerformanceStats());

// 开启性能监控
engine.setConfig({ showPerformanceStats: true });

🐛 问题排查

常见问题

Q: 游戏无法启动 A: 检查浏览器控制台错误，确保通过 HTTP 服务器访问（不是 file://）

Q: 音效无法播放 A: 确保用户已与页面交互（点击或按键），现代浏览器需要用户手势激活音频

Q: 性能问题 A: 开启性能统计(Ctrl/Cmd+P)检查 FPS，考虑降低渲染复杂度

Q: 触摸控制无响应 A: 确保在支持触摸的设备上测试，检查触摸事件是否被正确绑定

🤝 贡献指南

我们欢迎各种形式的贡献！

贡献方式

Bug 报告 - 提交详细的问题描述
功能建议 - 提出新功能想法
代码贡献 - 提交 Pull Request
文档改进 - 完善说明文档
测试用例 - 添加测试覆盖

提交流程

Fork 项目仓库
创建功能分支
实现功能和测试
提交 Pull Request
代码审查和合并

📄 许可证

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

🙏 致谢

Spec-Kit 框架 - 规范驱动开发工具
Web 标准 - HTML5、CSS3、JavaScript ES2020+
开源社区 - 提供的各种工具和库

📞 联系方式

项目仓库: [GitHub 链接]
问题反馈: [Issues 页面]
讨论交流: [Discussions 页面]

🎮 享受游戏时光！ 如果你喜欢这个项目，请给我们一个 ⭐️

最后更新: 2025 年 10 月 21 日

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.github/prompts		.github/prompts
.playwright-mcp		.playwright-mcp
.specify		.specify
assets/styles		assets/styles
specs/001-tetris-game		specs/001-tetris-game
src		src
.gitignore		.gitignore
BUGFIX_SCORING.md		BUGFIX_SCORING.md
LICENSE		LICENSE
PROJECT_OVERVIEW.md		PROJECT_OVERVIEW.md
README.md		README.md
favicon.ico		favicon.ico
index.html		index.html
main.js		main.js

License

OuterCloud/tetris-by-spec-kit

Folders and files

Latest commit

History

Repository files navigation