tetris/README.md

# Tetris Game | 俄罗斯方块

一个使用 Go 语言和 Ebitengine 游戏引擎实现的经典俄罗斯方块游戏，支持中英文双语界面。

A classic Tetris game implemented in Go using the Ebitengine game engine with bilingual support (Chinese/English).

## ✨ 特性 | Features

### 🎮 游戏特性 | 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 模块定义 | 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

项目遵循 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
- **`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 <repository-url>
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 版本

# 查看构建帮助 | View build help
make help

# 清理构建文件 | Clean build files
make clean
```

构建完成后，分发文件将保存在 `dist/` 目录中。

After building, distribution files will be saved in the `dist/` directory.

## 📦 系统要求 | System Requirements

### 开发环境 | Development Environment
- **Go**: 1.19 或更高版本 | 1.19 or higher
- **操作系统**: Windows 10+, macOS 10.15+, Linux (64-bit)

### 运行环境 | 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
)
```

- **[Ebitengine](https://ebitengine.org/)**: 现代 Go 语言 2D 游戏引擎 | Modern 2D game engine for Go
- **golang.org/x/image**: Go 官方图像处理扩展库 | Official Go image processing extensions

## 🎨 特色功能 | Special Features

### 🌟 视觉效果 | 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
# 检查字体文件是否存在 | Check if font file exists
ls -la assets/fonts/HYSongYunLangHeiW-1.ttf

# 重新运行字体测试 | Re-run font test
go run . --test-font
```

**构建失败 | 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:

- 📧 提交 Issue | Submit an Issue
- 🐙 GitHub Discussions
- 📝 Pull Request

---

**享受游戏！| Enjoy the game!** 🎮✨