简介一款基于Java开发的森林冰火人单人版小游戏源码与素材齐全适合刚掌握Java语法、想进阶GUI开发的初学者也可作为高校课程设计参考。压缩包共78个文件含6个java源文件、7个class文件、48张jpg场景图、14个gif动效素材大小仅2.98MB并附Eclipse工程配置便于直接导入运行。项目完整实现了角色移动跳跃、吃水晶积分、倒计时失败等机制涉及游戏循环、键盘事件监听、重力与碰撞检测、Timer定时等知识点。已有2660人学习下载通过阅读源码可掌握Swing/AWT界面与事件处理配合方式也可对照class与java源码理解编译运行机制还能在此之上扩展关卡或双人模式。1. 项目定位一个能跑、能读、能改的 Java 游戏入门范本如果你想找一个“开箱能玩、拆开能学”的 Java 小游戏源码这个《森林冰火人单人版》压缩包值得拆一遍。它把经典双人合作玩法改成了单人操作同一张地图里同时摆着火娃和冰娃你通过按键切换当前控制角色避开各自克制的液体陷阱最终走到对应出口。这个项目代码量不大却覆盖了 Java 游戏开发的几个必考模块Swing 窗口、游戏主循环、文本关卡解析、瓦片碰撞检测、角色状态切换。两类人适合入手刚学完 Java 基础、想找一个不依赖框架的实战项目的新手准备游戏方向面试、需要快速讲清“碰撞怎么检测”“双角色怎么切换”的开发者。下面按我拿到这种包时的拆解顺序写。2. 整体架构目录、游戏循环与地图资源是怎么串起来的拿到陌生 Java 游戏我一般不看类方法先看目录。目录结构能直接告诉你这个项目是“一个巨型 Main 类”还是“模块化的小工程”。2.1 目录结构先找入口再认资源目录解压后常见布局如下不同来源的包可能少了out或resources但至少都会保留srcForestIceFire/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/example/game/ │ │ │ ├── Game.java │ │ │ ├── GameFrame.java │ │ │ ├── GamePanel.java │ │ │ ├── LevelManager.java │ │ │ ├── Player.java │ │ │ ├── CollisionUtil.java │ │ │ └── AudioPlayer.java │ │ └── resources/ │ │ ├── levels/level1.map │ │ ├── levels/level2.map │ │ └── images/fire.png, water.png, background.jpg ├── README.md └── run.bat为什么要先找入口因为 Java 没有强迫规定入口文件名可能是Game、Main也可能是ForestIceFire。直接打开任意.java文件搜public static void main就能锁定主类。这里的主类大概率是Game.java它创建主窗体GameFrame再把GamePanel嵌进窗口。GamePanel承载了游戏循环、键盘监听、碰撞调用和绘制请求是核心中的核心。还要注意如果压缩包里带了out目录或已编译的.class说明包含构建产物。我建议不要直接跑这些老 class一律从src重新编译避免新旧代码混在一起出现诡异 bug。2.2 游戏主循环基于 Swing Timer 的定时器模型游戏能“动起来”的根基是循环每帧更新状态、每帧重绘、每帧读取输入。Swing 小游戏最省事的循环就是javax.swing.Timer它天然跑在事件分发线程上不需要处理跨线程绘制。public class GamePanel extends JPanel implements ActionListener { private Timer gameTimer; private GameState state; private long lastFrameTime; public GamePanel() { state new GameState(); // 16ms 一帧约 60 FPS如果卡顿可以放宽到 20ms gameTimer new Timer(16, this); gameTimer.start(); } Override public void actionPerformed(ActionEvent e) { long now System.currentTimeMillis(); float delta (now - lastFrameTime) / 1000f; lastFrameTime now; state.update(delta); repaint(); } Override protected void paintComponent(Graphics g) { super.paintComponent(g); state.draw(g); } }这里最容易被误解的一点Timer只是周期性提醒并不保证每一帧的耗时是 16ms。如果update()里做了太重的遍历超过 16ms帧率照样降。好在单人版地图很小普通状态更新只需要遍历几十行宽的字符数组性能压力不大。另一种常用方案是独立线程while(true) Thread.sleep(16)。表面看差不多但它会把逻辑放到非 EDT 线程而 Swing 的绘制不允许跨线程直接操作必须用SwingUtilities.invokeLater丢回事件线程。处理不好就是画面闪烁、按键失灵甚至会死锁。所以我拆这种项目时不会急着改线程模型。GameState本身也是个关键设计。它把当前场景、关卡索引、玩家列表、键盘状态集中管理GamePanel不需要维护一大堆布尔值。暂停、关卡切换、菜单返回这些逻辑都能放到 state 里public class GameState { public enum Status { INIT, PLAYING, PAUSED, LEVEL_CLEARED, GAME_OVER } private Status status Status.INIT; private LevelManager levelManager; private Player[] players; private int currentLevel; public void update(float delta) { if (status ! Status.PLAYING) { return; // 暂停或通关时不更新逻辑 } // 后续接角色更新和碰撞检测 } }引入status后的好处是暂停不再需要停掉 Timer只要在 update 入口做一个 guard。想重新开始关卡也只需调用resetLevel()把角色坐标恢复到出生点而不是销毁整个 GamePanel 重建窗口。2.3 地图资源解析字符串矩阵驱动的关卡设计森林冰火人的关卡本质是一张二维网格每个字符代表一种地形或物件。LevelManager负责把它读进char二维数组绘制层再逐格渲染。############ #F..E..P1 # #..~~..P2 # #..**.. # ############常见字符约定如下。不同包可能有差异以项目里 README 为准字符含义视觉表现#墙体棕色砖块.可走地面浅色地面~水池蓝色水面*岩浆池红色岩浆P1火娃出生点红色小人P2冰娃出生点蓝色小人F/W火/冰出口对应颜色大门这种字符矩阵的设计直接拉低了二次开发门槛加一个新关卡就是加一个 map 文件不用动 Java 代码。解析代码最常踩的坑是“行列长度不一致”有的行短、有的行长直接line.charAt(c)会越界。看下面的处理方式public class LevelManager { private char[][] tiles; private int rows, cols; private int fireStartX, fireStartY; private int waterStartX, waterStartY; public LevelManager(String path) throws IOException { ListString lines Files.readAllLines(Paths.get(path), StandardCharsets.UTF_8); rows lines.size(); cols 0; for (String line : lines) { cols Math.max(cols, line.length()); } tiles new char[rows][cols]; for (int r 0; r rows; r) { String line lines.get(r); for (int c 0; c cols; c) { char ch c line.length() ? line.charAt(c) : ; tiles[r][c] ch; if (ch P) { fireStartX c; fireStartY r; } else if (ch Q) { waterStartX c; waterStartY r; } } } } }这段代码有两个细节值得摘出来读取用了Files.readAllLines并显式传StandardCharsets.UTF_8解决了 Windows 下 GBK 编码导致的中文注释乱码。出生点坐标在解析时就缓存下来后面resetLevel()可以直接复用不需要再扫描整张地图。关卡解析完成后GameState遍历tiles遇到P或Q就创建对应 Player。地图数据和游戏逻辑就此解耦。我拆代码时看到这样的结构会下意识认为作者是有点工程经验的至少玩过不只一个 JFrame 项目。提示如果你的包把出生点字符写成了P1、P2而不是单独的P和Q解析时要注意先读第一个字符别把数字也当成地形标记。3. 核心模块拆解角色状态、碰撞检测与双控逻辑3.1 角色实体与状态机一个 Player 类撑起两种玩法游戏里火娃和冰娃的差异本质只是“谁能碰水、谁能碰岩浆”。把布尔属性isFire放进 Player比写两个子类更省事因为移动、跳跃、重力几乎完全一致。public class Player { public enum Facing { LEFT, RIGHT } public enum State { IDLE, RUNNING, JUMPING, DEAD, WIN } private int x, y; private int vx, vy; private boolean isFire; private Facing facing; private State state; private static final int GRAVITY 1; private static final int MOVE_SPEED 2; private static final int JUMP_FORCE -9; public Player(int x, int y, boolean isFire) { this.x x; this.y y; this.isFire isFire; this.facing Facing.RIGHT; this.state State.IDLE; } public void startMove(boolean right) { facing right ? Facing.RIGHT : Facing.LEFT; vx right ? MOVE_SPEED : -MOVE_SPEED; state State.RUNNING; } public void stopMove() { vx 0; state State.IDLE; } public void jump() { if (state State.JUMPING) return; vy JUMP_FORCE; state State.JUMPING; } public void update() { x vx; y vy; if (vy 4) vy GRAVITY; } public boolean isFire() { return isFire; } }这段代码有三个关键点用State枚举代替散落的布尔值。不然很快会出现isRunning !isJumping !isDead这种没法读的条件。MOVE_SPEED、GRAVITY做成常量调手感就是改数值。火娃跳得更高冰娃更沉都可以在各自的构造参数里传一个加速度系数。update()里 x 和 y 分开累加是为了配合后面的分轴碰撞检测。很多平台游戏都会这么做因为“水平撞墙”和“落地踩地”需要不同的修正逻辑。职责划分也很重要。Player 本身不调用碰撞检测它只负责携带坐标、状态和速度。碰撞判断统一放到CollisionUtil这样将来加敌人、加可推动箱子都能复用同一套移动碰撞代码。3.2 瓦片碰撞检测从矩形相交到“液体致命”判断碰撞检测是这类瓦片游戏的核心。项目里常用“中心点 下一帧坐标”的方式判断但这种方式有个隐患角色边缘会陷进墙里。更稳妥的做法是“角点检测”。下面这段是比较实用的版本public class CollisionUtil { private static final int TILE_SIZE 32; public static boolean isBlocked(char[][] map, int row, int col) { if (row 0 || row map.length || col 0 || col map[0].length) { return true; // 越界按墙处理 } char tile map[row][col]; return tile # || tile ; } public static boolean canMoveTo(Player p, char[][] map, int dx, int dy) { int newX p.getX() dx; int newY p.getY() dy; int left newX / TILE_SIZE; int right (newX TILE_SIZE - 1) / TILE_SIZE; int top newY / TILE_SIZE; int bottom (newY TILE_SIZE - 1) / TILE_SIZE; for (int row top; row bottom; row) { for (int col left; col right; col) { if (isBlocked(map, row, col)) { return false; } } } return true; } public static boolean isLethal(char[][] map, int row, int col, boolean isFire) { if (row 0 || row map.length || col 0 || col map[0].length) { return false; } char tile map[row][col]; if (isFire) return tile ~; return tile *; } }canMoveTo先算出角色矩形四个角覆盖到的格子范围再逐格看是否被墙阻挡。注意边界条件是(newX TILE_SIZE - 1) / TILE_SIZE如果直接用newX / TILE_SIZE再加上TILE_SIZE会导致右侧多算一格角色会无端被墙卡住。碰撞后的修正逻辑通常放在移动里public void moveWithCollision(Player p, char[][] map) { if (CollisionUtil.canMoveTo(p, map, 0, p.getVy())) { p.setY(p.getY() p.getVy()); } else { p.setVy(0); } if (CollisionUtil.canMoveTo(p, map, p.getVx(), 0)) { p.setX(p.getX() p.getVx()); } else { p.setVx(0); } }先做纵向移动再做横向移动。纵向落地后vy归零角色的“脚下”就贴合地面横向撞墙后vx归零角色贴着墙面滑行。这种“分轴修正”比矩形相交后统一推回要稳得多。液体致命判断放在移动之后。火娃碰到~冰娃碰到*对应的处理一般不是“立刻减血”而是调用resetLevel()把角色送回出生点。原版游戏用“幽灵残留”的视觉反馈来提示玩家死亡位置这个项目是否做了同样效果要看draw层有没有多画一条渐隐轨迹。3.3 单人双控手动切换与自动跟随的实现代价“单人版”最核心的变化在控制层。常见做法有三类复杂度差异很大。第一种是同键同步移动一根方向键同时操控两个角色。实现最简单但关卡没法做分工设计基本就是推箱子。第二种是手动切换按 Tab 切换当前控制角色。这是单人版最常用的方案代码很直白public class PlayerManager { private Player[] players; private int currentPlayer 0; public void switchPlayer() { currentPlayer 1 - currentPlayer; Player active players[currentPlayer]; // 换人时清空速度避免惯性残留 active.setVx(0); active.setVy(0); } public Player getCurrentPlayer() { return players[currentPlayer]; } public void handleKeyPress(int keyCode) { Player p getCurrentPlayer(); if (keyCode KeyEvent.VK_SPACE) { p.jump(); } else if (keyCode KeyEvent.VK_LEFT) { p.startMove(false); } else if (keyCode KeyEvent.VK_RIGHT) { p.startMove(true); } } }这里最容易被忽略的一行是setVx(0); setVy(0);。不清理速度的话切换后旧角色会带着之前的惯性继续滑过两秒你可能看到火娃自己掉进岩浆。这种 bug 不是必现而是取决于切人的瞬间速度方向定位时很折磨人。第三种是自动跟随非控制角色跟着主角走遇到自己不能走的地形就停住。这种 AI 写起来不难但容易“原地抖动”private void follow(Player follower, Player leader, char[][] map) { if (Math.abs(follower.getX() - leader.getX()) TILE_SIZE) { return; // 距离够近不追 } int dir Integer.compare(leader.getX(), follower.getX()); if (CollisionUtil.canMoveTo(follower, map, dir * MOVE_SPEED, 0)) { follower.startMove(dir 0); } else { follower.stopMove(); // 前方是墙或物种原地等 } }自动跟随最大的代价在关卡设计不能设计“必须让冰娃单独待在水边”的机关否则 AI 会在水边反复试探看起来像抽风。从工程角度说手动切换是性价比最高的方案因为我后续要改成双人玩法时只要把currentPlayer替换成两套按键映射其余逻辑几乎不用动。4. 运行与避坑从命令行编译到地图乱码排查4.1 环境准备JDK、编码、工作目录跑这个项目的硬性条件只有一个装了 JDK。Swing 是标准库JDK 8 就能跑。如果你机器上是 JDK 17 也不用慌这个项目基本不碰内部 API正常javac就能过。真正麻烦的是编码。源码和地图文件多是 UTF-8 存储而 Windows 命令行默认按 GBK 处理。编译前建议先验一下环境javac -version java -version如果看到javac正常但编译源码时中文字符报错基本就是没指定编码。编译命令要加-encoding UTF-8javac -encoding UTF-8 -d out src/main/java/com/example/game/*.java java -cp out -Dfile.encodingUTF-8 com.example.game.Game-Dfile.encodingUTF-8是运行时让 JVM 按 UTF-8 读资源文件。不写的话地图里的中文注释可能不影响运行但某些字符串判断可能因为乱码出错。打包成run.bat时还要处理工作目录。脚本所在目录和双击脚本时的当前目录不一定一致稳妥做法是先切到脚本自身目录echo off cd /d %~dp0 javac -encoding UTF-8 -d out src/main/java/com/example/game/*.java java -cp out -Dfile.encodingUTF-8 com.example.game.Game%~dp0拿到的是脚本所在路径加上cd /d确保不管从哪个盘符启动都能定位到资源目录。这一步能避免“明明文件在 resources 里却报找不到 level1.map”的问题。4.2 命令行与 IDE 的启动步骤命令行方式就是上面两行。如果你用的是 IDEA操作会多一点新建一个普通 Java 项目。把src/main/java下的java目录复制进项目的src。把resources目录复制到项目根目录然后在 Project Structure 里把它标记为Resources。设置主类为com.example.game.Game。运行配置的工作目录保持项目根目录。最容易漏的一步是“把 resources 标记为资源根”。如果漏了IDEA 编译时不会把图片和地图文件复制到输出目录运行时就会出现空指针。这类错误排查时容易被误导成代码问题其实只是资源路径没进 classpath。如果你在使用 Eclipse也需要把resources添加到 Build Path 的Source选项卡里。原则都是一样的让编译后的 classpath 同时包含out和resources。4.3 常见问题与避坑记录下面这几条是我拆这类 Swing 游戏时反复遇见的每一条都有具体场景。现象 1编译报错“编码 GBK 的不可映射字符”。原因源码是 UTF-8命令行javac按系统默认编码 GBK 读取中文字符串直接炸。解决编译命令加-encoding UTF-8。IDE 里则检查 File Encoding全部切到 UTF-8。现象 2运行后地图一片空白角色也不出现。原因常见的是地图文件路径没找到异常被catch吞掉。解决先别动逻辑在LevelManager的 catch 块里打e.printStackTrace()再打印new File(.).getAbsolutePath()确认当前工作目录。路径修正后空白问题基本消失。现象 3图片能加载但角色浮在错误位置。原因绘制时没有把逻辑坐标转换成像素坐标。比如角色逻辑坐标是 5,3绘制却用了drawImage(img, 5, 3, null)一格只有 5 像素当然画不齐。解决统一先乘TILE_SIZE也就是drawImage(img, x * TILE_SIZE, y * TILE_SIZE, null)。如果角色还带偏移量把这个偏移作为常量单独管理。现象 4Tab 切换后角色不受控制。原因按键监听里没有用currentPlayer方向键同时改了两个 Player。解决keyPressed里只操作players[currentPlayer]。再检查是否在switchPlayer时把索引减了两次导致焦点又切回原来的角色。现象 5游戏运行像幻灯片掉帧严重。原因如果在地图绘制里每一帧都创建new Font、新Color对象或者在paintComponent里遍历整张地图而地图又特别大就会卡成幻灯片。解决只绘制可视区域内的瓦片从cameraX / TILE_SIZE到(cameraX panelWidth) / TILE_SIZE。另一个常见做法是把静态背景先离屏画到一张BufferedImage每次重绘直接贴背景图角色单独画在上面。这五条覆盖了大部分新人第一次跑项目的翻车点。尤其是第五条现在地图小看不出问题一旦你改出 200x200 的大关卡不裁剪绘制区域性能一定崩。提示如果角色能穿墙而墙体前面明明有碰撞判断先检查canMoveTo里是不是用了Math.abs((newX TILE_SIZE - 1) / TILE_SIZE)导致右边界计算过宽。这是最容易出玄学 bug 的地方。5. 二次开发从改地图到改双人玩法5.1 先加一扇门让地图支持“切换触发机关”第一处值得做的改造是让地图出现“机关门”。在LevelManager里加一个setTile方法允许运行期修改某个格子的类型public void setTile(int row, int col, char tile) { if (row 0 row rows col 0 col cols) { tiles[row][col] tile; } }然后在.map文件里定义新字符V表示阀门D表示关着的门。游戏逻辑里当火娃踩到V时把全地图的D改为.。这一个改动就能让“先操作火娃开门再切回冰娃通过”成为真实玩法。逻辑判定很简单加在移动完成后的更新循环里如果当前角色的坐标与某个V重合就遍历地图把所有D替换成空格。替换后别忘了repaint()否则画面还保持着门的状态。5.2 再改输入层把单人切换升级成独立按键输入要改回真正双人玩法核心不在渲染而在输入映射。原来handleKeyPress只作用于currentPlayer改成双人后需要同时监听两套方向键。我通常用一张映射表来管理private final MapInteger, Runnable keyActions new HashMap(); private void setupKeyActions() { keyActions.put(KeyEvent.VK_W, () - players[1].jump()); keyActions.put(KeyEvent.VK_S, () - players[1].startMove(false)); keyActions.put(KeyEvent.VK_D, () - players[1].startMove(true)); keyActions.put(KeyEvent.VK_UP, () - players[0].jump()); keyActions.put(KeyEvent.VK_LEFT, () - players[0].startMove(false)); keyActions.put(KeyEvent.VK_RIGHT, () - players[0].startMove(true)); }使用Runnable的好处是以后要支持手柄或自定义按键只需要改这张表而不是在switch-case里到处加分支。验证方法也简单每次改完一个功能先通关一次原版第 1 关再进新关卡。这个强迫性习惯帮我拦下了很多“地图看着没问题角色开局就卡住”的坑。从那以后我每次拿到这种 Java 小游戏源码第一件事都是找地图字符约定第二件事是定位main方法把这两个点确认清楚才敢动代码。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/21 13:46:16 · 阅读 1.2k Java Swing小游戏源码解析：森林冰火人单人版碰撞检测与双控实现
简介一款基于Java开发的森林冰火人单人版小游戏源码与素材齐全适合刚掌握Java语法、想进阶GUI开发的初学者也可作为高校课程设计参考。压缩包共78个文件含6个java源文件、7个class文件、48张jpg场景图、14个gif动效素材大小仅2.98MB并附Eclipse工程配置便于直接导入运行。项目完整实现了角色移动跳跃、吃水晶积分、倒计时失败等机制涉及游戏循环、键盘事件监听、重力与碰撞检测、Timer定时等知识点。已有2660人学习下载通过阅读源码可掌握Swing/AWT界面与事件处理配合方式也可对照class与java源码理解编译运行机制还能在此之上扩展关卡或双人模式。1. 项目定位一个能跑、能读、能改的 Java 游戏入门范本如果你想找一个“开箱能玩、拆开能学”的 Java 小游戏源码这个《森林冰火人单人版》压缩包值得拆一遍。它把经典双人合作玩法改成了单人操作同一张地图里同时摆着火娃和冰娃你通过按键切换当前控制角色避开各自克制的液体陷阱最终走到对应出口。这个项目代码量不大却覆盖了 Java 游戏开发的几个必考模块Swing 窗口、游戏主循环、文本关卡解析、瓦片碰撞检测、角色状态切换。两类人适合入手刚学完 Java 基础、想找一个不依赖框架的实战项目的新手准备游戏方向面试、需要快速讲清“碰撞怎么检测”“双角色怎么切换”的开发者。下面按我拿到这种包时的拆解顺序写。2. 整体架构目录、游戏循环与地图资源是怎么串起来的拿到陌生 Java 游戏我一般不看类方法先看目录。目录结构能直接告诉你这个项目是“一个巨型 Main 类”还是“模块化的小工程”。2.1 目录结构先找入口再认资源目录解压后常见布局如下不同来源的包可能少了out或resources但至少都会保留srcForestIceFire/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/example/game/ │ │ │ ├── Game.java │ │ │ ├── GameFrame.java │ │ │ ├── GamePanel.java │ │ │ ├── LevelManager.java │ │ │ ├── Player.java │ │ │ ├── CollisionUtil.java │ │ │ └── AudioPlayer.java │ │ └── resources/ │ │ ├── levels/level1.map │ │ ├── levels/level2.map │ │ └── images/fire.png, water.png, background.jpg ├── README.md └── run.bat为什么要先找入口因为 Java 没有强迫规定入口文件名可能是Game、Main也可能是ForestIceFire。直接打开任意.java文件搜public static void main就能锁定主类。这里的主类大概率是Game.java它创建主窗体GameFrame再把GamePanel嵌进窗口。GamePanel承载了游戏循环、键盘监听、碰撞调用和绘制请求是核心中的核心。还要注意如果压缩包里带了out目录或已编译的.class说明包含构建产物。我建议不要直接跑这些老 class一律从src重新编译避免新旧代码混在一起出现诡异 bug。2.2 游戏主循环基于 Swing Timer 的定时器模型游戏能“动起来”的根基是循环每帧更新状态、每帧重绘、每帧读取输入。Swing 小游戏最省事的循环就是javax.swing.Timer它天然跑在事件分发线程上不需要处理跨线程绘制。public class GamePanel extends JPanel implements ActionListener { private Timer gameTimer; private GameState state; private long lastFrameTime; public GamePanel() { state new GameState(); // 16ms 一帧约 60 FPS如果卡顿可以放宽到 20ms gameTimer new Timer(16, this); gameTimer.start(); } Override public void actionPerformed(ActionEvent e) { long now System.currentTimeMillis(); float delta (now - lastFrameTime) / 1000f; lastFrameTime now; state.update(delta); repaint(); } Override protected void paintComponent(Graphics g) { super.paintComponent(g); state.draw(g); } }这里最容易被误解的一点Timer只是周期性提醒并不保证每一帧的耗时是 16ms。如果update()里做了太重的遍历超过 16ms帧率照样降。好在单人版地图很小普通状态更新只需要遍历几十行宽的字符数组性能压力不大。另一种常用方案是独立线程while(true) Thread.sleep(16)。表面看差不多但它会把逻辑放到非 EDT 线程而 Swing 的绘制不允许跨线程直接操作必须用SwingUtilities.invokeLater丢回事件线程。处理不好就是画面闪烁、按键失灵甚至会死锁。所以我拆这种项目时不会急着改线程模型。GameState本身也是个关键设计。它把当前场景、关卡索引、玩家列表、键盘状态集中管理GamePanel不需要维护一大堆布尔值。暂停、关卡切换、菜单返回这些逻辑都能放到 state 里public class GameState { public enum Status { INIT, PLAYING, PAUSED, LEVEL_CLEARED, GAME_OVER } private Status status Status.INIT; private LevelManager levelManager; private Player[] players; private int currentLevel; public void update(float delta) { if (status ! Status.PLAYING) { return; // 暂停或通关时不更新逻辑 } // 后续接角色更新和碰撞检测 } }引入status后的好处是暂停不再需要停掉 Timer只要在 update 入口做一个 guard。想重新开始关卡也只需调用resetLevel()把角色坐标恢复到出生点而不是销毁整个 GamePanel 重建窗口。2.3 地图资源解析字符串矩阵驱动的关卡设计森林冰火人的关卡本质是一张二维网格每个字符代表一种地形或物件。LevelManager负责把它读进char二维数组绘制层再逐格渲染。############ #F..E..P1 # #..~~..P2 # #..**.. # ############常见字符约定如下。不同包可能有差异以项目里 README 为准字符含义视觉表现#墙体棕色砖块.可走地面浅色地面~水池蓝色水面*岩浆池红色岩浆P1火娃出生点红色小人P2冰娃出生点蓝色小人F/W火/冰出口对应颜色大门这种字符矩阵的设计直接拉低了二次开发门槛加一个新关卡就是加一个 map 文件不用动 Java 代码。解析代码最常踩的坑是“行列长度不一致”有的行短、有的行长直接line.charAt(c)会越界。看下面的处理方式public class LevelManager { private char[][] tiles; private int rows, cols; private int fireStartX, fireStartY; private int waterStartX, waterStartY; public LevelManager(String path) throws IOException { ListString lines Files.readAllLines(Paths.get(path), StandardCharsets.UTF_8); rows lines.size(); cols 0; for (String line : lines) { cols Math.max(cols, line.length()); } tiles new char[rows][cols]; for (int r 0; r rows; r) { String line lines.get(r); for (int c 0; c cols; c) { char ch c line.length() ? line.charAt(c) : ; tiles[r][c] ch; if (ch P) { fireStartX c; fireStartY r; } else if (ch Q) { waterStartX c; waterStartY r; } } } } }这段代码有两个细节值得摘出来读取用了Files.readAllLines并显式传StandardCharsets.UTF_8解决了 Windows 下 GBK 编码导致的中文注释乱码。出生点坐标在解析时就缓存下来后面resetLevel()可以直接复用不需要再扫描整张地图。关卡解析完成后GameState遍历tiles遇到P或Q就创建对应 Player。地图数据和游戏逻辑就此解耦。我拆代码时看到这样的结构会下意识认为作者是有点工程经验的至少玩过不只一个 JFrame 项目。提示如果你的包把出生点字符写成了P1、P2而不是单独的P和Q解析时要注意先读第一个字符别把数字也当成地形标记。3. 核心模块拆解角色状态、碰撞检测与双控逻辑3.1 角色实体与状态机一个 Player 类撑起两种玩法游戏里火娃和冰娃的差异本质只是“谁能碰水、谁能碰岩浆”。把布尔属性isFire放进 Player比写两个子类更省事因为移动、跳跃、重力几乎完全一致。public class Player { public enum Facing { LEFT, RIGHT } public enum State { IDLE, RUNNING, JUMPING, DEAD, WIN } private int x, y; private int vx, vy; private boolean isFire; private Facing facing; private State state; private static final int GRAVITY 1; private static final int MOVE_SPEED 2; private static final int JUMP_FORCE -9; public Player(int x, int y, boolean isFire) { this.x x; this.y y; this.isFire isFire; this.facing Facing.RIGHT; this.state State.IDLE; } public void startMove(boolean right) { facing right ? Facing.RIGHT : Facing.LEFT; vx right ? MOVE_SPEED : -MOVE_SPEED; state State.RUNNING; } public void stopMove() { vx 0; state State.IDLE; } public void jump() { if (state State.JUMPING) return; vy JUMP_FORCE; state State.JUMPING; } public void update() { x vx; y vy; if (vy 4) vy GRAVITY; } public boolean isFire() { return isFire; } }这段代码有三个关键点用State枚举代替散落的布尔值。不然很快会出现isRunning !isJumping !isDead这种没法读的条件。MOVE_SPEED、GRAVITY做成常量调手感就是改数值。火娃跳得更高冰娃更沉都可以在各自的构造参数里传一个加速度系数。update()里 x 和 y 分开累加是为了配合后面的分轴碰撞检测。很多平台游戏都会这么做因为“水平撞墙”和“落地踩地”需要不同的修正逻辑。职责划分也很重要。Player 本身不调用碰撞检测它只负责携带坐标、状态和速度。碰撞判断统一放到CollisionUtil这样将来加敌人、加可推动箱子都能复用同一套移动碰撞代码。3.2 瓦片碰撞检测从矩形相交到“液体致命”判断碰撞检测是这类瓦片游戏的核心。项目里常用“中心点 下一帧坐标”的方式判断但这种方式有个隐患角色边缘会陷进墙里。更稳妥的做法是“角点检测”。下面这段是比较实用的版本public class CollisionUtil { private static final int TILE_SIZE 32; public static boolean isBlocked(char[][] map, int row, int col) { if (row 0 || row map.length || col 0 || col map[0].length) { return true; // 越界按墙处理 } char tile map[row][col]; return tile # || tile ; } public static boolean canMoveTo(Player p, char[][] map, int dx, int dy) { int newX p.getX() dx; int newY p.getY() dy; int left newX / TILE_SIZE; int right (newX TILE_SIZE - 1) / TILE_SIZE; int top newY / TILE_SIZE; int bottom (newY TILE_SIZE - 1) / TILE_SIZE; for (int row top; row bottom; row) { for (int col left; col right; col) { if (isBlocked(map, row, col)) { return false; } } } return true; } public static boolean isLethal(char[][] map, int row, int col, boolean isFire) { if (row 0 || row map.length || col 0 || col map[0].length) { return false; } char tile map[row][col]; if (isFire) return tile ~; return tile *; } }canMoveTo先算出角色矩形四个角覆盖到的格子范围再逐格看是否被墙阻挡。注意边界条件是(newX TILE_SIZE - 1) / TILE_SIZE如果直接用newX / TILE_SIZE再加上TILE_SIZE会导致右侧多算一格角色会无端被墙卡住。碰撞后的修正逻辑通常放在移动里public void moveWithCollision(Player p, char[][] map) { if (CollisionUtil.canMoveTo(p, map, 0, p.getVy())) { p.setY(p.getY() p.getVy()); } else { p.setVy(0); } if (CollisionUtil.canMoveTo(p, map, p.getVx(), 0)) { p.setX(p.getX() p.getVx()); } else { p.setVx(0); } }先做纵向移动再做横向移动。纵向落地后vy归零角色的“脚下”就贴合地面横向撞墙后vx归零角色贴着墙面滑行。这种“分轴修正”比矩形相交后统一推回要稳得多。液体致命判断放在移动之后。火娃碰到~冰娃碰到*对应的处理一般不是“立刻减血”而是调用resetLevel()把角色送回出生点。原版游戏用“幽灵残留”的视觉反馈来提示玩家死亡位置这个项目是否做了同样效果要看draw层有没有多画一条渐隐轨迹。3.3 单人双控手动切换与自动跟随的实现代价“单人版”最核心的变化在控制层。常见做法有三类复杂度差异很大。第一种是同键同步移动一根方向键同时操控两个角色。实现最简单但关卡没法做分工设计基本就是推箱子。第二种是手动切换按 Tab 切换当前控制角色。这是单人版最常用的方案代码很直白public class PlayerManager { private Player[] players; private int currentPlayer 0; public void switchPlayer() { currentPlayer 1 - currentPlayer; Player active players[currentPlayer]; // 换人时清空速度避免惯性残留 active.setVx(0); active.setVy(0); } public Player getCurrentPlayer() { return players[currentPlayer]; } public void handleKeyPress(int keyCode) { Player p getCurrentPlayer(); if (keyCode KeyEvent.VK_SPACE) { p.jump(); } else if (keyCode KeyEvent.VK_LEFT) { p.startMove(false); } else if (keyCode KeyEvent.VK_RIGHT) { p.startMove(true); } } }这里最容易被忽略的一行是setVx(0); setVy(0);。不清理速度的话切换后旧角色会带着之前的惯性继续滑过两秒你可能看到火娃自己掉进岩浆。这种 bug 不是必现而是取决于切人的瞬间速度方向定位时很折磨人。第三种是自动跟随非控制角色跟着主角走遇到自己不能走的地形就停住。这种 AI 写起来不难但容易“原地抖动”private void follow(Player follower, Player leader, char[][] map) { if (Math.abs(follower.getX() - leader.getX()) TILE_SIZE) { return; // 距离够近不追 } int dir Integer.compare(leader.getX(), follower.getX()); if (CollisionUtil.canMoveTo(follower, map, dir * MOVE_SPEED, 0)) { follower.startMove(dir 0); } else { follower.stopMove(); // 前方是墙或物种原地等 } }自动跟随最大的代价在关卡设计不能设计“必须让冰娃单独待在水边”的机关否则 AI 会在水边反复试探看起来像抽风。从工程角度说手动切换是性价比最高的方案因为我后续要改成双人玩法时只要把currentPlayer替换成两套按键映射其余逻辑几乎不用动。4. 运行与避坑从命令行编译到地图乱码排查4.1 环境准备JDK、编码、工作目录跑这个项目的硬性条件只有一个装了 JDK。Swing 是标准库JDK 8 就能跑。如果你机器上是 JDK 17 也不用慌这个项目基本不碰内部 API正常javac就能过。真正麻烦的是编码。源码和地图文件多是 UTF-8 存储而 Windows 命令行默认按 GBK 处理。编译前建议先验一下环境javac -version java -version如果看到javac正常但编译源码时中文字符报错基本就是没指定编码。编译命令要加-encoding UTF-8javac -encoding UTF-8 -d out src/main/java/com/example/game/*.java java -cp out -Dfile.encodingUTF-8 com.example.game.Game-Dfile.encodingUTF-8是运行时让 JVM 按 UTF-8 读资源文件。不写的话地图里的中文注释可能不影响运行但某些字符串判断可能因为乱码出错。打包成run.bat时还要处理工作目录。脚本所在目录和双击脚本时的当前目录不一定一致稳妥做法是先切到脚本自身目录echo off cd /d %~dp0 javac -encoding UTF-8 -d out src/main/java/com/example/game/*.java java -cp out -Dfile.encodingUTF-8 com.example.game.Game%~dp0拿到的是脚本所在路径加上cd /d确保不管从哪个盘符启动都能定位到资源目录。这一步能避免“明明文件在 resources 里却报找不到 level1.map”的问题。4.2 命令行与 IDE 的启动步骤命令行方式就是上面两行。如果你用的是 IDEA操作会多一点新建一个普通 Java 项目。把src/main/java下的java目录复制进项目的src。把resources目录复制到项目根目录然后在 Project Structure 里把它标记为Resources。设置主类为com.example.game.Game。运行配置的工作目录保持项目根目录。最容易漏的一步是“把 resources 标记为资源根”。如果漏了IDEA 编译时不会把图片和地图文件复制到输出目录运行时就会出现空指针。这类错误排查时容易被误导成代码问题其实只是资源路径没进 classpath。如果你在使用 Eclipse也需要把resources添加到 Build Path 的Source选项卡里。原则都是一样的让编译后的 classpath 同时包含out和resources。4.3 常见问题与避坑记录下面这几条是我拆这类 Swing 游戏时反复遇见的每一条都有具体场景。现象 1编译报错“编码 GBK 的不可映射字符”。原因源码是 UTF-8命令行javac按系统默认编码 GBK 读取中文字符串直接炸。解决编译命令加-encoding UTF-8。IDE 里则检查 File Encoding全部切到 UTF-8。现象 2运行后地图一片空白角色也不出现。原因常见的是地图文件路径没找到异常被catch吞掉。解决先别动逻辑在LevelManager的 catch 块里打e.printStackTrace()再打印new File(.).getAbsolutePath()确认当前工作目录。路径修正后空白问题基本消失。现象 3图片能加载但角色浮在错误位置。原因绘制时没有把逻辑坐标转换成像素坐标。比如角色逻辑坐标是 5,3绘制却用了drawImage(img, 5, 3, null)一格只有 5 像素当然画不齐。解决统一先乘TILE_SIZE也就是drawImage(img, x * TILE_SIZE, y * TILE_SIZE, null)。如果角色还带偏移量把这个偏移作为常量单独管理。现象 4Tab 切换后角色不受控制。原因按键监听里没有用currentPlayer方向键同时改了两个 Player。解决keyPressed里只操作players[currentPlayer]。再检查是否在switchPlayer时把索引减了两次导致焦点又切回原来的角色。现象 5游戏运行像幻灯片掉帧严重。原因如果在地图绘制里每一帧都创建new Font、新Color对象或者在paintComponent里遍历整张地图而地图又特别大就会卡成幻灯片。解决只绘制可视区域内的瓦片从cameraX / TILE_SIZE到(cameraX panelWidth) / TILE_SIZE。另一个常见做法是把静态背景先离屏画到一张BufferedImage每次重绘直接贴背景图角色单独画在上面。这五条覆盖了大部分新人第一次跑项目的翻车点。尤其是第五条现在地图小看不出问题一旦你改出 200x200 的大关卡不裁剪绘制区域性能一定崩。提示如果角色能穿墙而墙体前面明明有碰撞判断先检查canMoveTo里是不是用了Math.abs((newX TILE_SIZE - 1) / TILE_SIZE)导致右边界计算过宽。这是最容易出玄学 bug 的地方。5. 二次开发从改地图到改双人玩法5.1 先加一扇门让地图支持“切换触发机关”第一处值得做的改造是让地图出现“机关门”。在LevelManager里加一个setTile方法允许运行期修改某个格子的类型public void setTile(int row, int col, char tile) { if (row 0 row rows col 0 col cols) { tiles[row][col] tile; } }然后在.map文件里定义新字符V表示阀门D表示关着的门。游戏逻辑里当火娃踩到V时把全地图的D改为.。这一个改动就能让“先操作火娃开门再切回冰娃通过”成为真实玩法。逻辑判定很简单加在移动完成后的更新循环里如果当前角色的坐标与某个V重合就遍历地图把所有D替换成空格。替换后别忘了repaint()否则画面还保持着门的状态。5.2 再改输入层把单人切换升级成独立按键输入要改回真正双人玩法核心不在渲染而在输入映射。原来handleKeyPress只作用于currentPlayer改成双人后需要同时监听两套方向键。我通常用一张映射表来管理private final MapInteger, Runnable keyActions new HashMap(); private void setupKeyActions() { keyActions.put(KeyEvent.VK_W, () - players[1].jump()); keyActions.put(KeyEvent.VK_S, () - players[1].startMove(false)); keyActions.put(KeyEvent.VK_D, () - players[1].startMove(true)); keyActions.put(KeyEvent.VK_UP, () - players[0].jump()); keyActions.put(KeyEvent.VK_LEFT, () - players[0].startMove(false)); keyActions.put(KeyEvent.VK_RIGHT, () - players[0].startMove(true)); }使用Runnable的好处是以后要支持手柄或自定义按键只需要改这张表而不是在switch-case里到处加分支。验证方法也简单每次改完一个功能先通关一次原版第 1 关再进新关卡。这个强迫性习惯帮我拦下了很多“地图看着没问题角色开局就卡住”的坑。从那以后我每次拿到这种 Java 小游戏源码第一件事都是找地图字符约定第二件事是定位main方法把这两个点确认清楚才敢动代码。希望帮到你。本文还有配套的精品资源点击获取