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

简介：直接可运行的Java版吃豆人游戏，包含Player玩家控制、Enemy敌人AI、Wall地图墙体、Gold金币收集、Fruit道具水果、Ticker计时器等全部核心类，所有.java源文件和对应.class字节码文件均已打包。项目基于Java SE标准环境开发，不依赖数据库，兼容Eclipse一键导入运行。Image目录存放全部游戏图片素材（如角色、背景、图标），Sound目录集成音效文件（吃豆声、死亡音效、加分提示等），Pac-man.html提供简易网页启动入口，version.ini记录当前版本号。配套完整的Eclipse工程配置文件（.project、.classpath、org.eclipse.jdt.core.prefs），支持开箱即用。代码采用清晰的面向对象设计，各模块职责明确，关键逻辑配有适量中文注释，涵盖Swing图形界面绘制、主游戏循环调度、矩形碰撞检测、方向控制与状态切换等典型游戏开发要素，适合Java初学者理解游戏架构，也便于二次开发或教学演示。

1. 项目概述：一个“能跑、能看、能学”的Java吃豆人教学级工程

我第一次在Eclipse里双击PackmanGame.java运行出那个蓝黄相间的迷宫时，心里其实有点意外——不是因为画面多炫，而是它太“实在”了。没有Maven花哨的依赖管理，没有Spring Boot的自动装配，甚至没用任何第三方游戏引擎，就靠Java SE自带的javax.swing和java.awt，把吃豆人这个经典IP的核心骨架稳稳地立住了。这包东西，不是玩具，也不是Demo，而是一个可触摸、可调试、可拆解的教学实体。你打开Player.java，能看到方向键监听如何映射到角色移动；点进Enemy.java，会发现四个幽灵的AI行为差异不是靠随机数堆出来的，而是用不同状态机（巡逻、追击、惊慌）驱动的；Wall.java里那几行getBounds()调用，就是整个碰撞检测系统的物理基石。它不追求3D渲染或网络对战，但把“一个2D游戏怎么从零搭起”这件事，掰开了、揉碎了、摊在你眼皮底下。关键词里的“吃豆人游戏”“Java源码”“Swing游戏”，在这里不是标签，而是每一个.java文件里跳动的逻辑脉搏。适合谁？如果你刚学完Java基础语法，正卡在“学了类和对象，却不知道它们在真实程序里长什么样”，或者你是带学生做课程设计的老师，需要一个结构干净、无黑盒、能随时打断点讲原理的范例，那这个包就是为你准备的。它不教你如何写百万行商业游戏，但它会手把手告诉你：游戏循环怎么调度帧率、Swing双缓冲怎么防闪烁、矩形碰撞检测为什么比像素级更高效、甚至repaint()背后触发的绘制链路是怎样的。这不是一份“拿来即用”的资源，而是一份“拿来即懂”的说明书。

2. 整体架构与设计思路：为什么用纯Swing，而不是LibGDX或LWJGL？

2.1 核心设计哲学：用最轻量的工具，讲最本质的游戏逻辑

这个工程没选LibGDX，也没碰LWJGL，甚至刻意避开了JavaFX——原因很朴素：教学成本最小化。LibGDX封装太深，新手一进去就被AssetManager、SpriteBatch、Viewport绕晕，搞不清“画一个圆”背后到底发生了什么；LWJGL直通OpenGL，对刚接触图形概念的人简直是天书；JavaFX虽然现代，但其事件模型和CSS样式机制又引入了另一套学习曲线。而Swing，是Java SE自带的、文档最全的、IDE支持最成熟的GUI库。它的JPanel重写paintComponent(Graphics g)方法，就是最直观的“每一帧我来画什么”的入口；它的Timer类，就是最直白的“每隔多少毫秒执行一次”的游戏主循环载体。我试过把Ticker.java里的javax.swing.Timer换成java.util.Timer，结果画面疯狂闪烁——因为后者不在EDT（Event Dispatch Thread）上执行，Swing的绘制线程安全机制直接失效。这个坑，恰恰就是理解“为什么游戏循环必须绑定GUI线程”的最佳案例。所以，这个架构的选择，不是技术保守，而是精准卡位：用Swing的“笨办法”，逼你直面底层逻辑。

