Block Fall PC — Retro Tetris Game Source (Desktop Edition)

A retro-style Tetris-like game built on Godot 4.7+, designed for PC desktop in landscape (1280×720). Golden console aesthetic, pixel-art dino idle animation, DAS (Delayed Auto Shift) controls, scoring, level progression, and game state persistence — a complete project you can run, build, and study as an architecture template.

🎯 Core Highlights

Designed for AI-Assisted Development

The entire project is built purely in code: main.tscn is only 3 lines of substance. The node tree, UI, styles, and arrow icons are all constructed by GDScript at runtime. view_config.gd manages layout via named constants with absolute pixel coordinates, and the console shell pattern is drawn with draw_rect calls. Reading the .gd files tells you everything.

No .tscn black boxes — Scene tree built in code by view_builder.gd, read .gd files to understand the full picture
No external resources — styles code-drawn, arrow icons pixel-drawn, audio code-loaded
Constant-driven layout — dimensions and coordinates centralized in view_config.gd, avoiding verbose Container/anchors
Four universal principles — Everything is text, single-responsibility files, constant-driven layout, unidirectional dependencies (acyclic)

LV (Logic-View) Layered Architecture

Following the same Logic-View separation as Block Blast and Godot 2048 — replacing the common MVC pattern:

Layer	Responsibility	Key Files
logic/	Pure game logic. `Game` extends `RefCounted`, no scene-tree dependency, unit-testable. `Block` / `Matrix` are pure data classes. `SaveData` handles persistence.	`game.gd` `block.gd` `matrix.gd` `input_handler.gd` `save_data.gd`
view/	Pure rendering. All views read state via the `game` reference and auto-refresh through the `state_changed` signal. `ViewConfig.draw_shell()` code-draws the golden console shell.	`matrix_view.gd` `next_view.gd` `idle_hint.gd` `reset_dialog.gd`
main.gd	Thin coordinator. Builds UI → creates Game → drives the state machine each frame with `tick(delta)` → wires Logic ↔ View signals.	—

Key insight: Game extends RefCounted instead of Node, so the logic layer can be unit-tested without a scene tree — no Timer or SceneTree dependencies; all state transitions are driven by a pure tick(delta) function.

Complete Test Coverage

The project ships with a lightweight test framework (no plugin dependencies), two tiers:

Unit tests (tests/test_*.gd) — covers gravity, line clearing, Game Over, save data, and all other core rules for Block / Matrix / Game
Smoke test (tests/smoke_test.gd) — instantiates the real main scene and verifies startup and tick-driven operation

Run them with:

godot --headless --path . --script res://tests/test_runner.gd   # Unit tests
godot --headless --path . --script res://tests/smoke_test.gd    # Smoke test

PC Landscape Adaptation

Landscape 1280×720 resolution, golden retro console aesthetic
Console shell on the left (left area: board + panel; right area: control panel + virtual D-pad)
ViewConfig.draw_shell() draws the golden shell + screen border + panel background using draw_rect
Full keyboard support (A/D/W/S, arrow keys, Space, P, R, M) — convenient for desktop debugging
Auto-pause on window focus loss via NOTIFICATION_APPLICATION_FOCUS_OUT
Web export friendly: saves go to user://save.json, isolated per origin

🎮 Game Features

7 block types — I, L, J, Z, S, O, T, each with unique shapes and rotation origins
DAS input system — Delayed Auto Shift for smooth, responsive horizontal movement
Scoring system — Points for clearing 1–4 lines (100 / 300 / 700 / 1500) + block lock-in bonus
Level progression — Speed increases every 10 lines cleared, up to level 10, with a fixed horizontal movement speed for consistent controls
Next block preview — See the upcoming piece before it spawns
Idle animation — Pixel-art dino with blink/run cycle while waiting for input
Game Over animation — Flash-fill effect from bottom to top
Reset confirmation dialog — retro-styled, prevents accidental progress loss mid-game
Settings persistence — best score and music toggle saved to user://save.json
Audio feedback — sound effects for start, move, rotate, clear, fall, and Game Over
Virtual controls — on-screen D-pad and action buttons, mouse-clickable

