XT the Dungeoner (唐小天勇闯地下城)

一个基于 JavaFX + ECS 架构 + Python 混合开发的 2D Roguelike 动作游戏，致敬经典《以撒的结合》。

📖 项目简介 (Introduction)

XT the Dungeoner 是一个探索性的游戏开发项目，旨在构建一个高性能、易扩展的 Roguelike 游戏引擎。与传统的游戏开发不同，本项目摒弃了成熟的商业引擎（如 Unity, Godot），完全基于 JavaFX 进行图形渲染，并采用 ECS (Entity Component System) 架构来管理复杂的游戏逻辑。

此外，项目还探索了 多语言混合编程 (Polyglot Programming)，利用 Python 强大的生态来处理程序化地图生成 (PCG) 和复杂的概率计算，通过数据驱动的方式与 Java 核心引擎交互。

✨ 核心特色 (Features)

• 高性能 ECS 引擎: 自研 ECS 框架，实现实体、组件、系统的彻底解耦，支持成百上千个游戏实体的实时运算。
• 程序化地牢生成: 结合受限随机游走算法与模板匹配技术，每次游玩都会生成完全不同的地牢结构。
• 以撒式战斗体验: 实现了经典的双摇杆射击、子弹动量继承、基于分离轴定理 (SAT) 的精准碰撞检测。
• 丰富的道具系统: 支持被动道具叠加、主动道具使用，以及多种子弹变体（追踪、反弹、分裂等）。
• 混合架构: Java 处理核心实时循环 (60 FPS)，Python 处理离线/异步的复杂逻辑生成。

🛠 技术架构 (Technical Architecture)

本项目采用分层架构设计：

• 表现层 (Presentation): 使用 JavaFX Canvas API 进行高性能 2D 绘图。
• 逻辑层 (Logic): 纯 ECS 架构。
  • Entity: 仅作为整数 ID 存在。
  • Component: 纯数据容器 (如 PositionComponent, VelocityComponent)。
  • System: 纯业务逻辑 (如 MovementSystem, CollisionSystem, RenderSystem)。
• 生成层 (Generation): Python 脚本负责生成地图拓扑结构和房间布局数据。
• 数据层 (Data): JSON 作为核心数据交换格式。

详细架构说明请参考：docs/architecture/2025-12-31_系统架构详解.md

🚀 快速开始 (Quick Start)

1. 环境要求 (Prerequisites)

在开始之前，请确保您的开发环境满足以下要求：

• Java Development Kit (JDK): 21 或更高版本。
• Maven: 3.9 或更高版本。
• Python: 3.10 或更高版本 (用于地图生成脚本)。

2. 安装 Python 依赖

游戏开始时需要调用 Python 脚本生成地图数据，因此首次运行前请安装必要的 Python 库：

pip install -r src/scripts/requirements.txt

3. 构建与运行

在项目根目录下，使用 Maven 启动游戏：

mvn javafx:run

或者在 IntelliJ IDEA / Eclipse 中：

1. 导入 Maven 项目。
2. 找到 src/main/java/com/xt/dungeoner/MainApp.java。
3. 右键点击运行 MainApp.main()。

🎮 操作指南 (Controls)

• 移动: W, A, S, D
• 射击: ↑, ↓, ←, → (方向键)
• 使用主动道具: 1, 2, 3, 4, 5, 6 (对应道具槽位)

📂 目录结构 (Directory Structure)

xt-the-dungeoner/
├── docs/                    # 项目文档 (核心)
│   ├── architecture/        # 架构设计文档
│   ├── design/              # 游戏设计说明书
│   └── ...
├── src/
│   ├── main/
│   │   ├── java/com/xt/dungeoner/
│   │   │   ├── components/  # ECS 组件 (Components)
│   │   │   ├── systems/     # ECS 系统 (Systems)
│   │   │   ├── ecs/         # ECS 核心引擎实现
│   │   │   ├── game/        # 游戏管理器与逻辑
│   │   │   ├── ui/          # JavaFX 界面视图
│   │   │   └── MainApp.java # 程序入口
│   │   └── resources/       # 游戏资源 (图片、音效、字体)
│   └── scripts/             # Python 地图生成脚本
├── pom.xml                  # Maven 构建配置
└── README.md                # 项目说明

📚 文档索引 (Documentation)

为了更好地理解本项目，请务必阅读 docs/ 目录下的文档：

1. 00_项目概览: 项目愿景与分工。
2. 01_架构设计: (必读) 深入理解 ECS 与系统交互。
3. 02_开发工作流: Git 规范与环境配置。
4. 03_资源指南: 资源加载与管理。
5. 04_代码规范: 编码风格指南。
6. 游戏设计说明书: 详细的游戏玩法与机制设计。

📦 打包与发布 (Build & Release)

本项目采用 Java + Python 混合架构，为了让最终用户在没有安装 Python 的电脑上也能运行游戏，我们采用内置 Python 环境 (Embedded Python) 的方案进行打包。

1. 打包原理

• Java 部分: 使用 JDK 自带的 jpackage 工具，将游戏代码与精简版 Java 运行时 (JRE) 打包在一起，生成独立的 .exe 可执行文件。
• Python 部分: 将 Python Windows Embeddable Package 直接放入发布包中。
• 环境切换: 游戏内的 PythonEnvironment 类会自动识别运行环境：
  • 开发模式: 当检测不到内置 Python 时，自动调用系统环境变量中的 python 命令。
  • 发布模式: 优先使用包内的 python_embed/python.exe，实现零依赖运行。

2. 打包步骤

第一步：准备 Python 环境 (仅首次需要)

由于嵌入式 Python 包较大，不包含在 Git 仓库中，请手动准备：

1. 访问 Python 官网 下载 Windows embeddable package (64-bit) (推荐 3.10+)。
2. 在项目根目录新建文件夹 python_embed。
3. 将下载的压缩包解压到 python_embed/ 中（确保 python.exe 在该目录下）。
4. 关键修正: 用记事本打开 python_embed/python3xx._pth 文件，找到最后一行 #import site，删除开头的 # 号。这能确保 Python 正确加载模块。

第二步：运行一键打包脚本

在项目根目录打开 PowerShell，运行：

.\package_release.ps1

该脚本会自动执行 Maven 构建、jpackage 打包以及 Python 环境的注入。

第三步：获取发布包

构建成功后，生成的文件位于 release/XT-Dungeoner/ 目录。 您可以直接压缩该文件夹进行分发，用户双击 XT-Dungeoner.exe 即可直接游玩。

📄 版权说明 (License)

本项目暂未设置开源许可证 (No License)。保留所有权利。 仅供学习与技术交流使用。

---

Generated by XT-the-Dungeoner Team | Happy Coding!