2.2 模块职责划分：每个类只做一件事，且这件事必须可验证

翻开源码目录，你会发现所有核心类都遵循一个铁律：单一职责 + 明确边界。Player.java只管三件事：响应键盘输入、更新自身坐标、绘制自己。它不计算碰撞，不判断是否吃到金币，更不管理游戏分数——这些统统交给PackmanGame.java这个“游戏世界总控”来协调。Enemy.java同理，它内部维护一个State枚举（CHASE, SCATTER, FEAR），每个状态对应一套移动算法，但“什么时候切换状态”这个决策权，交给了PackmanGame根据全局时间戳和玩家位置来判定。这种设计，让调试变得极其简单：你想看幽灵AI怎么跑，就在Enemy.move()里打个断点；想查玩家为什么穿墙，就盯死Player.checkCollision()的返回值。Wall.java更是极致，它就是一个纯粹的“不可穿越区域”定义者，只提供getBounds()返回一个Rectangle，连绘制逻辑都剥离到PackmanGame.paintComponent()里统一处理。这种解耦，不是为了炫技，而是为了让初学者能像拆乐高一样，把一个复杂系统拆成几个独立可测试的积木块。你甚至可以单独写个测试类，实例化一个Wall和一个Player，手动调用player.getBounds().intersects(wall.getBounds())，立刻验证碰撞逻辑是否正确——这种即时反馈，是任何框架封装都给不了的教学红利。

2.3 资源组织逻辑：为什么图片和声音要放在Image/Sound目录，而不是jar包内？

看到Image和Sound两个目录，你可能会想：“直接用getClass().getResourceAsStream("/images/player.png")打进jar包不更方便？”但这里有个关键教学点被刻意保留：资源路径的显式管理，是理解Java类路径（Classpath）的第一课。这个工程里，所有资源加载都走的是相对路径，比如ImageIO.read(new File("Image/player.png"))。这意味着，当你把整个工程目录拖进Eclipse，它天然就能找到图片；但如果你打包成jar，就必须确保Image目录和jar同级，或者修改加载逻辑。这个“不方便”，恰恰是故意设置的认知锚点。我带学生做实验时，会让他们先尝试直接运行jar包，必然报FileNotFoundException；然后引导他们去看PackmanGame.java第87行的loadImages()方法，再对比getClass().getResource()的文档，最后亲手把图片复制进jar包根目录并改用流加载——这一套操作下来，对“类路径”“资源定位”“jar包结构”的理解，比背十遍概念都牢。音效同理，Sound目录下的.wav文件用AudioSystem.getAudioInputStream()加载，既避开了MP3版权问题，又保证了Java SE原生支持，零额外依赖。这种“原始”的资源管理方式，牺牲了一点部署便利性，换来的却是对Java基础生态最扎实的掌握。

3. 核心类详解与实操要点：从代码到运行的每一步

3.1 PackmanGame.java：游戏世界的“心脏”与“大脑”

作为整个项目的入口和中枢，PackmanGame.java继承自JPanel，并实现了ActionListener接口。它的核心在于两个循环的协同：渲染循环和逻辑更新循环。渲染循环由Swing的repaint()触发，最终调用paintComponent(Graphics g)进行双缓冲绘制；逻辑更新循环则由Ticker.java提供的javax.swing.Timer驱动，每16毫秒（约60FPS）触发一次actionPerformed()。关键点在于：paintComponent()里只做“画”，不做“算”；所有坐标更新、状态变更、碰撞检测，都在Ticker的actionPerformed()里完成。这种分离，是避免Swing线程阻塞导致界面冻结的黄金法则。例如，在actionPerformed()中，你会看到这样的链条：

