Java小游戏课设交付全攻略：UML图、README与Swing实现

简介：这是一份基于Java语言开发的完整小游戏项目，兼具课程设计与毕业设计参考价值，也适合初学者通过源码研读进入游戏开发领域。压缩包内含170个文件，大小约15.89MB，既有90个Java源文件实现角色、场景与逻辑控制，也有5个FXML界面布局、63张PNG图片素材、4个JAR依赖库，以及音频、JSON配置与说明文档，项目代码、资源与文档划分清晰。已有65人学习下载，其中design.pdf以UML图清晰展示系统结构、类与对象的关系以及消息传递流程，readme则说明了具体的游戏界面与操作方式。通过主程序入口可以观察游戏初始化、主循环、用户输入处理、画面渲染与状态更新等关键流程，并结合源码理解面向对象设计思想与模块协作方式。学习者既可将其作为课程设计或毕业设计的起点，也能在此基础上扩展玩法、优化性能，积累实战经验，为后续深入Java游戏开发打下扎实基础。

1. 一个Java小游戏zip里装着什么：课程设计交付的三件套

答辩前夜，老师发回一句“你的readme呢？UML图呢？”——很多人第一次听到这两个词就是在这种时刻。这个标题里的zip不是游戏本身，而是Java小游戏课程设计/小组作业的完整交付物：源码、README里的界面说明、design.pdf里的UML设计图。三种素材各司其职，源码证明你写得出来，README证明跑起来什么样，UML图证明你动手前想清楚了。这篇文章不教你“如何想出一个游戏创意”，而是把所有时间和精力花在你最可能卡住的地方：UML图怎么画、README怎么写、源码怎么组织才像样、以及交付前哪些坑会让你翻车。

2. 从design.pdf看UML设计：类图、时序图怎么画才不会答辩翻车

2.1 先定玩法再画图：用例图和状态图定边界

很多人的UML图是代码写完以后补的——补出来的图通常长得很抽象：一个Main类拉一根线连到GameFrame，GameFrame又连着所有东西。老师一眼就知道这不是设计，是复盘。

我一般建议先写一页纸的玩法说明，再画用例图。用例图回答的是“谁在用这个系统、能干什么”。一个单人Java小游戏，用例特别简单：玩家开始游戏、控制移动、查看分数、重新开始。但恰恰是这四行用例，能逼你把“游戏结束以后能不能重来”“暂停算不算一个状态”这种问题提前想清楚。

然后是状态图。贪吃蛇有开局、运行、暂停、吃到食物加分、碰墙结束这几个状态；接苹果、打砖块这种也类似。状态图不用画得很规范，但要把“从一个状态跳到另一个状态的事件”写出来。比如键盘空格是暂停/恢复，碰到边界是结束，结束以后回车是重新开始。这些事件就是后面写代码时的if和switch分支。状态图画不清楚，代码里就会全是临时变量加布尔开关，改一个地方崩三个地方。

2.2 类图是给答辩老师看的：实体、控制与边界的粒度控制

类图是整个design.pdf里的门面，也是最多人画崩的地方。一个合格的类图不是越详细越好，而是让老师一眼看出“你用了什么结构”。以贪吃蛇为例，常见的类图拆法是三类角色。

边界类（窗口和面板）负责显示，控制类（游戏逻辑）负责规则，实体类（蛇、食物、分数）负责数据。对应到Java代码，就是GameFrame（JFrame窗口）、GamePanel（JPanel绘制面板）、Snake（蛇身子链表）、Food（食物坐标）、ScoreManager（计分与存档）。整个项目不超过7个类，但每个类的职责边界非常清楚。

画类图的时候要注意属性类型和方法的返回值，不要画一个没有任何参数和返回值的方法名，那等于没画。像move()这种至少要写清楚返回void还是boolean。一个判断移动是否合法的isAlive()返回boolean，是加分项。字段用private标注，方法用public标注，这也是要养成的基本习惯。尽量控制在6到8个类，超过10个类的“小游戏设计图”基本就是啰嗦，课堂作业千万不要贪图规模。

