# J2ME PC Lab

将 Java ME 按键机游戏移植到 Windows 原生程序的开发框架，提供字节码到 C 的静态翻译、手机 API 兼容层、原版对照运行和 Agent 工具接口。

适合想保存、研究或移植自己持有的 J2ME 游戏的开发者，也适合让编程 Agent 在同一套构建和验证工具上持续修复兼容问题。

**当前为早期版本，支持 Windows x64 开发环境。生成的游戏无需 Java 或模拟器，但新游戏可能需要补充兼容实现。** 仓库自带原创 MicroQuest 测试游戏源码，不附带商业游戏 JAR、资源或移植成品。

## 能做什么

- 读取 MIDlet 配置，清点类、方法、外部 API 和资源，记录输入 JAR 的 SHA256。
- 将 `.class` 中的 JVM 字节码翻译为 C，通过 GCC 编译成原生 EXE。
- 为游戏提供绘图、键盘、字符串、数据流、RMS 存档和 MIDI、基础 WAV 播放等兼容实现。
- 运行原始 JAR 与原生程序，保存输入、画面、日志和独立存档，辅助定位差异。
- 通过 CLI 或 MCP 向 Agent 提供方法上下文、构建、运行、对比和源码补丁工具。

适用输入是 **Java ME 的 `.jar` 游戏**。Symbian `.sis/.sisx` 原生游戏不属于当前支持范围。完整厂商扩展、3D、通用多线程和联网服务尚未覆盖。

## 环境要求

| 依赖 | 要求 |
|---|---|
| 系统 | Windows x64，PowerShell |
| Python | 3.8+；建议在虚拟环境中安装依赖 |
| JDK | 11+，推荐 JDK 17；需要 `javac` 和 `java` |
| Git | 用于克隆仓库 |
| 网络 | 首次下载构建工具时需要访问 GitHub |

`scripts/bootstrap.py` 会把固定版本的 GCC、SDL2、BDWGC、FreeJ2ME-plus 和 CFR 下载到本地 `tools/`，并校验下载文件的 SHA256，不修改系统 PATH。版本与下载地址见 [dependencies.lock.json](dependencies.lock.json)。

JDK 用于构建测试样本、生成字体和运行原版参考程序；生成的原生游戏在运行时不依赖 JDK。框架本身不需要模型 API Key；使用 MCP 时由你选择的 Agent 客户端提供模型。

## 快速开始：先运行自带样本

以下命令在 PowerShell 中执行：

```powershell
git clone https://github.com/Disc13/j2me-pc-lab.git
cd j2me-pc-lab

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -X utf8 scripts/bootstrap.py

.\.venv\Scripts\python.exe -X utf8 scripts/make_fixture.py
.\.venv\Scripts\python.exe -X utf8 lab.py import fixtures/microquest/microquest.jar --name microquest
.\.venv\Scripts\python.exe -X utf8 lab.py build microquest
.\.venv\Scripts\python.exe -X utf8 lab.py run microquest --name first-run --seconds 30 --visible
```

成功后会出现 MicroQuest 窗口。用方向键左右移动，Enter 保存位置；本次运行在约 30 秒后自动结束。生成的程序位于 `projects/microquest/build/microquest.exe`，记录位于 `projects/microquest/runs/first-run/`。

后文使用 `python` 简写。没有激活虚拟环境时，请继续替换为 `.\.venv\Scripts\python.exe`。

若找不到 JDK，可指定安装目录后重试，例如：

```powershell
$env:J2ME_LAB_JAVA_HOME = 'C:\Program Files\Java\jdk-17'
```

路径应指向你实际的 JDK 目录，目录下应存在 `bin\javac.exe` 和 `bin\java.exe`。

## 导入自己的游戏

准备自己有权使用的 JAR，填写游戏实际分辨率和一个英文项目名：