player.update(); // 更新玩家坐标
for (Enemy enemy : enemies) {
    enemy.update(player.getX(), player.getY()); // 传入玩家位置供AI决策
}
checkCollisions(); // 统一检测所有碰撞

而paintComponent()里只有：

g.drawImage(background, 0, 0, null);
player.draw(g);
for (Enemy e : enemies) e.draw(g);
for (Gold g : golds) g.draw(g);
// ... 其他绘制

提示：如果你在paintComponent()里调用player.update()，会导致绘制和逻辑混在同一帧，一旦update()耗时稍长（比如加了复杂AI），画面就会卡顿。这是新手最容易踩的坑，务必牢记“绘制归绘制，计算归计算”。

3.2 Player.java：方向控制、移动与碰撞的三位一体

Player类是玩家交互的唯一出口。它的方向控制采用“按键状态缓存”而非“按键事件即时响应”。在keyPressed(KeyEvent e)中，只设置direction = newDirection；真正的移动发生在update()里，根据当前direction计算新坐标。这种设计解决了“按住方向键不放时，角色只走一步”的常见问题。更关键的是移动前的碰撞预判：update()方法里，先计算“如果按这个方向走，下一步坐标会是哪里”，再调用checkWallCollision(nextX, nextY)，只有未碰撞才真正赋值x = nextX; y = nextY。checkWallCollision()的实现极简却高效：遍历所有Wall对象，调用其getBounds().contains(nextX, nextY)。这里有个性能优化点——实际工程中，我们会用四叉树或空间哈希做碰撞粗筛，但在这个教学版本里，直接遍历ArrayList<Wall>，因为地图墙体总数不到50个，O(n)完全够用。Player还负责金币收集逻辑：在update()末尾，检查goldList.contains(new Point(x, y))，命中则移除金币并增加分数。注意，这里的Point是java.awt.Point，它重写了equals()和hashCode()，确保坐标比较准确。

3.3 Enemy.java：四种幽灵的AI状态机实现

四个幽灵（Blinky红、Pinky粉、Inky青、Clyde橙）的差异化行为，是这个工程最体现设计功力的部分。它们共用一个Enemy基类，但通过构造函数注入不同的AIType枚举，从而激活不同的move()算法：
- CHASE模式：Blinky直接追逐玩家坐标；Pinky计算玩家前方两格的位置作为目标；Inky的目标是“玩家位置与Blinky位置向量差的一半”；Clyde则在玩家距离远时追逐，近时逃跑。
- SCATTER模式：各自奔向迷宫四个角落的固定坐标。
- FEAR模式：随机移动，且速度降低。

所有这些逻辑，都封装在move()方法内部，外部PackmanGame只需调用enemy.update(playerX, playerY)，完全不关心具体实现。这种策略模式（Strategy Pattern）的应用，让AI扩展变得极其简单：想加第五种幽灵？只需新增一个AIType枚举值，并在move()的switch语句里补充分支即可。Enemy的绘制也暗藏巧思：它不直接画图片，而是根据当前State动态选择Image数组中的不同帧（如惊慌时画蓝白条纹），实现了状态驱动的视觉反馈。

3.4 Gold.java与Fruit.java：收集物的生命周期管理

金币（Gold）和水果（Fruit）看似简单，实则承载了游戏状态管理的关键逻辑。Gold类非常轻量，几乎就是一个带坐标的POJO，但它的存在意义在于：PackmanGame维护一个ArrayList<Gold>，每次绘制时遍历列表，只画那些isCollected == false的对象；玩家碰撞后，将对应Gold的isCollected设为true，并在下一帧绘制时跳过它。这种“标记-清除”模式，比频繁remove()列表元素更高效，避免了并发修改异常。Fruit则多了计时器属性：它有一个spawnTime（生成时间戳）和lifeTime（存活毫秒数）。PackmanGame在actionPerformed()中检查System.currentTimeMillis() - fruit.spawnTime > fruit.lifeTime，超时则自动设为isCollected = true。这种基于时间戳的状态管理，是游戏开发中处理“临时道具”的标准做法，比用Timer对象逐个管理更省内存。

