Block Blast PC — Drag-and-Drop Puzzle Game Source (Desktop Edition)

A Block Blast clone built on Godot 4.7+, designed for PC desktop in landscape (1280×720). 8×8 grid + 37 block shapes + combo system + clear animations — intuitive drag-and-drop gameplay, strategic depth, easy to pick up but hard to master.

🎯 Core Highlights

Designed for AI-Assisted Development

The entire project is built purely in code: main.tscn only holds the root node + script reference. The board, slots, score, buttons, and dialogs are all constructed in code by main.gd; block groups (cells + drag Button) are code-generated and triggered by the slot_filled signal. Read the .gd files and you understand everything.

No scene black boxes — Scene tree built in code, no .tscn / .tres resource dependencies
Path-based resource loading — textures and sounds are load() / preload() via res:// paths, no export variable injection
Constant-driven layout — color/texture mappings centralized in view_config.gd, ready to converge into constant tables
Four universal principles — Everything is text, single-responsibility files, constant-driven layout, unidirectional dependencies (Logic ← View ← main.gd)

LV (Logic-View) Layered Architecture

Following the same Logic-View separation as Block Fall 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. `Grid` / `Piece` / `Shapes` are pure data classes. `SaveData` handles leaderboard persistence.	`game.gd` `grid.gd` `piece.gd` `shapes.gd` `save_data.gd`
view/	Pure rendering + drag interaction. Read-only access to Logic state; intents call `Game` methods one-way, never write logic state directly.	`board_view.gd` `block_group.gd` `scores_view.gd` `clear_animation.gd` `retry_confirm_view.gd`
main.gd	Thin coordinator. Builds UI → creates Game → injects into Views → wires Logic ↔ View signals → plays sound effects.	—

Key insight: Game extends RefCounted instead of Node, so the logic layer can be unit-tested without a scene tree — Game.new() is all you need, no Godot runtime required.

Complete Test Coverage

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

Unit tests (tests/test_*.gd) — covers piece placement, line clearing, scoring, combos, Game Over, and all other core rules
Smoke test (tests/smoke_test.gd) — instantiates the real main scene and verifies the full flow (init, replenish, clear, combo, preview highlight, Retry, Scores, Game Over)

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

Tests automatically isolate the leaderboard save to user://test_scores.json, so they never pollute the player’s real save data.

PC Landscape Adaptation

Landscape 1280×720 resolution, optimized for mouse drag interaction
8×8 board on the left, three upcoming slots stacked vertically on the right (PC-exclusive layout)
7 vivid colored block textures + clear break animation (8 colors × 15 frames)
Dynamic combo sounds (Good → Nice → Great → Amazing → Excellent → Incredible)
Mute button + leaderboard dialog + restart confirmation dialog (retry_confirm_view.gd)
tools/generate_block_blast_assets.py — one-click logo + splash screen generator

🎮 Game Features

Drag-and-drop gameplay — intuitive mouse controls for placing blocks onto the 8×8 grid
37 unique block shapes — from single cells to complex multi-piece formations, three random pieces per round
7 vivid colors — red, orange, yellow, green, cyan, blue, and purple blocks
Combo system — clearing multiple lines in one move builds combos and multiplies your score
Animated clear effects — satisfying break animations when lines are cleared
Dynamic sound effects — progressive audio feedback for each combo level (Good → Incredible)
Local save — Top 5 high scores persisted locally
Progressive difficulty — smart piece generation adapts to your score

Scoring

Action	Points
Place a block	+10
Clear a line/column	+100 × Combo
Combo multiplier	Increases with consecutive clears

Combo sound tiers: Good → Nice → Great → Amazing → Excellent → Incredible

How to Play

Drag one of the three upcoming pieces from the right side onto the 8×8 grid
Fill complete rows or columns to clear them and earn points
Chain multiple line clears in a single move to trigger a combo multiplier
Strategize — you can only place each piece once, so plan your moves carefully
The game ends when all three upcoming pieces cannot fit anywhere on the grid

📂 Project Structure

block-blast-pc/
├── audio/                     # Sound effects (.ogg)
│   ├── good.ogg               #   Combo sounds (6 tiers: Good → Incredible)
│   ├── nice.ogg / great.ogg / amazing.ogg
│   ├── excellent.ogg / incredible.ogg
│   ├── snap.ogg               #   Piece placement sound
│   └── fail.ogg               #   Game Over sound
├── logic/                     # Game logic layer (Logic)
│   ├── game.gd                #   Game: per-run state + all rules (RefCounted pure logic)
│   ├── grid.gd                #   8×8 board data + line clear detection
│   ├── piece.gd               #   Block shape data + placement validation
│   ├── shapes.gd              #   37 block shape constants
│   └── save_data.gd           #   Leaderboard persistence (injectable path, test isolation)
├── view/                      # Rendering layer (View)
│   ├── board_view.gd          #   Board rendering + drag state machine + clear animations
│   ├── block_group.gd         #   Input proxy for draggable block groups
│   ├── scores_view.gd         #   High score leaderboard UI
│   ├── clear_animation.gd     #   Line clear animation (8 colors × 15 frames)
│   ├── retry_confirm_view.gd  #   Restart confirmation dialog (PC-exclusive)
│   └── view_config.gd         #   Shared view config (cell size, color/texture mapping)
├── textures/                  # Sprites and visual assets
│   ├── blocks1.png ~ blocks7.png  # 7 colored block textures
│   ├── board.png              #   Board background
│   ├── sound_on.png / sound_off.png  # Mute button icons
│   ├── clear_anim/            #   Line clear animation frames (8 colors × 15 frames)
│   └── logo/                  #   Game logo assets
├── tools/                     # Asset generation tools
│   └── generate_block_blast_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_game.gd           #   Game unit tests
├── docs/                      # Project documentation
│   ├── intro.md               #   This document (Chinese)
│   └── intro_en.md            #   English introduction
├── main.gd                    # Main coordinator (LV thin layer: UI build + wiring + audio routing)
├── main.tscn                  # Main scene (root node + script reference only)
├── project.godot              # Engine configuration
└── export_presets.cfg         # Export preset configuration

🚀 Quick Start

Requirements

Godot 4.7+

Run

Open the project directory with Godot
Press F5 to run (or godot --path .)
Drag pieces with your mouse to play

Build

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

Generate Assets

python3 tools/generate_block_blast_assets.py

👤 Who Is This For

Godot beginners — a complete, runnable puzzle game project with thorough Chinese comments, learn as you read
Architecture learners — LV separation + RefCounted pure logic + intent-driven View — 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 Block Blast gameplay, ready to ship or use as a starting point for derivatives
Compare with mobile Block Blast / Block Fall / 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