```powershell
python -X utf8 lab.py inspect 'D:\Games\my-game.jar'
python -X utf8 lab.py import 'D:\Games\my-game.jar' --name mygame --width 240 --height 320
python -X utf8 lab.py build mygame
python -X utf8 lab.py run mygame --name opening-01 --seconds 60 --visible
python -X utf8 lab.py status mygame
python -X utf8 lab.py dashboard mygame
```

打开 `projects/mygame/dashboard.html` 查看项目概况。构建报错时先看 `projects/mygame/build/pipeline.log` 和 `build.log`；生成失败、缺失符号或运行差异通常需要修改编译器或兼容层。报告里的未实现 API 清单是排查线索，不是兼容率。

同一项目固定对应输入 JAR 的哈希。换游戏版本时请使用新项目名。运行名称也应唯一，保留旧记录，例如 `opening-02`，避免覆盖证据。

需要不限时的交互运行时，在仓库根目录执行：

```powershell
.\projects\mygame\build\mygame.exe projects/mygame/assets 2
```

最后的 `2` 是窗口放大倍数。直接双击 `build/` 下的 EXE 时，其默认资源目录不存在，请使用上述带资源路径的命令，或按下文整理便携目录。

### 键盘与存档

| PC 键盘 | 手机按键 |
|---|---|
| 方向键 | 方向键，由游戏决定动作 |
| Enter、空格 | 确认 / 5 |
| Q、W | 左软键、右软键 |
| 数字 0–9 | 手机数字键 |
| Esc、关闭窗口 | 退出 |

通过 `lab.py run` 运行时，每次实验有独立的 `runs/<名称>/rms/`。直接运行 EXE 时，存档默认写入当前工作目录的 `saves/`；便携目录中双击 EXE 会使用该目录内的 `saves/`。

### 整理便携运行目录

把以下内容放在同一个文件夹中，即可双击 EXE 运行：

```text
mygame/
├── mygame.exe       # projects/mygame/build/mygame.exe
├── SDL2.dll         # projects/mygame/build/SDL2.dll
├── assets/          # 完整复制 projects/mygame/assets/，包含生成的 _lab/ 字体
└── licenses/        # 随程序保留依赖的许可和声明
```

请保留框架、SDL2、BDWGC 和 TinyMidiLoader 等组件的许可声明，具体来源见 [THIRD_PARTY.md](THIRD_PARTY.md)。自行整理的游戏包包含输入游戏资源；本仓库的 MIT 许可不授予这些游戏内容的分发权。

`scripts/package_delivery.py` 是本地《武当七侠》实验使用的专用打包脚本，依赖未随仓库提供的项目，不是通用打包入口。

## 验证移植结果

构建成功只代表生成和链接成功。运行记录是局部证据，仍需要检查具体功能和游戏场景。

### 自动回归

完成 MicroQuest 的导入和构建后执行：

```powershell
python -X utf8 -m unittest discover -s tests -v
```

当前测试覆盖编译语义、空引用异常、RMS 存取与重启、逻辑按键、项目路径、任务领取、MCP 协议和静音 MIDI 生命周期。

### 原版画面对照

```powershell
python -X utf8 scripts/reference_run.py projects/mygame/input.jar projects/mygame/runs/reference-01 --seconds 30
python -X utf8 lab.py run mygame --name native-01 --seconds 30
python -X utf8 lab.py compare projects/mygame/runs/reference-01 projects/mygame/runs/native-01 --out projects/mygame/comparison.json
```

参考端使用 FreeJ2ME-plus，当前参考运行器按 240×320 配置。它提供模拟器基准，尚未对照原手机硬件。

两端支持逻辑按键 JSON。把文件保存为 `projects/mygame/opening.json`，内容例如：

```json
[
  {"t_ms": 5000, "key": "FIRE", "action": "tap"},
  {"t_ms": 8000, "key": "SOFT_LEFT", "action": "tap"}
]
```

原生端添加 `--input opening.json`；参考端添加 `--input projects/mygame/opening.json`。双方会转换为各自的按键编号。运行时钟和随机种子尚未统一，需要人工核对是否进入同一状态；相同画面的数量不能证明整款游戏等价。