4. 实操过程与完整运行指南：从导入到调试的全流程

4.1 Eclipse环境配置：三步搞定开箱即用

这个工程的Eclipse兼容性，是经过反复验证的。导入步骤严格遵循标准流程，避免任何“玄学”操作：
1. 解压与目录确认：将下载的压缩包解压到一个不含中文和空格的路径下，例如D:\pacman-project。重点检查解压后根目录是否存在src文件夹（里面应有所有.java文件）、Image和Sound文件夹。
2. Eclipse导入操作：启动Eclipse → File → Import... → 选择General → Existing Projects into Workspace → 点击Next → 在Select root directory中浏览到你解压的pacman-project文件夹 → 勾选出现的项目（通常显示为Packman或类似名称）→ 取消勾选Copy projects into workspace（保持原路径，便于后续找资源）→ 点击Finish。
3. 运行前的最后检查：导入后，展开项目，确认src下有PackmanGame.java等源文件，Image和Sound文件夹已作为普通文件夹出现在项目根目录（不是在src内！）。右键点击PackmanGame.java → Run As → Java Application。如果首次运行报错Exception in thread "main" java.lang.NullPointerException，大概率是Image或Sound路径不对——请回到第1步，确认解压路径绝对干净。

4.2 Pac-man.html的简易启动原理与局限性

Pac-man.html是一个用<applet>标签嵌入Java Applet的古老方案。它之所以存在，是为了演示“如何用网页启动Java桌面应用”，尽管Applet技术已被现代浏览器废弃。其核心代码是：

<applet code="PackmanGame.class" width="800" height="600">
  <param name="archive" value="PackmanGame.jar">
</applet>

但请注意：此HTML文件无法在Chrome/Firefox等现代浏览器中运行，因为它们已彻底移除Java插件支持。它的实际价值在于教学：你可以用appletviewer Pac-man.html命令在命令行中启动它（需JDK环境），观察Applet生命周期（init(), start(), stop(), destroy()）与Swing组件的交互。对于日常开发，我们完全忽略它，直接用Eclipse运行PackmanGame.java即可。这个文件的存在，本身就是一堂关于“技术演进与兼容性”的无声课。

4.3 version.ini与工程元数据：理解Eclipse配置文件的作用

version.ini内容极简：

version=1.0.0
build_date=2023-10-15
author=JavaGameLab

它不参与运行，但教会你一个好习惯：为你的项目添加可读的元信息。而.project和.classpath这两个隐藏文件，则是Eclipse项目的“身份证”。.project定义了项目名称、构建器（org.eclipse.jdt.core.javabuilder）和性质（org.eclipse.jdt.core.javanature）；.classpath则指明了源码路径（<classpathentry kind="src" path="src"/>）、输出路径（<classpathentry kind="output" path="bin"/>）和Java运行时环境（<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>）。当你在其他电脑上导入项目时，Eclipse正是靠读取这两个文件，才能瞬间还原出正确的编译环境。这也是为什么工程包里必须包含它们——没有它们，Eclipse就只能当做一个普通文件夹，无法识别为Java项目。

4.4 音效与图像资源的加载调试技巧

资源加载失败是新手运行失败的头号原因。这里分享三个必试的调试技巧：
1. 路径打印法：在PackmanGame.loadImages()方法开头，加入System.out.println("Current working dir: " + System.getProperty("user.dir"));。运行后，控制台会输出Eclipse当前工作目录（通常是workspace根目录）。对照这个路径，确认Image文件夹是否在其下。如果不是，要么移动Image文件夹，要么修改代码中的路径为绝对路径（仅调试用）。
2. 文件存在性校验：在加载单个图片前，加入File imgFile = new File("Image/player.png"); System.out.println("Player image exists: " + imgFile.exists());。这样能精确定位是哪个文件缺失。
3. 音效格式兼容性：Sound目录下的.wav文件，必须是PCM编码、16位、小端序、单声道或立体声。如果自己替换音效，用Audacity导出时请选择WAV (Microsoft) signed 16-bit PCM。曾有学生用手机录的MP3转WAV，结果AudioSystem.getAudioInputStream()抛出UnsupportedAudioFileException，根源就是编码不匹配。

