Java版俄罗斯方块源码解析：从跑通到改造的完整指南-开发者社区

简介：这是一份面向Java初学者与桌面小游戏开发爱好者的俄罗斯方块完整源码，基于Java语言实现，需JRE环境运行，适合用来学习Swing界面绘制、游戏循环与状态管理。压缩包共49个文件，约224KB，以32个java源文件为核心，另含8个wav音效、3个res资源、3个xml配置及1个png图片，结构紧凑、便于阅读与二次开发。程序支持将声音、显示、关卡等配置保存到jar同级目录的cfg文件中，并提供标准、速度、复杂性三组关卡，可自定义控制键、切换单色与彩色显示、控制网格显隐，复杂性关卡还会随机生成障碍物并扩展至16种形状。源码中亦保留了形状擦除异常与蒙层覆盖等已知Bug的说明，可作为调试与排错练习的切入点。目前已有1996人学习下载，适合想通过一个完整小项目理解Java图形界面与游戏逻辑的读者参考。

1. Java版俄罗斯方块源码：从能跑到能改，中间隔着什么

很多人第一次搜「Java版俄罗斯方块小游戏源码」，心里想的其实是两件事：一是找个能直接跑起来的完整项目，二是想借着这个项目把 Java 基础、面向对象编程和 Swing 图形界面串一遍。俄罗斯方块这个题材之所以经典，是因为它足够小——小到一个人一下午能读完，又足够完整——完整到能覆盖游戏循环、碰撞检测、状态管理、键盘事件、分数系统这些真实项目里都会遇到的东西。但现实往往是：下载下来的源码能跑，可一旦想改点东西就懵了，方块下落速度写死在哪个变量里、旋转逻辑为什么偶尔会穿墙、消行之后分数怎么算的，全是一团乱麻。这篇笔记就按「先跑通、再拆解、再改造」的顺序，把一份典型的 Java 俄罗斯方块源码从黑匣子拆成你能随手改的白盒，顺带把 Java 环境配置、面向对象设计、Swing 绘图这些绕不开的点讲清楚。适合刚学完 Java 基础、想找个完整项目练手的人，也适合想拿它当课程设计案例源码的在校生。

2. 把源码跑起来：Java 环境配置与最小启动路径

2.1 先确认你的 Java 环境到底能不能用

拿到一份 Java 源码，第一件事不是急着导入 IDE，而是先把命令行环境验一遍。很多「java 启动失败怎么解决」的问题，根源都在环境变量没配对或者版本对不上。俄罗斯方块这类 Swing 项目通常用 JDK 8 到 JDK 17 都能跑，但如果你机器上装的是 JDK 21 而源码里用了某些被移除的 API，就会在编译期直接报错。

先在终端里执行下面三条命令，确认版本和路径：

java -version javac -version echo $JAVA_HOME

java -version输出的是运行时版本，javac -version输出的是编译器版本，两者最好一致。echo $JAVA_HOME在 Windows 上换成echo %JAVA_HOME%。如果JAVA_HOME是空的，或者javac提示「不是内部或外部命令」，那就说明环境变量没配好。Windows 下需要把 JDK 的bin目录加到Path里，同时新建JAVA_HOME指向 JDK 根目录；macOS 和 Linux 下在~/.bashrc或~/.zshrc里加export JAVA_HOME=/你的/jdk/路径和export PATH=$JAVA_HOME/bin:$PATH，然后source一下。

提示：如果你同时装了多个 JDK，命令行里java -version显示的未必是你以为的那个。用which java（Windows 用where java）看实际调用的是哪个路径下的可执行文件，这一步能省掉大量「明明装了却用不了」的玄学时间。

2.2 源码目录结构与编译运行的最小命令

一份典型的 Java 俄罗斯方块源码，目录结构通常长这样：

Tetris/ ├── src/ │ ├── Main.java │ ├── GamePanel.java │ ├── Tetromino.java │ └── ... └── README.md

有的项目会带pom.xml或build.gradle，那就是 Maven 或 Gradle 工程；有的就是纯src目录加一堆.java文件，这种最省事，直接用javac编译就行。先看根目录有没有构建文件，没有的话就按纯手工方式走。

假设所有.java文件都在src目录下，且没有包声明（也就是文件开头没有package xxx;），编译和运行命令是：

# 进入源码根目录 cd Tetris # 编译 src 下所有 java 文件，输出 class 到 out 目录 javac -d out src/*.java # 运行主类，假设入口是 Main java -cp out Main