### 声音检查

默认无界面运行会静音。静音测试无法确认系统真的输出了声音，可单独执行：

```powershell
# 原创测试音符：检查实际输出、音量、停止和循环，会播放声音
python -X utf8 scripts/audio_check.py --audible

# 加载已导入项目中的 MIDI，每首抽查开头约 2.5 秒
python -X utf8 scripts/audio_check.py --audible --project mygame

# 交互运行游戏，并记录 MIDI 事件
python -X utf8 scripts/native_run.py projects/mygame/runs/audio-01 --project mygame --seconds 30 --visible --audio
```

实际输出检查通过 WASAPI 回环读取峰值，只保留数值，不保存录音。完整曲目、原机音色、场景触发和游戏是否还有其他音效，需要另行核对。当前有声检查没有接入强制打包门槛。

## 在 Agent 客户端中使用

框架提供 MCP stdio 服务，供支持 MCP 的客户端调用：

```json
{
  "mcpServers": {
    "j2me-pc-lab": {
      "command": "D:/Dev/j2me-pc-lab/.venv/Scripts/python.exe",
      "args": ["-X", "utf8", "D:/Dev/j2me-pc-lab/lab.py", "mcp"]
    }
  }
}
```

将两个路径替换为实际克隆目录。客户端配置格式可能不同，上面展示的是常见的 `mcpServers` 结构。

可用工具包括项目清单、方法上下文、任务领取与记录、构建、运行、画面对比，以及带文件哈希校验和备份的源码补丁。Agent 负责选择场景、分析问题和验证修改；框架没有内置自动完成整款移植的模型循环。详细流程见 [Agent 工作流程](docs/AGENT_WORKFLOW.md)。

## 常见问题

**生成 EXE 后启动就退出？**

从 PowerShell 运行并查看输出。先确认资源路径，尤其 `assets/_lab/` 字体是否完整；再看对应运行目录的 `stderr.log`。

**没有声音？**

先确认运行方式没有设置 `LAB_MUTE=1`，并检查游戏自己的音量选项。运行上述有声测试确认 Windows MIDI 输出。已有 MIDI 与基础 WAV 播放实现；上述自动音频检查针对 MIDI，WAV 场景及其他格式需要另行验证。

**新游戏编译失败，是否能直接换一个模拟器内核解决？**

这里生成的是静态编译的原生程序。新游戏的问题通常需要定位到字节码翻译、对象与异常语义、手机 API 或设备差异；原版模拟器用于观察基准行为。

**支持 Linux、macOS 或 Symbian 原生游戏吗？**

当前构建链、主机和音频后端以 Windows x64 为目标。其他平台以及 Symbian 原生格式需要额外开发。

## 项目结构

```text
framework/compiler/   字节码解析和 C 代码生成
framework/native/     手机 API 兼容层与 Windows 主机
j2me_lab/             CLI、MCP、项目和验证记录
scripts/              依赖下载、构建、运行与检查工具
fixtures/microquest/  可自行构建的原创测试游戏
tests/                框架回归测试
docs/                 工作流程与实验记录
projects/             本地导入项目与生成物，忽略提交
tools/                本地工具链，忽略提交
research/、dist/      本地实验输出和交付包，忽略提交
```

编译器和运行库基于 MIT 项目 [doomrpgrecomp](https://github.com/sp00nznet/doomrpgrecomp) 改造。FreeJ2ME-plus 用于原版参考运行和构建时字体生成。方法上下文与对照验证的组织方式参考了 decomp.wtf 一类工程的思路，本仓库是独立的 J2ME 移植原型。

框架与原创样本采用 [MIT 许可](LICENSE)，第三方组件按各自许可使用，见 [THIRD_PARTY.md](THIRD_PARTY.md)。已有实验的范围与未解决问题见 [实验记录](docs/RESEARCH.md)。