p5engine + Starfield Rampart

p5engine 是一个基于 Processing 4 的 2D 游戏引擎框架。
Starfield Rampart（星域防线） 是基于该引擎开发的一款科幻太空塔防游戏，也是引擎的主要展示示例和驱动项目。

---

项目结构

p5engine/
├── src/main/java/shenyf/p5engine/     # 引擎源码（Java）
│   ├── core/                          # P5Engine 核心、配置、窗口管理
│   ├── scene/                         # GameObject / Component / Scene
│   ├── rendering/                     # 渲染、DisplayManager、ImageManager
│   ├── audio/                         # AudioManager（TinySound 后端）
│   ├── ui/                            # UI 框架、Tween、事件系统
│   ├── resource/ppak/                 # PPAK 资源包管理器
│   └── ...
│
├── library/p5engine.jar               # 引擎编译产物
├── examples/
│   ├── TowerDefenseMin2/              # ⭐ Starfield Rampart（主项目）
│   ├── PPakDemo/                      # PPAK 资源包演示
│   ├── ImageLab/                      # 图像处理工具
│   ├── MapEditor/                     # 地图编辑器
│   ├── HelloWorld/                    # 最小示例
│   └── ...
│
├── tools/ppak/                        # PPAK 打包工具（Python）
├── scripts/                           # 构建与发布脚本（PowerShell）
├── docs/                              # 技术文档
└── plans/                             # 开发计划

---

技术栈

层级	技术
运行时	Processing 4.5.2 (P2D / OpenGL)
引擎	p5engine 自研框架（Java 17）
音频	TinySound (OGG/Vorbis)
配置	SnakeYAML 2.2 + JSON
构建	PowerShell 5.1 + Processing CLI
发布	Launch4j + JLink 自定义 JRE
资源	自定义 PPAK 二进制包格式

---

开发工作流

环境要求

• Processing 4.5.2：D:\Processing\Processing.exe
• JDK 17：D:\java\jdk-17.0.10+7
• Python 3：用于 PPAK 打包工具
• PowerShell 5.1+（Windows）

日常开发循环

# 1. 修改引擎 Java 源码后，编译引擎
.\compile-jar.ps1 -NoCopy

# 2. 将新 jar 复制到游戏工程的 code/ 目录（必须！否则运行的是旧版引擎）
Copy-Item library\p5engine.jar examples\TowerDefenseMin2\code\p5engine.jar

# 3. 修改 PDE 后，用 Processing CLI 验证编译
& "D:\Processing\Processing.exe" cli `
    --sketch="E:\projects\kilo\p5engine\examples\TowerDefenseMin2" `
    --build

# 4. 调试运行（15 秒自动收集日志）
.\examples\TowerDefenseMin2\debug_run.ps1

完整发布工作流

# 一键完整发布：编译引擎 → PPAK 打包 → 导出 EXE → JLink 精简 JRE
.\scripts\build-release.ps1 `
    -SketchPath "E:\projects\kilo\p5engine\examples\TowerDefenseMin2" `
    -BuildEngine -UsePpak -Force

# 仅打包配置文件（开发时独立执行）
.\scripts\pack-config.ps1 `
    -SketchPath "E:\projects\kilo\p5engine\examples\TowerDefenseMin2"

发布产物位于 examples/TowerDefenseMin2/output/，包含独立的 .exe（无需预装 Java，约 85 MB）。

---

脚本速查

脚本	用途	典型调用
compile-jar.ps1	编译引擎为 library/p5engine.jar	.\compile-jar.ps1 -NoCopy
scripts/build-release.ps1	完整发布（编译→PPAK→导出→JLink）	见上方完整发布工作流
scripts/pack-config.ps1	将 data/config/ 打包为 config.ppak	.\scripts\pack-config.ps1 -SketchPath <path>
scripts/export_game.ps1	旧版简单导出（PPAK → Processing CLI → dist/）	.\scripts\export_game.ps1 -SketchPath <path>
tools/ppak/ppak_pack.py	PPAK 打包工具	python tools/ppak/ppak_pack.py data/ music/ -o data.ppak
tools/ppak/ppak_ls.py	查看 PPAK 内容	python tools/ppak/ppak_ls.py data.ppak
examples/TowerDefenseMin2/debug_run.ps1	游戏调试运行	直接双击运行

---

相关文档

文档	内容
docs/PPak_Config_Support.md	PPAK Config 支持实现报告
docs/Build_Release_System.md	打包发布系统技术报告
docs/PPAK_INTEGRATION.md	PPAK 整合与 API 文档
docs/Processing_Export_JLink_Guide.md	导出 EXE 与 JLink 精简指南
docs/TowerDefenseMin2_v0.7.0_Mechanics_Refactor.md	v0.7.0 核心机制重构
docs/Tower_Upgrade_Reference.md	6 种塔升级数据参考
docs/Steam_Store_About_This_Game.md	Steam 商店页面文案

---

引擎核心概念（快速参考）

// 初始化
P5Engine engine = P5Engine.create(this, P5Config.defaults());

// GameObject + Component
GameObject player = GameObject.create("Player");
player.addComponent(PlayerController.class);

// 场景
Scene scene = engine.getSceneManager().createScene("Main");
scene.addGameObject(player);

// 每帧
void draw() {
    engine.update();  // 逻辑更新
    engine.render();  // 渲染
}

更多 API 参考 docs/PPAK_INTEGRATION.md 和 examples/ 下的示例代码。

---

规范与约定

所有 Agent 参与本项目前，必须阅读 AGENTS.md。核心规则摘要：

• 计划管理：所有开发计划放入 plans/ 目录，命名格式 {主题}_{8位hash}.plan.md
• 编译验证：修改 Java 源码后必须运行 compile-jar.ps1；修改 PDE 后必须用 Processing CLI build 验证
• 最小修改原则：只改与当前任务直接相关的代码，不顺便格式化无关文件
• 删除权限：绝对禁止自行删除任何文件，除非用户明确说"删除/删掉/approved"
• Git 规范：禁止自动执行任何 git 变更（commit/push/tag 等），只有用户明确授权才可执行

---

License

MIT License