2.3 从UML到PDF：用PlantUML十分钟生成design.pdf

UML图不用手画，手画的图改起来是灾难。无论是课程设计还是小组合作，我推荐用PlantUML生成，这样到后面改代码时，图可以同步更新，而不是等最后一天重新画。

PlantUML的类图文本很简单，给一个可复用的骨架：

@startuml class Snake { - body: List<Point> - direction: Direction + move(): boolean + turn(d: Direction): void + eat(): void } class Food { - position: Point + generate(maxX: int, maxY: int): void } class GamePanel { - snake: Snake - food: Food - timer: Timer + paintComponent(g: Graphics): void + actionPerformed(e: ActionEvent): void } class ScoreManager { - score: int + addScore(points: int): void + save(): void + load(): int } Snake --> Food GamePanel --> Snake GamePanel --> Food GamePanel --> ScoreManager @enduml

PlantUML的语法非常有规律，类名后面大括号里写属性与方法，横线数量表示访问修饰符：-代表private，+代表public。箭头-->表示依赖关系，Snake --> Food说明Snake类用到了Food类。生成PDF的方式有两种：本地装了PlantUML就直接跑plantuml design.puml -tpdf，或者用在线编辑服务导出。在线工具的注意点是，把你的UML图内容粘贴过去以后选择导出PDF，不要用截图，截图的效果和字体都显得不正式。

除了类图，design.pdf里一般还要放一张时序图，说明一次完整的“按键到画面刷新”流程。文字说明和绘制顺序可以这样写：玩家按键触发keyPressed()，GamePanel调用Snake.turn()改变方向，Timer触发actionPerformed()，Snake.move()算出新位置，最后repaint()重绘画面。画时序图的意义，就是证明你理解事件驱动的机制，而不是背了一个Swing模板。

3. 把界面写进README：截图、操作说明与运行环境的落地套路

3.1 README里该放什么：不只是“照着敲就能跑”

README在课程设计里承担两个角色：一是给老师看——这个游戏怎么运行、有什么功能、代码结构什么样；二是给接手的人看——他会用命令行或IDE运行你的项目。所以结构要比普通开源项目更朴素直白。一个合格的Java小游戏README，我一般建议按下面顺序写：

项目名称和一句话介绍、运行环境要求（JDK版本、是否需要IDE）、启动步骤（编译命令和运行命令）、操作说明（键位表）、功能列表、分包结构说明、界面截图。核心是“别人拿这个README能不能把游戏跑起来”——如果运行说明不够清晰，老师甚至会怀疑代码能不能跑。

运行环境这一节特别容易写马虎。JDK版本一定要写。很多课程要求JDK 8或JDK 11，但你用的可能是JDK 17的新语法，对方用老版本编译时就会报错。建议在README里写清“JDK 8及以上”，同时把编译用的javac版本在命令里体现出来。

3.2 截图怎么截得像样：窗口尺寸、游戏状态与GIF动图

README里放截图，很多人以为就是“开个窗口按一下PrintScreen”，但同样一个游戏，截图是否讲究，观感差别很大。要截三张图：刚打开时的主界面、游戏进行中的画面、操作说明或菜单界面。这样可以快速展示项目全貌。

截图的时候注意几个细节。调整好游戏窗口大小，不要最大化，保持固定尺寸，否则图片会显得没设计感。截含有文字的界面，而不是只有色块和图形的空白帧。背景颜色如果默认是黑色，可以在代码里换一个灰色或深蓝色，否则图片发到文档里对比度很低。

另外建议加一张GIF动图。README里放GIF是近年课程设计里比较讨巧也实用的习惯，能让老师一眼看到能动起来的效果。用ScreenToGif这类录屏工具录制10到15秒，控制在2MB以内，直接把文件放到项目的screenshot文件夹里，然后用Markdown引入。GIF文件注意不要放在桌面路径下，放进项目仓库里，再用相对路径引用，这样整个zip给别人时才不会丢文件。

3.3 README的模板骨架：直接可改的Markdown结构