-d out指定编译后的.class文件输出目录，避免和源码混在一起。-cp out是运行时指定类路径，告诉 JVM 去哪里找编译好的类。如果源码里有package com.example.tetris;这样的包声明，那编译时要保持目录结构匹配，运行时的主类名要写成全限定名，比如java -cp out com.example.tetris.Main。

如果项目带了pom.xml，那就更简单：

mvn clean compile mvn exec:java -Dexec.mainClass="Main"

mvn clean compile会清理旧的编译产物并重新编译，exec:java插件直接运行指定主类。注意exec:java默认在 Maven 的 JVM 里跑，Swing 界面一般没问题，但如果遇到图形初始化异常，可以改用java -cp target/classes Main手动运行。

2.3 跑起来之后先别急着读代码，做三件事

程序能弹出窗口、方块能下落，说明环境这关过了。这时候别一头扎进代码里，先做三件小事，能帮你快速建立对这份源码的「手感」。

第一，玩一局，故意堆到顶，看游戏结束的逻辑是怎么触发的——是弹窗、还是直接卡死、还是重置。第二，按方向键和空格，感受一下旋转和硬降的响应，记下哪些键有反应、哪些没反应。第三，把窗口拉大拉小，看画面会不会跟着缩放，还是直接错位。这三件事做完，你对这份源码的完成度和代码质量就有了一个大概判断，后面读代码时心里有底。

注意：如果窗口弹出来是空白的，或者方块画不出来，大概率是paintComponent里没调super.paintComponent(g)，或者绘图坐标算错了。这类问题在 Swing 项目里非常常见，先检查绘图方法，别急着怀疑 JDK 版本。

3. 拆解核心类：方块、面板、游戏循环各自管什么

3.1 Tetromino 类：七种方块的数据怎么组织

俄罗斯方块的核心数据是七种形状，也就是 I、O、T、S、Z、J、L。一份写得清楚的源码，通常会用一个二维数组或者坐标列表来表示每种方块的初始形态。比如用int[][]存相对坐标：

// 每种方块用一组 (x, y) 偏移量表示，原点在方块包围盒左上角 public class Tetromino { // I 型：四个格子横排 public static final int[][] I = {{0,0},{1,0},{2,0},{3,0}}; // O 型：2x2 方块 public static final int[][] O = {{0,0},{1,0},{0,1},{1,1}}; // T 型：三横加中间一竖 public static final int[][] T = {{0,0},{1,0},{2,0},{1,1}}; // 其余 S、Z、J、L 同理 }

这种写法的好处是旋转逻辑可以统一处理：旋转本质上就是把每个坐标(x, y)变换成(y, -x)或者(-y, x)，不用为每种形状单独写一套旋转代码。但要注意，I 型和 O 型的旋转中心和其他形状不一样，如果统一用包围盒中心旋转，I 型转完可能会偏移一格，O 型转完位置不变但坐标会变。很多源码在这里翻车，表现就是 I 型方块旋转时「跳」一下。

参数说明：int[][]里每个子数组是{x, y}，x向右为正，y向下为正（因为屏幕坐标系原点在左上角）。旋转时如果直接用(x, y) -> (y, -x)，得到的y可能是负数，需要再整体平移回正数区间。这个平移量取决于包围盒大小，I 型是 4x4，其他是 3x3。

3.2 GamePanel 类：绘图、键盘、计时器三合一

Swing 项目里，JPanel的子类通常承担了绘图和事件监听两个职责。俄罗斯方块的游戏面板一般会实现ActionListener接口，用一个javax.swing.Timer驱动游戏循环。核心结构大概是：

