中国象棋（xiangqi）

一个用 JavaFX 框架编写的中国象棋游戏 for SUSTech CS109 Final Project (2025 Fall)

项目概述

1. 框架：JavaFX，使用 Gradle 进行项目管理与构建。

2. 数据存储：SQLite-JDBC，用于用户账户、对局历史和存档管理。

3. 人机对战：简单模式使用 Minimax + Alpha-Beta 剪枝，困难模式接入 Pikafish 引擎，实现不同难度等级。

4. 网络对战：使用 DatagramSocket 实现简单的局域网对战协议。

5. 棋谱系统：核心使用中国象棋的标准棋谱格式（PGN-ICCS，见这里），支持导入/导出，以及对局中实时中文棋谱翻译显示。

6. 其他：

• 不同模式：单人对战，人机对战（简单、困难），联机对战
• 多账户/游客登录，支持实时读档存档及预览，实时导入导出残局，棋谱实时显示
• 暂停，悔棋，认输，和棋，重新开始，下一步提示，整局逐步回放，绝杀（困毙）检测
• 落子高亮，落子推荐，移子提示，移子动画，音效（吃子或将军提示）
• 丝滑的UI，自适应窗口缩放，不同主题切换，背景音乐

项目结构图

架构摘要

核心游戏逻辑

• Analyzer: 分析棋局，给出推荐行棋，实现人机对战。
• Board: 表示棋盘的类，保存棋盘状态（对局无关），仅包含棋子布局。
• BoardRenderer: 负责画棋盘和棋子，实现动画效果。
• GameService: 游戏对局的逻辑核心，处理各种控制逻辑，例如重新开始、尝试移动、导入导出、保存退出等。
• MainApp: JavaFX 应用程序的入口，启动数据库和启动登录窗口。
• Move: 表示一次移动，包含起始位置、目标位置、是否吃子的信息。
• MoveHistory: 记录一局游戏的所有移动步骤，支持悔棋和遍历回放功能。
• MoveValidator: 静态工具类，移动合法性检验。
• Piece: 棋子类，包含了棋子的各种属性。（并没有子类棋子继承，通过枚举类型区分不同棋子）

数据处理

• GameRecord: 一局游戏的完整记录，规范了数据格式。包含双方玩家信息、对局时间、结果和每一步棋的记录等。
• UserService: 提供用户相关的数据库接口，处理用户登录、注册、数据持久化等功能。
• Utils: 静态工具类，提供各种辅助功能，例如存档的数据库接口等。

JavaFX 控制器类，可以使用 @FXML 注解调用和操作控件，监听事件。

• BoardController: 负责游戏主界面的交互逻辑。比较复杂，还涉及网络对战的处理。
• LoginController: 负责登录界面的交互逻辑。
• SaveView: 负责存档界面的交互逻辑。

其他

• ThemeManager: 多主题管理器，注册 Scene，动态切换不同的 CSS 主题文件。
• MusicPlayer: 音效播放器，播放各种音效文件。

Git 历史留念

How to Run (for Developers)

1. Java 21 is recommended.

2. Clone the repository

3. Use Gradle to build and run the project:

   # To only build, run:
   ./gradlew build
   # To launch the application, run:
   ./gradlew run

   For Windows, use .\gradlew.bat instead of ./gradlew.

4. Better use Scene Builder to open and edit FXML files.