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、通用多线程和联网服务尚未覆盖。

Related MCP server: workspace-mcp

环境要求

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

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

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

以下命令在 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，可指定安装目录后重试，例如：

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

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

导入自己的游戏

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

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，避免覆盖证据。

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

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

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

键盘与存档

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

整理便携运行目录

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

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。自行整理的游戏包包含输入游戏资源；本仓库的 MIT 许可不授予这些游戏内容的分发权。

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

验证移植结果

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

自动回归

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

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

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

原版画面对照

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，内容例如：

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

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

声音检查

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

# 原创测试音符：检查实际输出、音量、停止和循环，会播放声音
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 的客户端调用：

{
  "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 工作流程。

常见问题

生成 EXE 后启动就退出？

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

没有声音？

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

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

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

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

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

项目结构

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

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

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