← 返回文档中心
MD 使用文档

小慧 MC 启动器 · Android 预览版

小慧 MC 启动器 · Android 预览版

小慧 MC 启动器 · Android 预览版

在原 XHMCL 桌面版基础上移植的 Android 工程，版本 0.8.11-android.1。 原工程 K:\app dev\xhmcl 没有修改。本工程位于 K:\Android app dev\xhmcl。

当前是可构建的预览版，不是“全部功能已在手机上验证”的正式版。 十个功能页面及对应主要业务代码保留，Windows 专用接口替换为 Android 实现；游戏渲染、OpenJDK 执行和本地开服后端已接入，但尚未完成真机端到端验证。具体进度见 [功能对照](docs/FEATURE-PARITY.md) 和 [验证记录](docs/TESTING.md)。

安装与首次使用

构建产物：dist/XHMCL-Android-0.8.11-preview.apk，debug 签名，用于本地安装测试；不是商店发布包。

  1. 将 APK 复制到 Android 手机，使用系统安装器安装。按系统提示允许该文件来源安装应用。
  2. 设计最低版本 Android 8.0 / API 26；当前包包含 ARM64 和 x86_64 两种架构，不包含 32 位 ARM/x86。
  3. 首次启动完成引导，添加账号，从下载中心创建并安装游戏。Minecraft 正版联机仍需要有游戏授权的微软账号。
  4. Java 8 / 17 / 21 / 25 安装包已经内置，按游戏版本解压所需运行环境。无需把 Windows 的 java.exe 复制到手机。
  5. 首页选择实例及账号再启动；游戏界面提供方向、跳跃、潜行、疾跑、攻击、使用、背包、丢弃、快捷栏、聊天和 ESC 控制，也接入了常用键盘/鼠标事件。
  6. 设置中可切换 GL4ES / NG-GL4ES。不同 GPU、游戏和模组版本兼容性尚待分别验证，不保证所有整合包均可运行。

APK 因内置两种架构、多代 Java 和图形组件而较大。游戏资源仍需联网下载；安装运行时、实例和整合包需要额外可用空间。

数据与文件

  • 数据在应用内部 files/xhmcl，对应实例、服务器、下载、快照、音乐、皮肤等子目录。卸载应用会删除这些数据，重要世界请先导出备份。
  • “导入”使用 Android 系统文件选择器；“打开文件夹”使用内置浏览器；普通文件旁的“导出”可保存到系统选择的位置。
  • 游戏目录选择限定应用可访问的私有目录。桌面盘符路径不能在 Android 上直接复用。
  • 微软令牌使用 Android Keystore 加密。不应把桌面账号令牌或 APK 调试日志直接公开。
  • 游戏和 Java 后台任务分别在 Android 独立进程运行，主启动器不会被 OpenJDK 替换。最多同时运行一个游戏和三个后台 Java 任务。
  • 下载/音乐使用前台服务；服务器使用独立前台服务。系统强制停止、设备重启、后台运行限制仍可能中断任务；本版没有实现被系统杀死后的可靠任务恢复或关机期间定时开服。

功能范围

保留首页、实例管理、游戏下载、下载队列、资源中心、多人游戏、本地开服、工具箱、音乐和设置，以及原有九种语言资源。 账号、皮肤、模组/光影/材质/整合包、Modrinth、Fabric/Quilt/Forge/NeoForge、服务器控制台/自动化/备份、快照恢复、崩溃诊断等代码已迁入并连接 Android 适配层。

不能直接等价迁移的部分：Windows 全局内存清理改为本应用内存回收；桌面 JVM 插件必须改为 Android 可加载的 DEX 插件；自定义 Java 当前仅识别本应用安装过的 Android 运行时；更新服务需要提供 Android APK，桌面安装器不会被当成 Android 更新。 新加的 Android 专属说明/触控按钮目前主要为中文，原有九种语言页面资源保留。

构建

本机已经配置 local.properties 与 .tools/android-sdk。使用 PowerShell：

cd 'K:\Android app dev\xhmcl'
.\scripts\build-android.ps1

换电脑时准备 JDK 17/21、Android SDK（platforms;android-35、build-tools;35.0.0、platform-tools），重新配置 local.properties，然后：

.\scripts\build-android.ps1 -JavaHome 'C:\Path\To\jdk-21'

构建脚本执行 APK 构建、测试 APK 构建、JVM/Robolectric 测试与 Android lint；只有全部成功才更新 dist。 使用已连接并授权调试的 Android 测试设备时，可加 -DeviceTests 运行设备测试。该选项会在设备安装测试应用并解压内置 Java 17。

结构与第三方组件

  • app/src/main/java/app/xhmcl：迁移后的页面、状态、核心数据、业务服务。
  • app/src/main/java/app/xhmcl/android：系统文件、网络、媒体、JNI JVM、游戏 Surface 与触控适配。
  • app/src/main/assets、jniLibs：固定版本的 Android Java、LWJGL 与渲染组件。
  • app/src/test：核心与手机布局测试；app/src/androidTest：真机 UI、Keystore 与 JNI Java 测试。
  • reference/desktop-smoke：原桌面冒烟测试代码参考，不编入 APK。
  • .tools：本机构建/排障依赖；不应整体上传仓库。
  • scripts/port-desktop.ps1：首次移植的历史迁移脚本，不要对当前代码再次运行。

Android 游戏后端包含 Fold Craft Launcher / Pojav 生态的开源组件，不含 Minecraft 游戏本体。 来源、固定版本、SHA256、许可证和发布注意事项见 [THIRD-PARTY.md](THIRD-PARTY.md)。公开分发前还需要正式签名、设备兼容测试、第三方源码/许可证归档及商店政策审核；不能仅凭 APK 编译成功直接当作正式发行版。