diff --git a/README.md b/README.md index 7204e54..4a9643c 100755 --- a/README.md +++ b/README.md @@ -1,80 +1,237 @@ -# Tetris Game +# Tetris Game | 俄罗斯方块 -A classic Tetris game implemented in Go using the Ebitengine game engine. +一个使用 Go 语言和 Ebitengine 游戏引擎实现的经典俄罗斯方块游戏,支持中英文双语界面。 -## Features +A classic Tetris game implemented in Go using the Ebitengine game engine with bilingual support (Chinese/English). -- Classic Tetris gameplay -- Ghost piece preview -- Next piece preview -- Line clearing with scoring -- Progressive difficulty levels -- Smooth controls with wall kicks +## ✨ 特性 | Features -## Project Structure +### 🎮 游戏特性 | Game Features +- ✅ 经典俄罗斯方块玩法 | Classic Tetris gameplay +- 👻 半透明幽灵方块预览 | Transparent ghost piece preview +- 🔮 下一个方块预览 | Next piece preview +- 💥 消除行数计分系统 | Line clearing with scoring system +- 📈 渐进式难度等级 | Progressive difficulty levels +- 🎯 平滑控制与踢墙系统 | Smooth controls with wall kicks +- ⚡ 硬降落特效 | Hard drop visual effects +- 🎨 彩色方块显示 | Colorful block rendering + +### 🌍 多语言支持 | Multi-language Support +- 🇺🇸 **English** - 完整英文界面 | Full English interface +- 🇨🇳 **中文** - 完整中文界面 | Full Chinese interface +- 🔄 实时语言切换 | Real-time language switching (Press **L** key) + +### 🖥️ 平台支持 | Platform Support +- 🪟 **Windows** (64-bit) - 包含安装包和启动脚本 +- 🍎 **macOS** (10.15+) - 原生 .app 应用包 +- 🐧 **Linux** (64-bit) - 支持 X11/Wayland 显示系统 + +## 🎯 游戏控制 | Game Controls + +| 键位 | 功能 | Key | Function | +|------|------|-----|----------| +| ← → | 左右移动方块 | ← → | Move piece horizontally | +| ↑ | 顺时针旋转方块 | ↑ | Rotate piece clockwise | +| ↓ | 软降落 (加速下降) | ↓ | Soft drop (faster falling) | +| 空格 | 硬降落 (瞬间落底) | Space | Hard drop (instant drop) | +| L | 切换中英文界面 | L | Switch language | +| R | 重新开始游戏 | R | Restart game (when game over) | +| Esc | 退出游戏 | Esc | Exit game | + +## 🏗️ 项目结构 | Project Structure ``` tetris/ -├── main.go # Application entry point -├── go.mod # Go module definition -├── go.sum # Go module checksums -├── assets/ # Game assets (future use) -├── internal/ # Internal packages -│ ├── game/ # Core game logic -│ │ └── game.go # Game state and rendering -│ ├── tetromino/ # Tetromino (falling pieces) logic -│ │ └── tetromino.go # Piece shapes, rotation, movement -│ └── types/ # Shared type definitions -│ └── types.go # Block types and colors -└── pkg/ # Public packages - └── config/ # Configuration constants - └── config.go # Game configuration and constants +├── main.go # 应用程序入口 | Application entry point +├── go.mod # Go 模块定义 | Go module definition +├── go.sum # Go 模块校验和 | Go module checksums +├── Makefile # 构建系统 | Build system +├── BUILD.md # 构建说明文档 | Build documentation +├── build.sh # 构建脚本 | Build script +├── assets/ # 游戏资源文件 | Game assets +│ ├── fonts/ # 字体文件 | Font files +│ │ └── HYSongYunLangHeiW-1.ttf # 中文字体 +│ └── icons/ # 图标文件 | Icon files +├── internal/ # 内部包 | Internal packages +│ ├── game/ # 核心游戏逻辑 | Core game logic +│ │ └── game.go # 游戏状态和渲染 | Game state and rendering +│ ├── tetromino/ # 俄罗斯方块逻辑 | Tetromino logic +│ │ └── tetromino.go # 方块形状、旋转、移动 | Piece shapes, rotation, movement +│ ├── types/ # 共享类型定义 | Shared type definitions +│ │ └── types.go # 方块类型和颜色 | Block types and colors +│ ├── font/ # 字体渲染系统 | Font rendering system +│ │ └── font.go # 字体渲染器 | Font renderer +│ └── i18n/ # 国际化支持 | Internationalization +│ └── i18n.go # 多语言文本 | Multi-language text +├── pkg/ # 公共包 | Public packages +│ └── config/ # 配置常量 | Configuration constants +│ └── config.go # 游戏配置和常量 | Game configuration +└── dist/ # 分发文件 | Distribution files (generated) + ├── TetrisGame-Windows-v1.0.zip # Windows 分发包 + ├── TetrisGame-macOS-v1.0.dmg # macOS 分发包 + └── TetrisGame-Linux-v1.0.tar.gz # Linux 分发包 ``` -## Architecture +## 🏛️ 架构设计 | Architecture + +项目遵循 Go 语言最佳实践,采用清晰的包结构设计: The project follows Go best practices with a clean package structure: -- **`main.go`**: Entry point that initializes the game -- **`pkg/config`**: Contains all game configuration constants -- **`internal/types`**: Defines core data types and enums -- **`internal/tetromino`**: Handles tetromino piece logic (shapes, rotation, movement) -- **`internal/game`**: Core game mechanics (board state, input handling, rendering) +- **`main.go`**: 应用程序入口,初始化游戏 | Entry point that initializes the game +- **`pkg/config`**: 包含所有游戏配置常量 | Contains all game configuration constants +- **`internal/types`**: 定义核心数据类型和枚举 | Defines core data types and enums +- **`internal/tetromino`**: 处理俄罗斯方块逻辑 | Handles tetromino piece logic +- **`internal/game`**: 核心游戏机制 | Core game mechanics (board state, input handling, rendering) +- **`internal/font`**: 字体渲染系统 | Font rendering system for multi-language support +- **`internal/i18n`**: 国际化和本地化支持 | Internationalization and localization support + +## 🚀 快速开始 | Quick Start + +### 开发环境运行 | Development +```bash +# 克隆项目 | Clone the repository +git clone +cd tetris + +# 下载依赖 | Download dependencies +go mod download + +# 运行游戏 | Run the game +go run . + +# 测试字体渲染 | Test font rendering +go run . --test-font +``` + +### 构建分发版本 | Build Distribution + +```bash +# 构建所有平台版本 | Build for all platforms +make all + +# 构建特定平台 | Build for specific platform +make windows # Windows 版本 +make macos # macOS 版本 +make linux # Linux 版本 -## Controls +# 查看构建帮助 | View build help +make help -- **Left/Right Arrow**: Move piece horizontally -- **Up Arrow**: Rotate piece clockwise -- **Down Arrow**: Soft drop (faster falling) -- **Space**: Hard drop (instant drop) -- **L**: Switch language (English ⇄ 中文) -- **R** (when game over): Restart game +# 清理构建文件 | Clean build files +make clean +``` + +构建完成后,分发文件将保存在 `dist/` 目录中。 + +After building, distribution files will be saved in the `dist/` directory. -## 中文支持 / Chinese Support +## 📦 系统要求 | System Requirements -游戏支持中文界面!启动游戏后按 **L 键** 切换到中文模式。 +### 开发环境 | Development Environment +- **Go**: 1.19 或更高版本 | 1.19 or higher +- **操作系统**: Windows 10+, macOS 10.15+, Linux (64-bit) -The game supports Chinese interface! Press **L key** after starting the game to switch to Chinese mode. +### 运行环境 | Runtime Environment +- **Windows**: Windows 10/11 (64-bit) +- **macOS**: macOS 10.15 Catalina 或更高版本 | or higher +- **Linux**: 64-bit Linux 发行版,支持 X11 或 Wayland | distributions with X11/Wayland support + +## 🛠️ 主要依赖 | Dependencies + +```go +require ( + github.com/hajimehoshi/ebiten/v2 v2.8.8 // 2D 游戏引擎 | 2D game engine + golang.org/x/image v0.20.0 // 图像处理库 | Image processing +) +``` -参见 [中文使用指南](HOW_TO_USE_CHINESE.md) 了解详细说明。 +- **[Ebitengine](https://ebitengine.org/)**: 现代 Go 语言 2D 游戏引擎 | Modern 2D game engine for Go +- **golang.org/x/image**: Go 官方图像处理扩展库 | Official Go image processing extensions -See [Chinese Usage Guide](HOW_TO_USE_CHINESE.md) for detailed instructions. +## 🎨 特色功能 | Special Features -## Building and Running +### 🌟 视觉效果 | Visual Effects +- **幽灵方块**: 半透明预览方块将要落下的位置 | Transparent preview of where piece will land +- **硬降落特效**: 硬降落时的闪烁动画效果 | Flashing animation during hard drop +- **网格线**: 清晰的游戏区域网格显示 | Clear game area grid display +- **渐变背景**: 美观的背景色彩搭配 | Beautiful background color scheme +### 💯 计分系统 | Scoring System +- **基础分数**: 根据消除行数计算 | Based on lines cleared +- **等级系统**: 随着分数增加难度递增 | Progressive difficulty with score +- **实时显示**: 分数和等级实时更新 | Real-time score and level updates + +### 🎯 游戏机制 | Game Mechanics +- **7种标准方块**: I、O、T、S、Z、J、L 形方块 | Standard 7 tetromino pieces +- **踢墙算法**: 智能旋转碰撞检测 | Smart rotation collision detection +- **行消除**: 满行自动消除和分数计算 | Automatic line clearing and scoring +- **渐进速度**: 等级越高下降速度越快 | Progressive drop speed increase + +## 🎮 游戏截图 | Screenshots + +*(游戏支持实时中英文切换,界面简洁美观)* + +*(The game supports real-time Chinese/English switching with a clean and beautiful interface)* + +## 🔧 故障排除 | Troubleshooting + +### 常见问题 | Common Issues + +**中文字体显示异常 | Chinese Font Display Issues** ```bash -# Run the game -go run . +# 检查字体文件是否存在 | Check if font file exists +ls -la assets/fonts/HYSongYunLangHeiW-1.ttf -# Build executable -go build -o tetris -./tetris +# 重新运行字体测试 | Re-run font test +go run . --test-font ``` -## Dependencies +**构建失败 | Build Failures** +```bash +# 检查 Go 环境 | Check Go environment +go version + +# 清理并重新构建 | Clean and rebuild +make clean && make all + +# 检查依赖 | Check dependencies +go mod verify +``` + +**运行时错误 | Runtime Errors** +- 确保在支持的操作系统上运行 | Ensure running on supported OS +- 检查显卡驱动是否支持 OpenGL | Check if graphics drivers support OpenGL +- 确保有足够的系统资源 | Ensure sufficient system resources + +## 🤝 贡献指南 | Contributing + +欢迎提交 Issue 和 Pull Request! + +Welcome to submit Issues and Pull Requests! + +1. Fork 本项目 | Fork the project +2. 创建特性分支 | Create a feature branch +3. 提交更改 | Commit your changes +4. 推送到分支 | Push to the branch +5. 创建 Pull Request | Create a Pull Request + +## 📄 许可证 | License + +本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。 + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## 📞 联系方式 | Contact + +如有问题或建议,请通过以下方式联系: + +For questions or suggestions, please contact via: -- [Ebitengine](https://ebitengine.org/) v2.8.8 - 2D game engine for Go +- 📧 提交 Issue | Submit an Issue +- 🐙 GitHub Discussions +- 📝 Pull Request -## License +--- -This project is open source and available under the MIT License. \ No newline at end of file +**享受游戏!| Enjoy the game!** 🎮✨ \ No newline at end of file