如果不想从空白开始写README，可以直接拿下面这个骨架改。这是我从几个课设项目里总结出来的写法，兼顾“给老师看”和“给同学跑”两个目标。

# 贪吃蛇小游戏 基于 Java Swing 实现的贪吃蛇游戏，JDK 8+ 可运行。 ## 运行环境 - JDK 8 及以上 - 无第三方依赖 ## 启动步骤 ```bash # 在项目根目录执行 javac -encoding UTF-8 src/*.java -d out java -cp out com.course.snake.Main

游戏操作

界面截图

功能列表

• 实时计分与最高分存档
• 食物随机生成、蛇身增长
• 暂停恢复与游戏结束重开

包结构说明

• Main.java：程序入口
• GamePanel.java：游戏绘制与主循环
• Snake.java：蛇的移动与碰撞逻辑
• Food.java：食物生成
• ScoreManager.java：分数读写

关键细节说明：第一，把`javac -encoding UTF-8`写进启动命令，避免Windows控制台默认编码导致中文乱码；第二，包名用`com.course.snake`而不是默认包，是更规范的Java习惯；第三，表格里的键位表比大段文字更容易阅读；第四，用相对路径指向项目内的screenshot目录，而不是外链图片网址。这样整个项目目录可以被打包成一个zip直接分发。 ## 4. 拆开源码看最小可玩的Swing游戏：主循环、键盘事件与分层 ### 4.1 包结构与启动入口：别把两百行全塞进main Java小游戏最容易写烂的写法，是把所有逻辑都堆在main方法或者JFrame里。一个Class文件里塞了贴图、游戏循环、碰撞检测、计分、键盘监听，整个文件能达到五百行，能跑但是没法维护，而且答辩的时候老师翻代码会很难受。 比较规范的入口设计是main方法只做两件事：设置窗口属性，启动游戏面板。主面板的启动代码骨架如下，这个写法适用于绝大多数Swing小游戏： ```java package com.course.snake; import javax.swing.JFrame; public class Main { public static void main(String[] args) { JFrame frame = new JFrame("贪吃蛇小游戏"); frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); frame.setResizable(false); GamePanel panel = new GamePanel(); frame.add(panel); frame.pack(); frame.setLocationRelativeTo(null); frame.setVisible(true); panel.start(); } }

这段代码要做的事情是：创建一个不可拉伸的窗口，把GamePanel加进去，调用pack()让窗口按面板的PreferredSize自动调整尺寸，然后显示窗口并启动游戏循环。注意frame.setLocationRelativeTo(null)让窗口居中显示，这也是课程展示时的一个加分项。

4.2 Swing窗体的最小骨架：JPanel与paintComponent

游戏界面本质上是一个画布，Swing里对应的就是JPanel。重写paintComponent方法，在画布上绘制游戏元素，这是Swing游戏开发的通用做法。一个能跑的GamePanel骨架如下，以“接苹果下落”的玩法为例，可以看到画布绘制和游戏状态的关系。