public class GamePanel extends JPanel implements ActionListener { private Timer timer; private int delay = 500; // 下落间隔，单位毫秒 public GamePanel() { setFocusable(true); // 必须，否则键盘事件收不到 addKeyListener(new TetrisKeyAdapter()); timer = new Timer(delay, this); timer.start(); } @Override public void actionPerformed(ActionEvent e) { // 每次计时器触发，方块下落一格 if (!moveDown()) { // 落不下去了，固定当前方块，检查消行，生成新方块 lockPiece(); clearLines(); spawnNewPiece(); } repaint(); // 请求重绘 } @Override protected void paintComponent(Graphics g) { super.paintComponent(g); // 这一行不能省 // 画背景网格、已固定的方块、当前下落方块 } }

setFocusable(true)是血泪经验：不写这一行，面板收不到键盘事件，按什么键都没反应，但程序看起来一切正常。timer.start()启动游戏循环，actionPerformed里做状态更新，repaint()触发重绘。注意repaint()只是「请求」重绘，实际调用paintComponent的时机由 Swing 的绘制线程决定，所以不要在actionPerformed里直接调paintComponent。

参数说明：delay控制下落速度，数值越小越快。500 毫秒是偏慢的入门速度，实际游戏里通常会随着分数增加逐步减小这个值。但注意不要在actionPerformed里直接改timer.setDelay()，因为Timer的延迟变更不是立即生效的，更稳妥的做法是维护一个speedLevel变量，每次触发时根据它决定是否要timer.setDelay(newDelay)。

3.3 碰撞检测：边界判断和已固定方块的叠加检查

碰撞检测是俄罗斯方块里最容易写出 bug 的地方。核心逻辑就两条：一是方块不能超出左右下边界，二是方块不能和已经固定的方块重叠。用代码表达大概是：

private boolean isValidPosition(int[][] shape, int offsetX, int offsetY) { for (int[] cell : shape) { int x = cell[0] + offsetX; int y = cell[1] + offsetY; // 左右边界和下边界检查 if (x < 0 || x >= COLS || y >= ROWS) { return false; } // 和已固定方块的重叠检查 if (y >= 0 && board[y][x] != 0) { return false; } } return true; }

COLS和ROWS是游戏区域的列数和行数，常见是 10 列 20 行。board是一个二维数组，0 表示空，非 0 表示已固定方块的颜色索引。注意y >= 0这个判断：方块刚生成时，部分格子可能在屏幕上方（y < 0），这时候不应该检查board，否则会数组越界。

提示：旋转的时候不要直接改当前方块的坐标，而是先算出旋转后的新坐标，用isValidPosition验一遍，通过了再应用。这个「先验后改」的习惯能避免大量旋转穿墙和卡死的 bug。

4. 改造实战：调速度、加暂停、改配色

4.1 下落速度随分数动态调整

原版源码里delay通常是写死的，改起来很简单，但要注意改的时机和方式。我一般会加一个level变量，每消 10 行升一级，每升一级把delay减少 50 毫秒，但不低于 100 毫秒：

private int level = 1; private int linesCleared = 0; private static final int BASE_DELAY = 500; private static final int MIN_DELAY = 100; private void updateSpeed() { int newDelay = Math.max(MIN_DELAY, BASE_DELAY - (level - 1) * 50); if (timer.getDelay() != newDelay) { timer.setDelay(newDelay); } } // 在消行逻辑里调用 private void clearLines() { int cleared = 0; // ... 消行循环 ... linesCleared += cleared; int newLevel = linesCleared / 10 + 1; if (newLevel != level) { level = newLevel; updateSpeed(); } }

Math.max保证速度不会无限加快到无法操作。timer.getDelay() != newDelay这个判断是为了避免重复设置相同的延迟，虽然setDelay本身开销不大，但频繁调用会让计时器重新计算下一次触发时间，可能导致下落节奏抖动。

4.2 加一个暂停功能：别让 Timer 空转

暂停的实现有两种常见做法：一是timer.stop()，恢复时timer.start()；二是用一个isPaused标志位，在actionPerformed里判断，暂停时直接return。第一种更干净，但要注意timer.start()会重置计时周期，恢复后方块不会立刻下落，而是等一个完整的delay才动。第二种响应更平滑，但计时器一直在跑，只是不做状态更新。

我一般用第一种，配合键盘事件：

private boolean isPaused = false; // 在键盘监听里 if (e.getKeyCode() == KeyEvent.VK_P) { if (isPaused) { timer.start(); } else { timer.stop(); } isPaused = !isPaused; repaint(); // 重绘以显示暂停提示 }

repaint()是为了在画面上显示「已暂停」的文字。注意暂停时如果用户按了方向键，不应该让方块移动，所以在moveDown、moveLeft等方法开头加一句if (isPaused) return false;。

4.3 改配色：从 Color 常量到主题切换

原版源码里颜色通常是硬编码的Color.RED、Color.BLUE之类。想改配色，最直接的办法是定义一个Color[]数组，按方块类型索引：

private static final Color[] PIECE_COLORS = { new Color(0, 240, 240), // I 青色 new Color(240, 240, 0), // O 黄色 new Color(160, 0, 240), // T 紫色 new Color(0, 240, 0), // S 绿色 new Color(240, 0, 0), // Z 红色 new Color(0, 0, 240), // J 蓝色 new Color(240, 160, 0) // L 橙色 };

绘图时用g.setColor(PIECE_COLORS[type])取色。如果想做主题切换，就把这个数组换成从配置读取，或者定义几套预设，用一个themeIndex变量切换。注意new Color(r, g, b)的三个参数是 0 到 255 的整数，别写成 0 到 1 的浮点数，否则颜色会全黑。

注意：改配色时别忘了背景网格线和已固定方块的颜色也要跟着调，否则可能出现「方块颜色变了但网格还是原来的灰色」这种不协调的情况。网格线颜色建议用比背景稍深一点的灰，对比度不要太高。

5. 避坑与排查：那些让俄罗斯方块跑不起来的常见问题

5.1 键盘按了没反应

现象：程序能跑，方块自己往下掉，但按左右键和空格完全没反应。

原因：JPanel默认不接收键盘焦点，没有setFocusable(true)或者焦点被其他组件抢走了。

解决：在面板构造函数里加setFocusable(true)和requestFocusInWindow()。如果还是不行，检查是不是有别的组件（比如按钮）抢了焦点，或者把键盘监听改成用KeyBindings绑定到WHEN_IN_FOCUSED_WINDOW输入映射上，这样不依赖焦点也能响应。

5.2 方块旋转后穿墙或卡死

现象：按旋转键，方块有时候会跑到边界外面，或者和已固定方块重叠。

原因：旋转逻辑直接改了坐标，没有做碰撞检测；或者旋转中心选错了，导致坐标偏移。

解决：旋转前先算出新坐标，用isValidPosition验一遍，不通过就尝试左右平移一格再验，还不行就放弃这次旋转。这个「踢墙」逻辑是标准做法，能解决绝大多数旋转卡死问题。

5.3 消行之后分数不对或者行没消干净

现象：明明填满了一行，但没消掉，或者消了但分数加错了。

原因：消行循环的遍历方向写反了，从下往上遍历时删掉一行会导致上面的行索引错位；或者分数计算用了错误的行数。

解决：消行时从下往上遍历，遇到满行就把该行以上的所有行整体下移一行，然后把最顶行清空。分数按一次消的行数给不同权重，比如 1 行 100 分、2 行 300 分、3 行 600 分、4 行 1000 分，这个权重表在大多数俄罗斯方块实现里都通用。

5.4 游戏结束后重新开始，状态没重置干净

现象：点了重新开始，但分数还是上一局的，或者方块堆叠还在。

原因：重置逻辑只清了部分状态，board数组、分数、等级、当前方块都没完全复位。

解决：写一个resetGame()方法，把所有可变状态集中重置：board全部置 0、分数归零、等级归 1、重新生成第一个方块、timer.setDelay(BASE_DELAY)、isPaused置 false。这个方法在游戏结束和手动重开时都调用，保证状态一致。

5.5 窗口缩放后画面错位

现象：拉大窗口，方块和网格线位置对不上，或者画面只画在左上角。

原因：绘图坐标用了固定像素值，没有根据面板实际尺寸做缩放或居中。

解决：在paintComponent里用getWidth()和getHeight()计算偏移量，把游戏区域居中绘制。如果不想做缩放，至少要把绘制原点平移到居中位置，否则窗口一大画面就偏在角落。

6. 从能改到能讲：用俄罗斯方块练手 Java 面试题里的那些点

把这份源码改到能跑、能暂停、能变速之后，其实你已经顺手练了一批 Java 面试题里常问的东西。比如Tetromino类的设计就是面向对象编程里「用数据描述行为」的典型；GamePanel里的Timer和ActionListener是观察者模式的简化版；board二维数组的遍历和消行逻辑，本质上就是数组操作和边界处理。如果你正在准备 Java 基础相关的面试，拿这个项目当素材，比背八股文有意思得多。

再往深走一步，可以试着把游戏状态和渲染分离。现在的写法是GamePanel既管数据又管画图，改起来容易牵一发动全身。一个更干净的结构是：单独写一个GameState类，只负责board、当前方块、分数、等级这些数据，提供moveDown、rotate、clearLines等方法；GamePanel只负责从GameState读数据然后画出来。这样你想加一个「AI 自动玩」的功能时，只需要写一个类去操作GameState，完全不用碰绘图代码。

验证改造是否成功，我一般用三个检查点：一是连续玩三局，看有没有卡死或穿墙；二是故意在边界处旋转 I 型和 O 型，看位置对不对；三是把窗口拉到最大和最小，看画面是否始终居中且比例正常。这三个检查点过了，基本就能拿去当课程设计案例源码交了。

最后说个我自己的习惯：每次改完一个功能，先不急着改下一个，而是把当前版本复制一份存成Tetris_v1、Tetris_v2，这样改崩了随时能退回去。俄罗斯方块这种小项目，翻车成本低，但养成留后悔药的习惯，放到大项目里能救命。希望帮到你。

本文还有配套的精品资源，点击获取