5. 常见问题与排查技巧实录：那些年我们踩过的坑

5.1 游戏窗口空白/黑屏：90%是双缓冲或绘制顺序问题

现象：运行后窗口弹出，但一片漆黑，或只显示背景色，角色和金币完全不出现。
- 排查步骤1：检查paintComponent()是否被调用
在PackmanGame.paintComponent(Graphics g)第一行加入System.out.println("Painting frame...");。如果控制台没有输出，说明repaint()根本没触发——检查PackmanGame构造函数里是否漏掉了setFocusable(true)和requestFocusInWindow()（键盘输入需要焦点）。
- 排查步骤2：确认双缓冲启用
PackmanGame构造函数中必须有this.setDoubleBuffered(true);。如果没有，注释掉它再运行，画面会出现严重撕裂感，这就是双缓冲失效的典型表现。
- 排查步骤3：绘制顺序与坐标偏移
Graphics的坐标原点(0,0)在窗口左上角。如果player.draw(g)里用了g.drawImage(img, x, y, null)，但x或y是负数，图片就会画到窗口外。在draw()方法里打印System.out.println("Drawing at: " + x + ", " + y);，确认坐标在合理范围（如0~799, 0~599）。

5.2 幽灵穿墙/玩家卡在墙里：碰撞检测逻辑失效

现象：角色能穿过墙壁，或在墙边反复抖动。
- 核心原因：坐标精度与边界计算
Wall.getBounds()返回的Rectangle，其x、y、width、height都是int类型。如果玩家坐标是double（如x += speed * Math.cos(angle)），直接传给contains(int x, int y)会强制截断小数，导致精度丢失。解决方案：在checkWallCollision()中，将玩家坐标四舍五入为整数，或统一用int存储所有坐标。
- 另一个陷阱：墙体坐标系不一致
Wall.java里定义的坐标，是否和Player.java里使用的坐标系一致？比如，Wall的x,y是左上角，而Player的x,y是中心点？如果是，碰撞检测必须用player.getBounds().intersects(wall.getBounds())，而不是简单的wall.contains(player.x, player.y)。检查Player.getBounds()的实现，确保它返回的Rectangle是以玩家中心为基准、正确包含了碰撞半径的矩形。

5.3 音效不播放/报错：Java音频子系统的隐性限制

现象：游戏运行正常，但没有声音，或控制台报LineUnavailableException。
- 根本原因：音频线路被独占
Java的Clip对象需要获取系统音频线路（Line），而Windows系统默认只允许一个应用独占线路。如果你同时开着QQ音乐、网易云，Clip.open()就会失败。解决方案：在SoundPlayer.playSound()方法中，用try-catch捕获LineUnavailableException，并打印友好提示：“音频设备被占用，请关闭其他播放软件”。
- 备用方案：使用SourceDataLine流式播放
对于短音效（如吃豆声），Clip是最佳选择；但对于长背景音乐，SourceDataLine更稳定。本工程虽未采用，但可在SoundPlayer中扩展一个playBackgroundMusic()方法，用AudioInputStream持续读取数据并写入SourceDataLine，实现后台音乐播放。

5.4 Eclipse导入后报红/编译错误：JDK版本与构建路径冲突

现象：src下所有.java文件左侧有红色感叹号，Player.java里@Override标红，提示“Must override a superclass method”。
- 诊断：JDK版本不匹配
右键项目 → Properties → Java Build Path → Libraries → 展开JRE System Library，看版本号。如果显示JRE System Library [jdk-11]，但你的代码用了var关键字（JDK 10+特性），而Eclipse默认用JDK 8编译，就会报错。解决方案：Properties → Java Compiler → 将Compiler compliance level设为11或更高，并勾选Use default compliance settings。
- 终极保险：清理并重建
Project → Clean... → 选择该项目 → OK。Eclipse会强制重新编译所有文件，清除可能的缓存错误。

