JigsawPuzzles

一个基于 Java Swing 的拼图游戏项目，包含用户登录注册、动态主题图片、难度切换、进度存档与读取等完整流程。

项目定位

本项目聚焦两个目标：

• 提供完整可玩的桌面拼图体验（交互、存档、主题切换）
• 展示清晰的业务逻辑设计（可解性判断、状态流转、数据持久化）

功能概览

• 难度等级：2x2 / 3x3 / 4x4 / 5x5
• 主题类型：动物、美女、运动、人物、Pokemon
• 操作方式：键盘方向键、鼠标点击相邻块
• 用户系统：注册、登录、验证码、密码 MD5 存储
• 存档系统：按用户名保存与恢复游戏状态

核心逻辑（算法与数据流）

1) 棋盘状态建模

拼图状态由以下核心数据组成：

• gridSize：网格尺寸（2/3/4/5）
• board：二维棋盘数组，0 表示空白块
• emptyX/emptyY：空白块坐标
• stepCount：当前步数

这样建模的好处是：

• 所有移动规则都围绕“空白块坐标 + 棋盘值交换”实现
• UI 层只负责渲染 board，不直接处理业务细节

2) 随机开局与可解性保障

拼图并不是“随便打乱”就能玩。核心流程：

1. 初始化数组 [0 ... n-1]
2. 使用 Fisher-Yates 洗牌算法生成随机序列
3. 转为二维棋盘并记录空白块位置
4. 通过“逆序数规则”判断是否可解
5. 若不可解则重新生成，直到可解

关键点说明：

• 奇数阶棋盘：逆序数为偶数才可解
• 偶数阶棋盘：逆序数 + 空白块自底向上行号 为奇数才可解

这一步保证玩家不会遇到“理论上无解”的死局。

3) 移动规则（键盘/鼠标）

鼠标点击

• 仅当点击块与空白块“曼哈顿距离为 1”时允许移动
• 实质操作：交换点击块与空白块
• 成功后步数 +1

键盘方向键

• 按键映射为空白块移动目标坐标
• 先做边界判断（越界则不移动）
• 合法时交换并更新空白块坐标

统一规则：所有可移动行为最终都转成“交换空白块与目标块”。

4) 胜利判定

目标状态是按行递增，最后一个格子为 0：

1  2  3  ...
...      ...
n-1 0

每次移动后进行判定：

• 任意位置不匹配目标值 -> 未完成
• 全部匹配 -> 游戏胜利

5) 主题图片加载与缓存

图片资源按以下规则组织：

image/<theme>/<themeN>/<grid>x<grid>/
  ├── 1.jpg ... k.jpg
  └── all.jpg

加载流程：

1. 扫描主题目录，得到可用图片编号列表
2. 每次切换主题时按顺序取下一个编号（用完后重新打乱）
3. 根据当前难度拼接路径并加载分块图
4. 缺失图片时使用默认占位图，避免界面崩溃

6) 存档与读档数据流

保存流程

当前局面 -> 组装 GameSave -> 序列化为 JSON -> 按用户名写文件

存档字段包含：

• 用户名
• 网格大小
• 棋盘状态
• 空白块位置
• 当前步数
• 当前主题路径和图片编号
• 保存时间

读取流程

按用户名读取 JSON -> 反序列化 GameSave -> 恢复局面与主题 -> 刷新 UI

7) 登录与注册校验流程

登录校验顺序

1. 用户名非空
2. 密码非空
3. 验证码非空
4. 验证码匹配
5. 输入密码做 MD5
6. 与用户数据比对

注册校验

• 用户名格式与长度校验
• 密码长度与复杂度校验
• 两次密码一致性校验
• 用户名唯一性校验
• 通过后写入用户 JSON 数据

关键数据文件

• 用户数据：userinfo.json
• 存档目录：save/{username}.json

示例存档：

{
  "username": "user1",
  "gridSize": 4,
  "puzzleState": [[1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,0]],
  "emptyX": 3,
  "emptyY": 3,
  "stepCount": 152,
  "imagePath": "image/animal/animal",
  "imageNum": 1,
  "saveTime": "2026-01-21 14:30:45"
}

快速开始

环境要求

• JDK 21+
• Maven 3.6+

本地运行

cd Game
mvn clean package
java -jar target/Game-1.0-SNAPSHOT.jar

也可在 IDE 直接运行 Game/src/main/java/App.java。

配置说明

• config.properties：运行模式开关（dev / prod）
• config-dev.properties：开发环境路径
• config-prod.properties：生产环境路径（支持 ${APPDATA}）

路径解析逻辑会兼容从仓库根目录或 Game 子目录启动。

项目结构

Game/
├── src/main/java/
│   ├── controller/
│   ├── model/
│   │   ├── domain/
│   │   ├── service/
│   │   └── repository/
│   │       └── json/
│   ├── ui/
│   └── util/
├── src/test/java/
└── pom.xml

技术栈

• Java 21
• Swing
• Maven
• Hutool 5.8.43
• JUnit 5.10.2

作者

Narylr