GodotStudy

资源介绍

Block Fall PC — 复古俄罗斯方块源码（桌面版）

一款采用 Godot 4.7+ 开发的复古风格俄罗斯方块游戏，专为 PC 桌面端横屏（1280×720）设计。金色游戏机外壳造型、像素风闲置恐龙、DAS 流畅操控、计分等级系统、游戏状态持久化——一款可直接运行、可构建发布、可作为架构学习模板的完整项目。

🎯 核心亮点

专为 AI 辅助开发设计

整个项目纯代码构建：唯一的 main.tscn 仅 3 行实质内容。节点树、UI、样式、箭头图标全部由 GDScript 在运行时构建，view_config.gd 常量驱动绝对像素布局，外壳图案由 draw_rect 代码绘制。读 .gd 即可理解全貌。

  • 无 .tscn 黑盒 — 场景树由 view_builder.gd 代码构建，读 .gd 文件即可理解项目全貌
  • 无外部资源依赖 — 样式代码绘制、箭头图标像素级绘制、音频代码加载
  • 常量驱动布局 — 尺寸与坐标集中在 view_config.gd，避开冗长的 Container/anchors
  • 四条通用原则 — 一切皆文本、单一职责文件、常量驱动布局、单向依赖（无环）

LV（Logic-View）分层架构

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

层 职责 关键文件
logic/ 纯游戏逻辑。Game 继承 RefCounted，无场景树依赖、可单元测试；Block / Matrix 纯数据类；SaveData 负责存档 game.gd block.gd matrix.gd input_handler.gd save_data.gd
view/ 纯渲染。所有视图经 game 引用读取状态，通过 state_changed 信号自动刷新；ViewConfig.draw_shell() 代码绘制金色游戏机外壳 matrix_view.gd next_view.gd idle_hint.gd reset_dialog.gd
main.gd 薄协调者。构建 UI → 创建 Game → 每帧 tick(delta) 驱动状态机 → 连接 Logic ↔ View 信号 —

关键：Game 继承 RefCounted 而非 Node，逻辑层可脱离场景树直接单元测试，不依赖 Timer/Signal 等场景树组件，改用 tick(delta) 纯驱动。

完整测试覆盖

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

  • 单元测试（tests/test_*.gd）— 覆盖 Block / Matrix / Game 的重力、消行、game over、存档等核心逻辑
  • 冒烟测试（tests/smoke_test.gd）— 实例化真实主场景，验证启动与 tick 驱动

运行方式：

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

PC 端横屏适配

  • 横屏 1280×720 分辨率，金色复古游戏机外壳造型
  • 外壳居左（左：棋盘 + 面板；右：控制面板 + 虚拟方向键）
  • ViewConfig.draw_shell() 用 draw_rect 代码绘制金色外壳 + 屏幕边框 + 面板背景
  • 完整键盘支持（A/D/W/S、方向键、Space、P、R、M），便于桌面端调试
  • 窗口失焦自动暂停，NOTIFICATION_APPLICATION_FOCUS_OUT 事件处理
  • Web 导出友好：存档走 user://save.json，按域名隔离

🎮 游戏特性

  • 7 种方块类型 — I、L、J、Z、S、O、T，各有独特形状和旋转原点
  • DAS 输入系统 — 延迟自动连发，实现流畅的水平移动控制
  • 计分系统 — 消除 1–4 行得分（100 / 300 / 700 / 1500）+ 方块固化奖励
  • 等级进度 — 每消除 10 行速度提升，最高 10 级；水平移动速度固定不变，操控始终如一
  • 下一个方块预览 — 方块出现前即可看到
  • 闲置动画 — 像素风恐龙，带眨眼/跑动循环
  • 游戏结束动画 — 自下而上的闪烁填充效果
  • 重置确认弹窗 — 复古风格，避免局中误触丢失进度
  • 设置持久化 — 最高分与声音设置保存到 user://save.json
  • 音效反馈 — 开始、移动、旋转、消除、下落、结束均有音效
  • 虚拟按键 — 屏幕方向键 + 功能按钮，支持鼠标点击

计分规则

消除行数 分数
1 100
2 300
3 700
4 1500
  • 方块固化奖励：10 + (speed_level - 1) × 2
  • 每消除 10 行提升速度（最高 10 级）

操作说明

动作 键盘 虚拟按钮
左移 A / ← 方向键左
右移 D / → 方向键右
软降 S / ↓ 方向键下
旋转 W / ↑ 方向键上
硬降 Space 无
暂停 / 开始 P 暂停
重置 R 重置
静音 / 取消静音 M 音效

📂 项目结构

block-fall-pc/
├── audio/                          # 音效文件 (.ogg)
│   ├── start.ogg                   #   游戏开始
│   ├── move.ogg                    #   方块移动
│   ├── rotate.ogg                  #   方块旋转
│   ├── clear.ogg                   #   消除
│   ├── fall.ogg                    #   下落
│   └── gameover.ogg                #   Game Over
├── logic/                          # 游戏逻辑层 (Logic)
│   ├── block.gd                    #   方块数据（形状、旋转、移动）
│   ├── game.gd                     #   游戏逻辑 + tick 状态机（RefCounted 纯逻辑）
│   ├── input_handler.gd            #   键盘/按钮输入 + DAS 重复逻辑
│   ├── matrix.gd                   #   网格逻辑（碰撞检测、固化、消行）
│   └── save_data.gd                #   存档读写（user://save.json）
├── view/                           # 渲染层 (View)
│   ├── idle_hint.gd                #   恐龙闲置动画
│   ├── matrix_view.gd              #   矩阵渲染
│   ├── next_view.gd                #   下一个方块预览渲染
│   ├── reset_dialog.gd             #   重置确认弹窗（复古风格）
│   ├── view_config.gd              #   布局常量 + draw_shell() 外壳绘制
│   └── view_builder.gd             #   场景树构建 + 视图工厂方法
├── tools/                          # 资源生成工具
│   └── gen_block_fall_assets.py    #   Logo + 启动图生成脚本
├── tests/                          # 测试（无插件依赖）
│   ├── test_runner.gd              #   单元测试运行器
│   ├── smoke_test.gd               #   冒烟测试
│   ├── test_base.gd                #   测试基类
│   ├── test_block.gd               #   Block 单元测试
│   ├── test_game.gd                #   Game 单元测试
│   └── test_matrix.gd              #   Matrix 单元测试
├── docs/                           # 项目文档
│   ├── intro.md                    #   本文档（godotstudy.cn 介绍文案）
│   └── intro_en.md                 #   英文版介绍
├── main.gd                         # 主协调者（LV 薄层：接线 + tick 驱动 + 外壳绘制）
├── main.tscn                       # 主场景（仅根节点 + 脚本引用）
├── project.godot                   # 引擎配置
├── export_presets.cfg              # 导出预设配置
└── LICENSE.md                      # 付费许可证（含 LICENSE_en.md 英文版）

🚀 快速上手

环境要求

  • Godot 4.7+

运行

  1. 使用 Godot 打开项目目录
  2. 按 F5 运行（或 godot --path .）
  3. 键盘 A/D/W/S + 方向键 / Space / P / R / M，或虚拟按钮

构建

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

生成资源

python3 tools/gen_block_fall_assets.py

👤 适合谁

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

📄 许可证

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

俄罗斯方块电脑版源代码

¥49