6. 二次开发与教学扩展建议：让这个工程活起来

6.1 新手友好型扩展：三分钟添加一个新功能

想让学生快速获得成就感？推荐从这三个低门槛扩展入手：
- 添加生命值显示：在PackmanGame.paintComponent()中，g.drawString("Lives: " + lives, 20, 30);，并在Player死亡时lives--。这能立刻让学生理解“游戏状态变量”如何影响UI。
- 实现暂停功能：在PackmanGame中添加boolean isPaused = false;，在keyPressed()中监听空格键，if (e.getKeyCode() == KeyEvent.VK_SPACE) isPaused = !isPaused;，然后在Ticker.actionPerformed()中加if (!isPaused) { updateAll(); }。这引入了“游戏状态机”的初级概念。
- 修改迷宫布局：直接编辑PackmanGame.java里的map[][]二维数组（如果工程用数组定义地图），把1（墙）改成0（空地），立刻生成新关卡。这是理解“数据驱动设计”的最直观方式。

6.2 进阶教学点：从Swing到现代游戏开发的桥梁

这个工程的价值，不仅在于它本身，更在于它是一块跳板。可以引导学生思考：
- Swing的瓶颈在哪？ 当敌人数量从4个增加到40个，paintComponent()里的遍历绘制会明显变慢。这时，自然引出“场景图（Scene Graph）”概念，对比LibGDX的Stage和Actor。
- 碰撞检测的升级路径：当前的O(n)遍历，遇到上千个物体就崩了。可以带学生实现一个简易的“网格分区”：将屏幕划分为10x10的格子，每个物体注册到所在格子，碰撞检测只在相邻格子内进行，复杂度降至O(1)。
- 游戏循环的现代化：javax.swing.Timer精度有限（最低约10ms）。可以演示用System.nanoTime()实现固定时间步长（Fixed Timestep）的主循环，解决不同机器上速度不一致的问题。

6.3 个人经验总结：为什么坚持用“老技术”教“新思维”

在我带过的二十多届学生中，凡是上来就学Unity或Unreal的，往往陷入“拖拽组件-调参-出效果”的舒适区，问“为什么按钮点击后角色会动”，答不上来；而从这个Swing吃豆人起步的，三个月后就能自己写出一个带A寻路的塔防游戏。原因很简单：没有银弹，只有基石*。Swing的“啰嗦”，强迫你直面每一行代码的因果；它的“原始”，让你看清图形渲染、事件分发、线程协作的底层契约。这个工程包里的每一个.java文件，都不是终点，而是你敲开游戏开发大门时，手里那把最趁手的螺丝刀。它不华丽，但拧得紧；它不炫酷，但拆得开。当你某天在IDE里看着Enemy.java里那个switch(state)，突然意识到这不就是状态模式的教科书实现吗？那一刻，你就已经超越了代码本身，开始用设计思维去重构世界了。

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

简介：直接可运行的Java版吃豆人游戏，包含Player玩家控制、Enemy敌人AI、Wall地图墙体、Gold金币收集、Fruit道具水果、Ticker计时器等全部核心类，所有.java源文件和对应.class字节码文件均已打包。项目基于Java SE标准环境开发，不依赖数据库，兼容Eclipse一键导入运行。Image目录存放全部游戏图片素材（如角色、背景、图标），Sound目录集成音效文件（吃豆声、死亡音效、加分提示等），Pac-man.html提供简易网页启动入口，version.ini记录当前版本号。配套完整的Eclipse工程配置文件（.project、.classpath、org.eclipse.jdt.core.prefs），支持开箱即用。代码采用清晰的面向对象设计，各模块职责明确，关键逻辑配有适量中文注释，涵盖Swing图形界面绘制、主游戏循环调度、矩形碰撞检测、方向控制与状态切换等典型游戏开发要素，适合Java初学者理解游戏架构，也便于二次开发或教学演示。

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