# 🎨 字体系统说明 / Font System Guide

## ✅ 优化完成 / Optimization Complete

**游戏现在只使用 `assets/fonts` 目录中的字体！**  
不再依赖系统字体，确保跨平台一致性。

### 当前状态 / Current Status

- **使用中的字体**: `HYSongYunLangHeiW-1.ttf` (3.6MB)
- **字体系统**: 已优化为仅使用项目本地字体
- **状态**: ✅ 正常运行，无错误

---

## 🔧 字体管理 / Font Management

### 快速设置 / Quick Setup

运行字体设置脚本：
```bash
./scripts/setup_fonts.sh
```

提供以下功能：
- 🏆 从 Windows 系统复制微软雅黑
- 📥 下载开源中文字体
- 📖 字体放置说明
- 🧪 测试字体配置
- 🧹 清理字体目录

### 手动添加字体 / Manual Font Addition

1. **将字体文件放入此目录**
   ```bash
   cp your_font.ttf assets/fonts/
   ```

2. **重新编译游戏**
   ```bash
   make build
   ```

3. **运行游戏**
   ```bash
   ./tetris
   ```

---

## 📊 字体优先级 / Font Priority

游戏按以下优先级选择字体：

```
🥇 微软雅黑系列
   ├── msyh.ttf, yahei.ttf
   └── microsoft*.ttf

🥈 思源/Noto 系列  
   ├── noto*.ttf, source*.ttf
   └── 思源*.ttf

🥉 苹果字体系列
   ├── pingfang*.ttf
   └── hiragino*.ttf

🏅 其他中文字体
   ├── simhei*.ttf, 宋*.ttf
   └── 任意可用字体

🆘 最终回退
   └── Go 默认字体
```

---

## 📋 支持的格式 / Supported Formats

| 格式 | 支持状态 | 说明 |
|------|----------|------|
| `.ttf` | ✅ 完全支持 | **推荐使用** |
| `.otf` | ✅ 完全支持 | OpenType 字体 |
| `.ttc` | ⚠️ 部分支持 | 可能不兼容，建议转换为 TTF |

---

## 🚀 推荐字体 / Recommended Fonts

### 微软雅黑 / Microsoft YaHei (推荐)
```bash
# 从 Windows 系统复制
cp /mnt/c/Windows/Fonts/msyh.ttc assets/fonts/
# 或 TTF 格式
cp /path/to/msyh.ttf assets/fonts/
```

### 开源替代 / Open Source Alternatives
- **Noto Sans CJK** - Google 开源中文字体
- **思源黑体** - Adobe/Google 联合开发
- **文泉驿微米黑** - 经典开源中文字体

---

## 🛠️ 故障排除 / Troubleshooting

### 常见问题 / Common Issues

**❌ "collections not allowed" 错误**
- 解决方案: 使用 TTF 格式而不是 TTC
- 或者使用脚本下载开源字体

**❌ 中文显示为方块**
- 检查字体是否支持中文字符集
- 确认字体文件完整

**❌ 字体未加载**
- 检查文件权限: `chmod 644 assets/fonts/*.ttf`
- 查看启动日志: `./tetris 2>&1 | grep 字体`

### 调试信息 / Debug Info

查看字体加载详情：
```bash
./tetris 2>&1 | grep -E "(字体|🎨|✅|❌)"
```

正常输出示例：
```
🔍 在 assets/fonts 目录找到 1 个字体文件
✅ 使用项目字体: assets/fonts/your_font.ttf
🎨 字体系统初始化完成，使用: assets/fonts/your_font.ttf
```

---

## 💡 优化特点 / Optimization Features

- **🎯 专用目录**: 只使用 `assets/fonts` 目录
- **🚀 智能选择**: 自动选择最适合的字体
- **🔍 详细日志**: 完整的字体加载信息
- **⚡ 快速回退**: 无字体时使用默认字体
- **🌐 跨平台**: 不依赖系统字体路径

---

## ⚠️ 版权声明 / Copyright Notice

**微软雅黑字体受版权保护**，请确保您有合法使用权限。

推荐使用开源字体：
- Noto Sans CJK (Apache License 2.0)
- 文泉驿微米黑 (GPL)
- 阿里巴巴普惠体 (免费商用)

---

**🎉 字体系统已优化完成！享受一致的中文显示效果！**