俄罗斯方块流沙版

基于Phaser.js的创新方块游戏，具有独特的三方向下落物理系统，像素块如流沙般自然堆积。

📌 项目状态

当前版本: MVP 1.0
开发状态: 核心功能完成 ✅
最后更新: 2025年10月10日

完成度

• ✅ 核心玩法: 100% (完全可玩)
• ✅ 物理系统: 100% (三角形堆积正常)
• ✅ 消除机制: 100% (像素层BFS)
• ✅ 计分系统: 100% (含连锁)
• ⏳ 视觉特效: 0% (待实现)
• ⏳ 音效系统: 0% (待实现)
• ⏳ SDK集成: 0% (待实现)

✨ 核心特色

• 🎮 像素级物理模拟：每个小颗粒独立受重力影响
• 🏔️ 三方向下落系统：自然形成三角形堆积效果
• 🖱️ 自由拖放：无传统俄罗斯方块的下落限制
• ⛓️ 连锁反应：消除后可能触发连续的连锁消除
• 🎯 横向连接消除：同色方块横跨左右边界时触发

🛠️ 技术栈

• 游戏引擎: Phaser.js 3.90.0
• 开发语言: TypeScript 5.0
• 构建工具: Vite 5.0
• 后端SDK: sce-game-sdk（排行榜，待集成）
• 代码质量: 0 TypeScript错误，0 Linter警告

快速开始

安装依赖

npm install

开发模式

npm run dev

浏览器将自动打开 http://localhost:3000

构建生产版本

npm run build

预览生产版本

npm run preview

项目结构

project-h/
├── src/
│   ├── core/              # 核心系统
│   │   ├── Grid.ts        # 双层网格系统（逻辑12×22 + 像素120×220）
│   │   ├── PhysicsManager.ts  # 三方向下落物理引擎
│   │   ├── Tetromino.ts   # 方块定义和7-Bag系统
│   │   └── GameState.ts   # 游戏状态机
│   ├── gameplay/          # 玩法逻辑
│   │   ├── DragDrop.ts    # 拖放机制
│   │   ├── Elimination.ts # 消除系统（BFS算法）
│   │   ├── Scoring.ts     # 计分系统
│   │   └── PreviewSlots.ts # 预览槽位
│   ├── rendering/         # 渲染层
│   │   ├── PixelRenderer.ts # 像素块渲染
│   │   └── Animations.ts   # 消除动画
│   ├── scenes/            # Phaser场景
│   │   ├── GameScene.ts   # 主游戏场景
│   │   └── UIScene.ts     # UI场景
│   ├── types/             # TypeScript类型定义
│   ├── config/            # 配置常量
│   └── main.ts            # 入口文件
├── docs/                  # 设计文档
└── assets/                # 资源文件

核心概念

双层网格系统

• 逻辑层 (12×22)：用于方块形状定义、消除判定、计分计算
• 物理层 (120×220)：用于渲染、动画、物理模拟（重力、碰撞）
• 比例：1个逻辑格子 = 10×10个像素块

三方向下落物理

每个像素块独立下落，优先正下方，如果被占用则尝试斜向（左下/右下）滑落，形成自然的三角形堆积。

// 核心算法伪代码
if (正下方为空) {
  移动到正下方;
} else if (左下方为空 || 右下方为空) {
  随机选择一个空的斜下方移动;
} else {
  标记为稳定;
}

开发进度

Week 1: 项目基础架构与网格系统 ✅

• 项目初始化（Vite + TypeScript + Phaser.js）
• 双层网格系统实现（逻辑12×22 + 像素120×220）
• 基础渲染系统（像素块渲染、网格线显示）

Week 2-3: 核心玩法系统 ✅

• 三方向下落物理引擎（完整实现）
• 方块生成系统（7种形状 + 7-Bag随机）
• 预览槽位系统（3个槽位 + 立即补充）
• 拖放交互系统（拖动、碰撞检测、视觉反馈）

Week 4: 消除机制与计分系统 ✅

• 消除判定算法（BFS连通搜索）
• 边界触及判定（横向连接）
• 计分系统（基础公式 + 连锁加成）
• 消除动画（粒子效果）