package com.course.snake; import javax.swing.*; import java.awt.*; import java.awt.event.*; public class GamePanel extends JPanel implements ActionListener, KeyListener { private static final int PANEL_W = 480; private static final int PANEL_H = 640; private int paddleX = 200; private int appleX = 200; private int appleY = 0; private int score = 0; private boolean running = false; private Timer timer; public GamePanel() { setPreferredSize(new Dimension(PANEL_W, PANEL_H)); setBackground(new Color(0x2C3E50)); setFocusable(true); addKeyListener(this); timer = new Timer(30, this); } public void start() { running = true; timer.start(); } @Override protected void paintComponent(Graphics g) { super.paintComponent(g); // 画挡板 g.setColor(Color.WHITE); g.fillRect(paddleX, PANEL_H - 40, 80, 12); // 画苹果 g.setColor(Color.RED); g.fillOval(appleX, appleY, 20, 20); // 画分数 g.setColor(Color.WHITE); g.drawString("Score: " + score, 10, 20); } @Override public void actionPerformed(ActionEvent e) { if (!running) return; appleY += 6; // 碰撞检测：挡板与苹果的位置重叠判定 Rectangle paddleRect = new Rectangle(paddleX, PANEL_H - 40, 80, 12); Rectangle appleRect = new Rectangle(appleX, appleY, 20, 20); if (paddleRect.intersects(appleRect)) { score += 10; appleX = (int)(Math.random() * (PANEL_W - 20)); appleY = 0; } // 苹果落到屏幕底部则结束 if (appleY > PANEL_H) { running = false; timer.stop(); } repaint(); } @Override public void keyPressed(KeyEvent e) { int key = e.getKeyCode(); if (key == KeyEvent.VK_LEFT) { paddleX = Math.max(0, paddleX - 20); } else if (key == KeyEvent.VK_RIGHT) { paddleX = Math.min(PANEL_W - 80, paddleX + 20); } } @Override public void keyReleased(KeyEvent e) {} @Override public void keyTyped(KeyEvent e) {} }

这里的关键逻辑要展开说。javax.swing.Timer和Thread.sleep的区别在于，Swing的Timer把事件回调放到了事件调度线程（EDT）里，不会和界面绘制抢资源，所以游戏循环用的是它。new Timer(30, this)里的30是定时器间隔，单位毫秒，30毫秒约等于每秒33帧，这是动作类小游戏比较顺滑的配置。如果游戏简单，调到50毫秒也没问题，但低于16毫秒就是徒增CPU消耗。Rectangle.intersects()是Java自带的矩形碰撞检测，不用自己写多组坐标判定。焦点问题是Swing键盘监听最常见的一个坑，所以setFocusable(true)必须写在构造器里，否则按键盘没反应。

4.3 键盘输入、移动逻辑与分数：三个最常改的逻辑点

小游戏的核心逻辑无外乎三块：输入控制、移动规则、分数结束判定。输入控制里容易犯的错是用KeyListener配合JFrame的焦点，导致切出窗口再点回来就没反应了，这个问题用setFocusable(true)和requestFocusInWindow()可以缓解，但彻底解决要换InputMap和ActionMap，课程设计一般不需要。

移动逻辑建议是“先算后画”，也就是在actionPerformed里先改变游戏对象的状态，再调用repaint()让paintComponent重绘，不要把移动计算写到绘制方法里。绘制方法里只负责根据当前状态画图，不修改状态，这是所有游戏开发里值得长期坚持的习惯。

分数模块单独抽一个ScoreManager类出来会更整洁，它内部至少包含addScore(int)、save()、load()三个方法。存储用最简单的文本文件即可，把最高分写成字符串存到用户目录，而不是项目目录。原因很实际：项目目录在打包成jar后变得不可写，而用户目录（比如Windows的C:\Users\用户名）永远可写。这个选择背后就是踩过相对路径的坑。

5. 复现与常见问题排查：JDK版本、图片路径、打包与黑匣子报错

5.1 javac编译报“非法字符”或中文乱码：编码问题

现象：在Windows上用javac编译带中文注释的源码，报错误: 非法字符: '\ufeff'，或者游戏运行后界面上中文全是乱码。原因：源码文件的编码是UTF-8带BOM，或者编译器默认使用了GBK。解决方案：所有源码用UTF-8保存，编译时显式指定编码，在IDE里也把项目编码设为UTF-8。命令是：

javac -encoding UTF-8 src/com/course/snake/*.java -d out

顺带说明一个更隐蔽的情况：在IDEA里写代码时中文显示正常，但用命令行编译就乱码，几乎都是编译器默认编码和文件编码不一致导致的。养成在编译命令里写-encoding UTF-8的习惯，比去改系统区域设置更省事。

5.2 图片加载在IDE里正常、打包成jar后空白

现象：代码里写new ImageIcon("images/bg.png")，在IDE里运行正常，导出jar后双击运行，背景没了，或直接抛NullPointerException。原因：images/bg.png是相对路径，jar包启动后的当前工作目录不一定是jar所在目录，相对路径就会失效。解决方案：把图片作为资源放进jar包，用类加载器读取：

ImageIcon icon = new ImageIcon(getClass().getResource("/images/bg.png"));

注意/images/开头的路径代表classpath根目录，资源要放在src/main/resources/images/下（Maven结构），或直接把图片和类一起放进源码目录里。排查技巧：打包后先用jar tf 你的包名.jar查看jar里面的文件列表，确认图片有没有被包含进去。很多人漏了这一步，最后只能把图片放在jar外面，显得很不专业。

5.3 高分记录写不进文件：当前目录的玄学

现象：代码里写new File("score.txt")，在IDE里跑能保存最高分，打成jar双击就不保存，也没有报错。原因：刚才说过，相对路径是相对于“进程启动时的工作目录”，双击jar启动时，工作目录是你双击的那个文件夹。解决方案：存到用户目录：

Path scorePath = Paths.get(System.getProperty("user.home"), "snake_score.txt"); Files.writeString(scorePath, String.valueOf(score), StandardCharsets.UTF_8);

System.getProperty("user.home")在任何操作系统上都能拿到对应用户的目录。类似的思路还有getProperty("user.dir")，但它返回的是工作目录，不是jar的位置，别搞混。

5.4 双击jar没反应：黑匣子问题

现象：在IDE里运行正常，导出可执行jar后双击完全没反应。原因可能性很多，但最常见的有两个：MANIFEST.MF里没有写Main-Class，或者JDK版本不一致。解决方案是先在命令行里跑一次看报错：

java -jar snake.jar

如果提示“no main manifest attribute”，在Maven的pom里配maven-jar-plugin指定mainClass；如果是“UnsupportedClassVersionError”，说明jar是你高版本JDK编译的，对方的JDK版本更旧，需要在编译时加--release 8或--release 11参数。这个报错是黑匣子，命令行的输出是唯一能信的证据，比到处找问题有用得多。

5.5 交付前请对一遍类图与代码：概念和实现别打架

现象：答辩时老师问“你这个UML类图里Snake类的move()返回void，为什么代码里move()返回boolean？”——答不上来。原因：代码写到一半改了逻辑，类图没有同步更新，最后交上去的design.pdf和源码对不上。解决方案：交付前花二十分钟把类图与代码逐一对照一遍。检查每个类名、方法名、返回类型、方法参数和大致的类关系。我这里有一个现实的教训：同学交上去的UML类图画的还是Callable接口，但代码里用的是Runnable，答辩时老师一眼看穿，整个设计的可信度就打了折扣。所以UML图不是装饰品，它是你设计过程的证据。不用改到外貌完全一致，但核心类、核心方法签名必须与代码一致。

6. 别急着交付：用一份验收清单把项目升级成“拿得出手”

6.1 五个检查点，每个三分钟

在压缩并上交之前，按下面的检查表过一遍是很有必要的。每个检查点代表一类最常被扣分的问题。

6.2 若想让这份作业再往前走一步：三个可投入的方向

如果你做完基础功能后还有时间，推荐三个方向，按性价比排序。第一是接入音效，可以给吃到食物和游戏结束各加一个AudioClip播放的提示音，注意关闭循环播放；第二是做一个简单的开始菜单界面，状态模式在Swing里可以把“菜单状态”和“游戏状态”各写一个Panel，切换比在同一个Panel里写if分支清晰很多；第三是把移动逻辑从“按一下动一格”改成“按住持续移动”，这个涉及键盘按下的监听和定时器的配合，真正能区分出你有没有理解事件驱动。

做完这些以后，把你查“java排序”“java面试题”时积累的零碎知识沉淀到你自己项目的代码注释里，你会发现这类作业最大的收获，是让你完整走了一遍“设计、编码、文档、打包、交付”的链路。我第一份Java课设因为README里忘记写JDK版本，让隔壁同学卡在编译上卡了一个小时，从那以后每个项目我都先写README再写代码，也算是血泪经验换来的习惯。希望帮到你。

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