Block Blast PC — 拖放益智游戏源码（桌面版）

一款基于 Godot 4.7+ 开发的 Block Blast 复刻版益智游戏，专为 PC 桌面端横屏（1280×720）设计。8×8 网格 + 37 种方块形状 + 连击系统 + 消除动画——直观的拖放玩法、策略性十足、容易上手但难以精通。

🎯 核心亮点

专为 AI 辅助开发设计

整个项目纯代码构建：唯一的 main.tscn 只有根节点 + 脚本引用。棋盘、槽位、分数、按钮、弹窗全部由 main.gd 在代码中构建；方块组（格子 + 拖拽 Button）由 slot_filled 信号触发、代码生成。读 .gd 即可理解全貌。

无场景黑盒 — 场景树在代码中构建，无 .tscn / .tres 资源依赖
资源按路径加载 — 贴图/音效用 res:// 路径在代码中 load() / preload()，无 export 变量注入
常量驱动布局 — 颜色/纹理映射集中在 view_config.gd，可渐进收敛到常量表
四条通用原则 — 一切皆文本、单一职责文件、常量驱动布局、单向依赖（Logic ← View ← main.gd）

LV（Logic-View）分层架构

与 Block Fall、Godot 2048 一脉相承的 Logic-View 分层，替代常见的 MVC：

层	职责	关键文件
logic/	纯游戏逻辑。`Game` 继承 `RefCounted`，无场景树依赖、可单元测试；`Grid` / `Piece` / `Shapes` 纯数据类；`SaveData` 负责排行榜持久化	`game.gd` `grid.gd` `piece.gd` `shapes.gd` `save_data.gd`
view/	纯渲染 + 拖拽交互。只读 Logic 状态，意图单向调用 `Game` 方法，不直接写逻辑状态	`board_view.gd` `block_group.gd` `scores_view.gd` `clear_animation.gd` `retry_confirm_view.gd`
main.gd	薄协调者。构建 UI → 创建 Game → 注入各 View → 连接 Logic ↔ View 信号 → 播放音效	—

关键：Game 继承 RefCounted 而非 Node，逻辑层可脱离场景树直接单元测试——Game.new() 即可构造，无需启动 Godot 运行时。

完整测试覆盖

项目自带轻量级测试框架（无插件依赖），分两层：

单元测试（tests/test_*.gd）— 覆盖落子、消行、计分、combo、GameOver 等核心规则
冒烟测试（tests/smoke_test.gd）— 实例化真实主场景，验证全流程（初始化、补货、消行、combo、预览高亮、Retry、Scores、Game Over）

运行方式：

godot --headless --path . --script res://tests/test_runner.gd   # 单元测试
godot --headless --path . --script res://tests/smoke_test.gd    # 冒烟测试

测试运行时排行榜存档会自动隔离到 user://test_scores.json，不会污染玩家真实存档。

PC 端横屏适配

横屏 1280×720 分辨率，专为鼠标拖拽操作优化
8×8 棋盘居左，三个待放置槽位在右侧纵向排列（PC 版独有布局）
7 种鲜明色彩方块 + 消除破碎动画（8 色 × 15 帧）
动态连击音效（Good → Nice → Great → Amazing → Excellent → Incredible）
静音按钮 + 排行榜弹窗 + 重开确认弹窗（retry_confirm_view.gd）
tools/generate_block_blast_assets.py 一键生成 Logo + 启动图资源

🎮 游戏特性

拖放玩法 — 直观的鼠标拖拽控制，将方块放置到 8×8 网格上
37 种方块形状 — 从单个格子到复杂的多块组合，每局随机出三个
7 种鲜明色彩 — 红、橙、黄、绿、青、蓝、紫方块
连击系统 — 一次操作清除多行可积累连击，分数成倍增加
消除动画效果 — 消除行/列时有爽快的破碎动画
动态音效 — 每个连击等级都有递进式音频反馈（Good → Incredible）
本地存档 — 本地保存 Top 5 最高分记录
渐进式难度 — 智能方块生成机制会根据分数调整难度

计分规则

操作	分数
放置方块	+10
消除一行/列	+100 × 连击数
连击倍率	连续消除时递增

连击音效等级：Good → Nice → Great → Amazing → Excellent → Incredible