Week 5: 游戏流程与状态机 ✅

• 游戏状态机（8种状态完整实现）
• 完整游戏循环（物理→消除→重力）
• 游戏结束判定
• 连锁反应系统

Week 6: UI优化与SDK集成 🚧

• 基础UI（分数、状态、槽位预览）
• 拖放视觉反馈
• 游戏结束界面
• 消除动画特效
• sce-game-sdk集成
• 性能优化（对象池、分层渲染）
• 音效系统

📖 重要文档（AI必读）

🤖 给下一个AI会话的指引

如果你是新的AI会话，强烈建议先读这个 → AI_HANDOFF.md ⭐⭐⭐⭐⭐

5分钟了解项目全貌，包含：

• 项目概览
• 4个关键警告（避免踩坑）
• 已解决的5个bug清单
• 快速上手步骤

📚 完整文档体系

按重要性排序：

优先级	文档	用途	阅读时间
⭐⭐⭐⭐⭐	AI_HANDOFF.md	AI会话交接	5分钟
⭐⭐⭐⭐⭐	PROJECT_CONTEXT.md	项目完整上下文	15分钟
⭐⭐⭐⭐⭐	docs/GameDesignDocument.md	游戏设计规范	60分钟
⭐⭐⭐⭐	docs/ARCHITECTURE.md	技术架构说明	20分钟
⭐⭐⭐⭐	docs/DEVELOPMENT_LOG.md	开发历程记录	10分钟
⭐⭐⭐	QUICK_START.md	快速启动指南	3分钟
⭐⭐⭐	IMPLEMENTATION_SUMMARY.md	实施总结报告	15分钟

📁 分类文档

• 功能文档 - docs/features/

  • 每日挑战系统实现
  • 功能开发指南

• 工程文档 - docs/engineering/

  • 性能优化追踪 - 性能问题分析与优化进度

📝 推荐阅读顺序

如果你想快速上手 (15分钟)

1. AI_HANDOFF.md (5分钟) ⭐⭐⭐⭐⭐
2. PROJECT_CONTEXT.md (10分钟) ⭐⭐⭐⭐⭐
3. 运行游戏测试

如果你想完全理解 (2小时)

1. AI_HANDOFF.md
2. PROJECT_CONTEXT.md
3. docs/GameDesignDocument.md (重点：开头+第5章+第8章)
4. ARCHITECTURE.md
5. DEVELOPMENT_LOG.md
6. 阅读源码

🎮 测试说明

基础操作

1. 启动游戏：npm run dev → 浏览器自动打开 http://localhost:3001
2. 选择方块：点击底部3个预览槽位
3. 拖动放置：
   • 🟢 绿色边框 = 可以放置
   • 🔴 红色边框 = 无法放置
4. 观察效果：
   • 像素块独立下落，形成三角形堆积
   • 同色方块横跨左右边界时触发消除
   • 消除后自动检查悬空像素块
   • 连锁反应获得额外分数倍数

调试快捷键

• G键: 显示网格调试信息（总像素块、稳定/不稳定数量）
• R键: 手动触发重力重新检查
• ESC键: 取消拖动

核心功能验证

• ✅ 三方向下落物理系统（方块形成三角形）
• ✅ 拖放操作（完整交互、视觉反馈）
• ✅ 横向连接消除（像素层BFS算法）
• ✅ 自动稳定性检查（无悬空残留）
• ✅ 连锁反应系统（多层消除）
• ✅ 计分系统（含连锁加成）
• ✅ 游戏结束判定（3个槽位都无法放置）

📚 参考文档清单

文档	用途	优先级
PROJECT_CONTEXT.md	AI会话上下文	⭐⭐⭐⭐⭐
docs/GameDesignDocument.md	完整设计规范	⭐⭐⭐⭐⭐
DEVELOPMENT_LOG.md	开发历程	⭐⭐⭐⭐
IMPLEMENTATION_SUMMARY.md	实施总结	⭐⭐⭐
QUICK_START.md	快速上手	⭐⭐⭐
ARCHITECTURE.md	技术架构	⭐⭐⭐

许可证

MIT License