Scoring

Lines Cleared	Score
1	100
2	300
3	700
4	1500

Base settlement bonus: 10 + (speed_level - 1) × 2 per block locked
Speed increases every 10 lines cleared (max level 10)

Controls

Action	Key	Virtual Button
Move Left	`A` / `←`	D-Pad Left
Move Right	`D` / `→`	D-Pad Right
Soft Drop	`S` / `↓`	D-Pad Down
Rotate	`W` / `↑`	D-Pad Up
Hard Drop	`Space`	N/A
Pause / Start	`P`	Pause
Reset	`R`	Reset
Mute / Unmute	`M`	Sound

📂 Project Structure

block-fall-pc/
├── audio/                          # Sound effects (.ogg)
│   ├── start.ogg                   #   Game start
│   ├── move.ogg                    #   Block move
│   ├── rotate.ogg                  #   Block rotate
│   ├── clear.ogg                   #   Line clear
│   ├── fall.ogg                    #   Lock-in fall
│   └── gameover.ogg                #   Game Over
├── logic/                          # Game logic layer (Logic)
│   ├── block.gd                    #   Block data (shapes, rotation, movement)
│   ├── game.gd                     #   Game logic + tick state machine (RefCounted pure logic)
│   ├── input_handler.gd            #   Keyboard/button input + DAS repeat logic
│   ├── matrix.gd                   #   Grid logic (collision, merge, clear lines)
│   └── save_data.gd                #   Save/load (user://save.json)
├── view/                           # Rendering layer (View)
│   ├── idle_hint.gd                #   Dino idle animation
│   ├── matrix_view.gd              #   Matrix rendering
│   ├── next_view.gd                #   Next block preview rendering
│   ├── reset_dialog.gd             #   Reset confirmation dialog (retro style)
│   ├── view_config.gd              #   Layout constants + draw_shell() shell drawing
│   └── view_builder.gd             #   Scene tree construction + view factories
├── tools/                          # Asset generation tools
│   └── gen_block_fall_assets.py    #   Logo + splash screen generator
├── tests/                          # Tests (no plugin dependencies)
│   ├── test_runner.gd              #   Unit test runner
│   ├── smoke_test.gd               #   Smoke test
│   ├── test_base.gd                #   Test base class
│   ├── test_block.gd               #   Block unit tests
│   ├── test_game.gd                #   Game unit tests
│   └── test_matrix.gd              #   Matrix unit tests
├── docs/                           # Project documentation
│   ├── intro.md                    #   This document (Chinese)
│   └── intro_en.md                 #   English introduction
├── main.gd                         # Main coordinator (LV thin layer: wiring + tick + shell drawing)
├── main.tscn                       # Main scene (root node + script reference only)
├── project.godot                   # Engine configuration
├── export_presets.cfg              # Export preset configuration
└── LICENSE.md                      # Paid license (see LICENSE_en.md for English version)

🚀 Quick Start

Requirements

Godot 4.7+

Run

Open the project directory with Godot
Press F5 to run (or godot --path .)
Use A/D/W/S + arrow keys, Space, P, R, M — or the virtual buttons

Build

Adjust target platform presets in export_presets.cfg
Use Godot’s export dialog to build for Web (HTML5) / Windows / macOS / Linux

Generate Assets

python3 tools/gen_block_fall_assets.py

👤 Who Is This For

Godot beginners — a complete, runnable 2D project with thorough Chinese comments, learn as you read
Architecture learners — LV separation + RefCounted pure logic + tick-driven state machine — a fresh take on making logic layers testable
AI-assisted developers — pure code architecture aligns perfectly with AI tooling; changing features is find-and-replace friendly
Indie game developers — classic Tetris gameplay, ready to ship or use as a starting point for derivatives
Compare with mobile Block Fall / Block Blast / Godot 2048 — same architecture across three targets (mobile portrait + PC landscape) and four game types, compare at rest and in motion

📄 License

This project uses a paid custom license. After purchase you may modify the code and ship derivative games, but you may not redistribute the source code or sell it commercially. See LICENSE_en.md (or LICENSE.md for Chinese) for the full terms.

Description