游戏玩法

拖动右侧三个待放置方块之一到 8×8 网格上
填满完整的行或列即可清除并获得分数
连击 — 一次操作中清除多行可触发连击倍率
策略思考 — 每个方块只能放置一次，请谨慎规划
当所有待放置方块都无法放入网格时，游戏结束

📂 项目结构

block-blast-pc/
├── audio/                     # 音效文件 (.ogg)
│   ├── good.ogg               #   连击音效（Good → Incredible 六档）
│   ├── nice.ogg / great.ogg / amazing.ogg
│   ├── excellent.ogg / incredible.ogg
│   ├── snap.ogg               #   落子音效
│   └── fail.ogg               #   Game Over 音效
├── logic/                     # 游戏逻辑层 (Logic)
│   ├── game.gd                #   Game：单局状态 + 全部规则（RefCounted 纯逻辑）
│   ├── grid.gd                #   8×8 棋盘数据 + 消行检测
│   ├── piece.gd               #   方块形状数据 + 放置合法性校验
│   ├── shapes.gd              #   37 种方块形状常量
│   └── save_data.gd           #   排行榜持久化（路径可注入，测试隔离）
├── view/                      # 渲染层 (View)
│   ├── board_view.gd          #   棋盘渲染 + 拖拽状态机 + 消除动画
│   ├── block_group.gd         #   可拖拽方块的输入代理
│   ├── scores_view.gd         #   高分排行榜界面
│   ├── clear_animation.gd     #   消除动画（8 色 × 15 帧）
│   ├── retry_confirm_view.gd  #   重开确认弹窗（PC 版独有）
│   └── view_config.gd         #   View 层共享配置（格子大小、颜色/纹理映射）
├── textures/                  # 精灵图和视觉资源
│   ├── blocks1.png ~ blocks7.png  # 7 种颜色方块贴图
│   ├── board.png              #   棋盘背景
│   ├── sound_on.png / sound_off.png  # 静音按钮图标
│   ├── clear_anim/            #   行/列消除动画帧（8 种颜色 × 15 帧）
│   └── logo/                  #   游戏 Logo 资源
├── tools/                     # 资源生成工具
│   └── generate_block_blast_assets.py  # Logo + 启动图生成脚本
├── tests/                     # 测试（无插件依赖）
│   ├── test_runner.gd         #   单元测试运行器
│   ├── smoke_test.gd          #   冒烟测试
│   ├── test_base.gd           #   测试基类
│   └── test_game.gd           #   Game 单元测试
├── docs/                      # 项目文档
│   ├── intro.md               #   本文档（godotstudy.cn 介绍文案）
│   └── intro_en.md            #   英文版介绍
├── main.gd                    # 主协调者（LV 薄层：构建 UI + 接线 + 音效路由）
├── main.tscn                  # 主场景（仅根节点 + 脚本引用）
├── project.godot              # 引擎配置
└── export_presets.cfg         # 导出预设配置

🚀 快速上手

环境要求

Godot 4.7+

运行

使用 Godot 打开项目目录
按 F5 运行（或 godot --path .）
鼠标拖拽即可开始游戏

构建

在 export_presets.cfg 中调整目标平台预设
使用 Godot 导出对话框构建 Windows / macOS / Linux / Web（HTML5 PWA）

生成资源

python3 tools/generate_block_blast_assets.py

👤 适合谁

Godot 初学者 — 一个完整可跑的益智游戏项目，注释全部中文，边看边学
架构模式学习者 — LV 分层 + RefCounted 纯逻辑 + 意图驱动 View，一种让逻辑层可测试的新思路
AI 辅助开发者 — 纯代码构建架构与 AI 工具天然契合，改功能用查找替换即可
独立游戏开发者 — Block Blast 经典玩法，可直接发布或作为衍生项目的起点
与移动端版 Block Blast / Block Fall / Godot 2048 对比学习 — 同架构三端（移动端竖屏 + PC 横屏）四种游戏类型，一静一动对比学习

📄 许可证

本项目使用付费自定义许可证。购买后可修改代码并发布衍生游戏，但不得二次分发源代码或以商业目的销售源代码。详细条款请参阅项目内的 LICENSE.md（含 LICENSE_en.md 英文版）。

资源介绍