@bkm016/calcite 0.1.0 → 0.3.0

package/README.md

@@ -28,6 +28,8 @@ Calcite 用于以编程方式驱动**真实的 Minecraft Java 版客户端**。
 - [Node.js API](#nodejs-api)
 - [平台与账号](#平台与账号)
 - [渲染模式](#渲染模式)
+- [模组](#模组)
+- [扩展](#扩展)
 - [版本兼容性](#版本兼容性)
 - [数据目录与环境变量](#数据目录与环境变量)
 - [故障排查](#故障排查)
@@ -40,8 +42,11 @@ Calcite 用于以编程方式驱动**真实的 Minecraft Java 版客户端**。
 - **跨平台**：Linux、Windows、macOS。
 - **账号**：支持离线账号，也支持微软正版账号。正版账号使用设备码登录，凭据持久保存并自动刷新。
 - **无显卡环境截图**：在 Linux 服务器上通过 Xvfb 与 Mesa 软件渲染完成截图。
+- **模组加载器**：一行参数安装 Fabric、Forge 或 NeoForge，并从本地文件、URL 或 Modrinth 加载模组（自动补全前置依赖），探针功能在模组环境中同样可用。
+- **玩家操作**：转向、移动、寻路到坐标、攻击、使用物品与方块、挖掘、切换快捷栏、丢弃物品，以及打开箱子等容器并点击槽位。操作走原版客户端逻辑，与真实玩家输入等价。
 - **按需渲染**：默认不渲染画面，截图时临时渲染。单次截图约 0.5 秒，进服后首次截图需等待区块编译，约 2–4 秒。
-- **Java 自动管理**：按游戏版本自动选择 Java；本机缺少时从 Eclipse Adoptium 下载 Temurin，并校验 SHA-256。
+- **Java 自动管理**：按游戏版本自动选择 Java（render `off` 时原本需要 Java 8 的版本改用 Java 17，HeadlessMC 3 的 LWJGL 替身不支持 Java 8）；本机缺少时从 Eclipse Adoptium 下载 Temurin，并校验 SHA-256。HeadlessMC 3 本身运行在 Java 25 上，同样按需下载。
+- **可扩展**：第三方可用 Java 编写扩展 jar，为 bot 增加自定义命令与事件；游戏内的模组也可以零依赖地注册命令。Node.js、MCP、命令行均可直接调用，见[扩展](#扩展)。
 - **自动重连**：掉线或崩溃后按指数退避自动重连。
 - **多客户端**：一个进程可同时管理多个相互隔离的客户端实例。
 
@@ -50,7 +55,7 @@ Calcite 用于以编程方式驱动**真实的 Minecraft Java 版客户端**。
 | 项目 | 要求 |
 | --- | --- |
 | Node.js | 20.18.1 或更高版本 |
-| Java | 无需预装；缺少时自动下载 |
+| Java | 无需预装；缺少时自动下载（游戏所需版本，以及 HeadlessMC 所需的 Java 25） |
 | 磁盘 | 每个游戏版本约 0.5–1 GB，资源文件在各版本间共享 |
 | Linux 截图 | `xvfb`、`libgl1-mesa-dri`；Minecraft 26.x 另需 `libegl1`、`libegl-mesa0` |
 
@@ -91,6 +96,20 @@ calcite launch play.example.com -V 1.21.11 -n Bot1
 | `:shot [文件]` | 截图并保存为 PNG |
 | `:render on\|off` | 开启或关闭持续渲染 |
 | `:respawn` | 死亡后重生 |
+| `:look <yaw> <pitch>` / `:lookat <x> <y> <z>` | 设置视角 / 看向坐标 |
+| `:goto <x> <z>` | 直线走到指定坐标，遇到台阶自动跳跃 |
+| `:move <按键,...> [tick]` | 按住按键若干 tick（默认 20），按键为 `forward`、`back`、`left`、`right`、`jump`、`sneak`、`sprint`、`attack`、`use` |
+| `:stop` | 停止当前移动、挖掘等持续操作 |
+| `:attack [实体ID]` | 攻击指定实体；省略时攻击准星所指 |
+| `:use [实体ID \| x y z] [tick]` | 右键实体或方块；省略目标时使用手中物品，可指定按住时长 |
+| `:dig <x> <y> <z>` | 挖掘方块直至破坏 |
+| `:block <x> <y> <z>` / `:target` | 查看方块 / 查看准星目标 |
+| `:inv` / `:slot <0-8>` | 查看背包 / 切换快捷栏 |
+| `:container` / `:close` | 查看 / 关闭当前打开的容器 |
+| `:click <槽位> [按键] [模式]` | 点击容器槽位，模式见下文 |
+| `:drop [all]` | 丢弃手中物品（`all` 丢弃整组） |
+| `:ext` | 列出扩展命令 |
+| `:call <命令> [JSON 参数]` | 调用扩展命令，例如 `:call hud.tablist {"limit":5}` |
 | `:quit` | 退出并关闭客户端 |
 
 ### 命令一览
@@ -98,7 +117,7 @@ calcite launch play.example.com -V 1.21.11 -n Bot1
 | 命令 | 说明 |
 | --- | --- |
 | `calcite launch [server]` | 启动客户端并在终端中交互 |
-| `calcite install [version]` | 预下载指定版本（客户端、库、资源、Java），不启动游戏 |
+| `calcite install [version]` | 预下载指定版本（客户端、库、资源、Java），不启动游戏；`-l, --loader` 同时安装模组加载器 |
 | `calcite versions` | 列出可用版本（`-t release\|snapshot\|old_beta\|old_alpha\|all`，`-l <数量>`） |
 | `calcite login` | 微软账号登录（设备码） |
 | `calcite accounts` | 列出已保存的微软账号 |
@@ -115,6 +134,9 @@ calcite launch play.example.com -V 1.21.11 -n Bot1
 | `-u, --username <name>` | 实例名 | 离线用户名 |
 | `-m, --microsoft [account]` | — | 使用已保存的微软账号（省略名称时使用主账号） |
 | `-r, --render <mode>` | `on-demand` | 渲染模式：`on-demand`、`always`、`off` |
+| `-l, --loader <loader>` | — | 模组加载器：`fabric`、`forge`、`neoforge`，可加 `@<版本>`，见[模组](#模组) |
+| `--mod <spec>` | — | 加载模组，可重复；需同时指定加载器 |
+| `--ext <jar>` | — | 加载探针扩展（本地 jar 或 URL），可重复；扩展事件输出到标准错误 |
 | `--java <path>` | 自动选择 | 指定游戏使用的 Java |
 | `--no-java-download` | — | 禁止自动下载 Java |
 | `--memory <size>` | `2G` | 最大堆内存 |
@@ -148,13 +170,13 @@ Claude Code 也可以通过命令添加：
 claude mcp add calcite -- npx -y @bkm016/calcite mcp
 ```
 
-`calcite mcp` 支持 `-r, --render <mode>` 和 `--memory <size>`，用于设置新客户端的默认值。
+`calcite mcp` 支持 `-r, --render <mode>`、`--memory <size>` 和 `--ext <jar>`（可重复），用于设置新客户端的默认值。
 
 ### 工具列表
 
 | 工具 | 说明 |
 | --- | --- |
-| `launch_client` | 启动客户端，可指定服务器、版本、离线用户名或微软账号、渲染模式 |
+| `launch_client` | 启动客户端，可指定服务器、版本、离线用户名或微软账号、渲染模式、模组加载器与模组 |
 | `stop_client` | 停止客户端 |
 | `list_clients` | 列出当前管理的客户端 |
 | `get_state` | 获取生命周期阶段与游戏状态（界面、坐标、生命值、维度、帧率、断开原因） |
@@ -162,12 +184,30 @@ claude mcp add calcite -- npx -y @bkm016/calcite mcp
 | `send_chat` | 发送聊天消息 |
 | `run_command` | 执行指令，并返回执行期间收到的聊天 |
 | `screenshot` | 渲染并返回 PNG 截图 |
-| `wait_for` | 等待条件成立：聊天匹配正则、实体出现或消失、进入指定阶段 |
+| `wait_for` | 等待条件成立：聊天匹配正则、实体出现或消失、进入指定阶段、收到扩展事件 |
 | `get_chat` | 获取聊天记录 |
 | `get_logs` | 获取游戏日志与 Calcite 日志，用于排查崩溃 |
 | `set_render` | 开启或关闭持续渲染 |
 | `respawn` | 死亡后重生 |
-| `install_version` | 预下载指定版本 |
+| `look` | 设置视角，或看向指定坐标 |
+| `walk_to` | 直线走到指定坐标，遇障碍自动跳跃，返回是否到达 |
+| `move` | 按住移动、跳跃、潜行、疾跑等按键若干 tick |
+| `stop_actions` | 停止所有持续操作并松开按键 |
+| `attack` | 攻击实体（按 ID 或准星目标） |
+| `use` | 右键：使用手中物品、与方块交互（开箱、放置）、与实体交互 |
+| `dig` | 挖掘方块直至破坏 |
+| `get_block` | 查询方块 ID 与方块状态 |
+| `get_target` | 查询准星所指的方块或实体 |
+| `get_inventory` | 查询背包、快捷栏与手持物品 |
+| `select_slot` | 切换快捷栏槽位 |
+| `get_container` | 查询当前打开的容器（类型、标题、槽位物品） |
+| `click_slot` | 点击容器槽位，支持拾取、快速移动、数字键交换、丢弃等模式 |
+| `close_container` | 关闭当前容器 |
+| `drop_item` | 丢弃手中物品 |
+| `list_extensions` | 列出扩展与模组注册的命令（名称、说明、参数 schema）及已加载的扩展 jar |
+| `call_extension` | 调用扩展命令 |
+| `get_events` | 获取扩展事件（可按序号、名称正则过滤） |
+| `install_version` | 预下载指定版本，可同时安装模组加载器 |
 | `list_versions` | 列出可用版本 |
 | `account_login_start` | 开始微软账号登录，返回验证链接 |
 | `account_login_status` | 查询登录进度 |
@@ -210,6 +250,9 @@ await bot.stop();
 | `server` | `host[:port]`；省略时停留在标题界面 |
 | `account` | `{ type: 'offline', username }` 或 `{ type: 'microsoft', name? }` |
 | `render` | `on-demand`（默认）、`always`、`off` |
+| `loader` | 模组加载器：`fabric`、`forge`、`neoforge`，可加 `@<版本>` |
+| `mods` | 模组列表：本地 jar 或目录、http(s) URL、`modrinth:<项目>[@<版本>]` |
+| `extensions` | 探针扩展 jar：本地路径或 http(s) URL |
 | `memory` | 最大堆内存，默认 `2G` |
 | `javaPath` / `allowJavaDownload` | 指定 Java 路径 / 是否允许自动下载 |
 | `jvmArgs` / `gameArgs` | 额外的 JVM 参数 / 游戏参数 |
@@ -228,11 +271,41 @@ await bot.stop();
 | `entities(query)` | 实体列表，`query` 支持 `radius`、`type`、`name`、`uuid`、`limit` |
 | `chat(text)` / `command(cmd)` | 发送聊天 / 执行指令 |
 | `screenshot({ keep })` | 返回 `{ png, path? }` |
-| `waitFor(cond, timeoutMs)` | 等待聊天、实体或阶段条件 |
+| `waitFor(cond, timeoutMs)` | 等待聊天、实体、阶段条件或扩展事件（`{ event: '正则' }`） |
 | `setRender(enabled)` / `respawn()` | 切换持续渲染 / 重生 |
 | `chatSince(seq)` / `logsSince(opts)` | 读取聊天与日志缓冲 |
+| `look({ yaw, pitch } \| { x, y, z })` | 设置视角或看向坐标 |
+| `walkTo(x, z, { range, sprint, timeoutMs })` | 走到坐标，返回 `{ arrived, reason?, distance, x, y, z }` |
+| `move(controls, { ticks })` / `stopActions()` | 按住按键若干 tick / 停止所有持续操作 |
+| `attack(entityId?)` | 攻击实体，省略时攻击准星目标 |
+| `use({ entityId?, block?, holdTicks? })` | 右键实体、方块或使用手中物品 |
+| `dig(block, { timeoutMs })` | 挖掘方块，返回 `{ broken, block, ticks?, reason? }` |
+| `block(pos)` / `target()` | 查询方块 / 准星目标 |
+| `inventory()` / `selectSlot(n)` | 查询背包 / 切换快捷栏 |
+| `container({ waitMs })` / `closeContainer()` | 查询 / 关闭当前容器 |
+| `click(slot, { button, mode })` | 点击容器槽位 |
+| `drop({ all })` | 丢弃手中物品 |
+| `extensions()` / `call(name, args)` | 列出扩展命令 / 调用扩展命令 |
+| `eventsSince({ since, name, limit })` | 读取扩展事件缓冲（最多保留 1000 条） |
+
+事件：`phase`、`state`、`chat`、`log`、`exit`、`extension`（扩展事件 `{ seq, time, name, data }`）。
+
+### 玩家操作示例
 
-事件：`phase`、`state`、`chat`、`log`、`exit`。
+```js
+await bot.walkTo(100.5, 200.5);                             // 走到 (100.5, 200.5)
+await bot.dig({ x: 101, y: 64, z: 200 });                   // 挖掉一个方块
+await bot.use({ block: { x: 100, y: 64, z: 202 } });        // 右键打开箱子
+const chest = await bot.container({ waitMs: 3000 });        // 等待容器界面打开
+for (const item of chest.items.filter((i) => i.slot < chest.containerSlots)) {
+  await bot.click(item.slot, { mode: 'quick_move' });       // Shift+点击 取出物品
+}
+await bot.closeContainer();
+```
+
+容器槽位编号与原版一致：容器自身的槽位在前（`0` 到 `containerSlots - 1`），玩家背包在后；`item.inventorySlot` 给出对应的背包槽位。`click` 的 `mode` 可取 `pickup`（默认，`button` 0 为左键、1 为右键）、`quick_move`（Shift+点击）、`swap`（数字键，`button` 为快捷栏序号 0–8）、`clone`、`throw`、`quick_craft`、`pickup_all`；槽位 `-999` 表示点击界面外部。未打开容器时，`click` 作用于玩家自身的背包界面。
+
+操作有距离限制（6 格）：目标过远时返回 `out_of_reach` 错误，需先用 `walkTo` 靠近。
 
 此外还导出 `ClientManager`（多客户端管理）、`installVersion`、`startLogin`、`listAccounts`、`removeAccount` 等函数，类型定义随包发布。
 
@@ -243,10 +316,12 @@ await bot.stop();
 | Linux | 全部功能（在 Xvfb 中渲染） | 全部功能 |
 | Windows / macOS | 无渲染运行，不支持截图，其余功能正常 | 全部功能 |
 
-HeadlessMC 仅允许离线账号在 Linux 虚拟显示器中渲染。这是上游策略，Calcite 遵循该策略。如需在 Windows 或 macOS 上截图，请使用正版账号。
+HeadlessMC 仅在检测到 Xvfb 时允许离线账号渲染，否则强制以无渲染方式运行。这是上游策略，Calcite 遵循该策略。如需在 Windows 或 macOS 上截图，请使用正版账号。
 
 离线账号只能进入 `online-mode=false` 的服务器。
 
+从 0.1.x 升级：Calcite 现使用 HeadlessMC 3，其凭据格式与 HeadlessMC 2 不兼容，已保存的微软账号需要重新执行一次 `calcite login`。
+
 ## 渲染模式
 
 | 模式 | 说明 |
@@ -255,11 +330,134 @@ HeadlessMC 仅允许离线账号在 Linux 虚拟显示器中渲染。这是上
 | `always` | 持续渲染，适合在本地桌面观察 |
 | `off` | 以无渲染器方式运行（替换 LWJGL），资源占用最低，不支持截图 |
 
+## 模组
+
+```bash
+# Fabric + Fabric API（从 Modrinth 下载，自动补全前置）
+calcite launch localhost -V 1.21.11 -l fabric --mod modrinth:fabric-api --mod ./mods/my-mod.jar
+
+# 指定加载器版本
+calcite launch localhost -V 1.20.1 -l forge@47.4.26
+calcite install 1.21.11 -l neoforge
+```
+
+```js
+new Client({ version: '1.21.11', loader: 'fabric', mods: ['modrinth:fabric-api', './my-mod.jar'] });
+```
+
+<p align="center">
+  <img src="docs/images/mods-fabric.jpg" alt="Fabric 1.21.11：Xaero's Minimap 与 Jade" width="49%">
+  <img src="docs/images/mods-neoforge.jpg" alt="NeoForge 1.21.11：JEI 物品列表" width="49%">
+</p>
+<p align="center"><sub>左：Fabric 1.21.11，加载 Fabric API、Xaero's Minimap、Jade、Mod Menu，准星对准羊时 Jade 显示其信息。右：NeoForge 1.21.11，加载 JEI 与 Xaero's Minimap，通过 <code>use</code> 打开箱子后右侧为 JEI 物品列表。模组均以 <code>modrinth:</code> 参数自动下载。</sub></p>
+
+- 加载器由 HeadlessMC 安装到共享的 `minecraft/versions/`，省略版本时使用最新版本（已安装过则复用本地最新版）。
+- 模组来源：本地 jar、包含 jar 的目录、http(s) URL，或 `modrinth:<项目>[@<版本号>]`。Modrinth 模组按游戏版本与加载器挑选最新正式版，并自动下载必需的前置模组；下载文件按哈希校验并缓存在 `mods/`。
+- 模组复制到实例的 `mods/` 目录。Calcite 只管理自己放入的文件（记录在 `mods/.calcite-mods.json`），手动放入的模组不受影响。
+- 模组加载失败时，客户端会停在错误界面；Calcite 检测到后立即结束进程并返回 `mod_loading_failed`，错误信息附带相关日志。
+
+| 加载器 | 支持的版本 | 探针 |
+| --- | --- | --- |
+| Fabric | Fabric 支持的所有版本 | 全部功能（自动将 Mojang 映射转换为 intermediary 名称） |
+| NeoForge | 1.20.2 及以上 | 全部功能 |
+| Forge | 1.17 及以上 | 全部功能（1.20.4 及以前自动转换为 SRG 名称） |
+| Forge | 1.16.5 及以前 | 可以启动，探针功能不可用 |
+
+Forge 与 NeoForge 的安装器要求与游戏版本完全一致的 Java 主版本（例如 1.20.1 需要 Java 17），缺少时自动下载。Forge 与 NeoForge 不支持在 render `off` 下运行原本需要 Java 8 的版本。
+
+已验证：Fabric 1.21.11 / 26.3（含 Fabric API）、NeoForge 1.20.4 / 1.21.11、Forge 1.20.1 / 1.21.1。
+
+## 扩展
+
+内置操作之外的能力可以由第三方补充，有两种方式：
+
+- **扩展 jar**：用 Java 编写，通过探针 API 注册命令、发送事件，启动时用 `extensions` / `--ext` 加载。适合为 bot 增加读取界面、执行复杂操作等能力，不需要模组加载器。
+- **模组桥接**：游戏中已安装的模组无需依赖 Calcite，直接通过系统属性注册命令。适合模组作者为自己的模组提供测试接口。
+
+两种方式注册的命令都可以从 Node.js、MCP 与命令行调用；事件推送到 Node.js 端，可以监听、查询，也可以在 `wait_for` 中等待。
+
+### 使用扩展
+
+```js
+const bot = new Client({ version: '1.21.11', server: 'localhost', extensions: ['./calcite-hud.jar'] });
+bot.on('extension', (e) => console.log(e.name, e.data));     // 例如 hud.title { title: 'Hello', subtitle: null }
+await bot.start();
+
+console.log(await bot.extensions());                         // { commands: [...], extensions: [{ jar, ids }] }
+console.log(await bot.call('hud.sidebar'));                  // { title: 'Kills', lines: [{ name: 'Bot1', score: 7 }] }
+await bot.waitFor({ event: '^hud\\.title$' }, 10_000);
+```
+
+```bash
+calcite launch localhost -V 1.21.11 --ext ./calcite-hud.jar   # 交互模式中用 :ext 与 :call
+calcite mcp --ext ./calcite-hud.jar                            # MCP 中用 list_extensions / call_extension / get_events
+```
+
+[`examples/extension-hud`](examples/extension-hud) 是一个完整示例，提供 `hud.bossbars`（Boss 栏）、`hud.sidebar`（计分板侧边栏）、`hud.tablist`（Tab 列表）、`hud.title`（标题与动作栏）四个命令，并在标题或动作栏变化时发送 `hud.title`、`hud.actionbar` 事件。已在原版 1.21.11、Fabric 1.21.11、Forge 1.20.1 上验证。构建方法：`npm run build:probe && node examples/extension-hud/build.mjs`。
+
+### 编写扩展 jar
+
+扩展针对探针 API 编译。API 位于 npm 包内的 `vendor/calcite-probe.jar`（包名 `calcite.probe.api`），只在编译时需要，不要打包进扩展。以 Java 8 为目标编译即可在所有版本上运行。
+
+```java
+package com.example;
+
+import calcite.probe.api.*;
+
+public final class MyExtension implements CalciteExtension {
+    @Override public String id() { return "my"; }                  // 命令与事件名的前缀
+
+    @Override public void init(final Calcite c) {
+        c.command("health", "玩家生命值", null, args -> c.onGameThread(() -> {
+            Object player = c.ref().get(c.minecraft(), "player");      // Mojang 官方名称，任何加载器下都可用
+            return player == null ? null : c.ref().call(player, "getHealth");
+        }, 5000));                                                     // 注册为 my.health
+        c.emit("ready", c.minecraftVersion());                         // 发送事件 my.ready
+    }
+}
+```
+
+在 jar 中添加 `META-INF/services/calcite.probe.api.CalciteExtension`，内容为实现类的全名（一个 jar 可以包含多个扩展）。
+
+`Calcite` 接口：
+
+| 方法 | 说明 |
+| --- | --- |
+| `command(name, [description, schema,] handler)` | 注册命令 `<id>.<name>`。`handler` 接收参数 `Map`，返回值序列化为 JSON（支持 `Map`、`List`、数组、字符串、数字、布尔、`null`）；`schema` 为参数的 JSON Schema，会显示在 `list_extensions` 中 |
+| `emit(name, data)` | 发送事件 `<id>.<name>` |
+| `onGameThread(task, timeoutMs)` | 在游戏主线程上执行；读写游戏状态必须在主线程进行。命令处理器本身运行在工作线程 |
+| `ref()` | 反射工具，按 Mojang 官方名称访问类、字段与方法（`cls`、`get`、`call`、`method` 等），自动转换为运行时的 intermediary / SRG 名称 |
+| `minecraft()` / `minecraftVersion()` / `headless()` | `Minecraft` 实例 / 版本号 / 是否以无渲染方式运行 |
+| `call(op, args)` | 调用探针内置操作，例如 `state`、`entities`、`chat` |
+| `log(message)` | 写入游戏日志 |
+
+处理器抛出 `CalciteException(code, message)` 时，调用方收到对应的错误码；其他异常的错误码为 `error`。扩展的类加载器可以看到游戏（含模组）的全部类，但为了兼容所有加载器与版本，推荐通过 `ref()` 以官方名称反射访问。
+
+### 模组桥接
+
+模组无需依赖 Calcite。探针在游戏启动前通过系统属性发布两个对象：
+
+| 系统属性 | 类型 | 用途 |
+| --- | --- | --- |
+| `calcite.commands` | `Map<String, Object>` | 放入命令。值可以是 `Function<Map<String, Object>, Object>`、`Callable`、`Runnable`，或 `Map`：`{ handler, description, schema }` |
+| `calcite.emit` | `BiConsumer<String, Object>` | 发送事件 |
+
+```java
+@SuppressWarnings("unchecked")
+static void registerCalcite() {
+    Object commands = System.getProperties().get("calcite.commands");
+    if (!(commands instanceof Map)) return;                            // 不是由 Calcite 启动
+    ((Map<String, Object>) commands).put("mymod.status", (Function<Map<String, Object>, Object>) args -> MyMod.status());
+}
+```
+
+模组命令在 `list_extensions` 中的 `source` 为 `mod`，命令名不会自动加前缀，建议使用 `<模组 ID>.<命令>`。
+
 ## 版本兼容性
 
 | 版本范围 | 支持情况 |
 | --- | --- |
-| 1.14.4 及以上 | 全部功能（状态、实体、聊天、指令、截图） |
+| 1.14.4 及以上 | 全部功能（状态、实体、聊天、指令、截图、玩家操作） |
 | 1.14.4 以前 | 可以启动并进入服务器；Mojang 未发布这些版本的映射表，探针功能不可用 |
 
 已验证的版本：1.16.5、1.20.4、1.21.11、26.3。
@@ -272,14 +470,17 @@ HeadlessMC 仅允许离线账号在 Linux 虚拟显示器中渲染。这是上
 | --- | --- |
 | `minecraft/` | 各版本共享的游戏文件、库与资源 |
 | `instances/<name>/` | 各实例独立的游戏目录（`options.txt`、日志、截图） |
-| `hmc-home/HeadlessMC/auth/` | 已保存的微软登录凭据（权限 600，请妥善保管） |
+| `hmc-home/.auth/default/` | 已保存的微软登录凭据（权限 600，请妥善保管） |
+| `instances/<name>/.headlessmc/` | 该实例的 HeadlessMC 配置、账号副本与缓存 |
 | `java/` | 自动下载的 Java 运行时 |
+| `mods/` | 从 URL 与 Modrinth 下载的模组缓存 |
+| `mappings/` | 映射表及为模组加载器转换后的名称表 |
 
 | 环境变量 | 说明 |
 | --- | --- |
 | `CALCITE_HOME` | 数据目录 |
 | `CALCITE_LOG_LEVEL` | 日志级别：`debug`、`info`、`warn`、`error`、`silent` |
-| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | 下载代理 |
+| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | HTTP 代理。Calcite 自身的下载使用该代理，并将其转换为 Java 系统属性传给 HeadlessMC 与游戏进程（Java 不支持代理认证；游戏与服务器之间的连接不经过代理） |
 | `CALCITE_JAVA_<主版本>` | 指定某个 Java 主版本的路径，例如 `CALCITE_JAVA_8` |
 | `CALCITE_HMC_JAR` / `CALCITE_HMC_URL` | 使用自定义的 HeadlessMC |
 | `CALCITE_PROBE_DIR` | 探针目录，路径中不能包含空格 |
@@ -298,14 +499,20 @@ HeadlessMC 仅允许离线账号在 Linux 虚拟显示器中渲染。这是上
 | `not_logged_in` / `unknown_account` | 未登录微软账号或账号名不存在。请先执行 `calcite login` |
 | `instance_busy` | 同名实例已在其他进程中运行 |
 | `unsupported_version` | 版本不存在或不受支持 |
+| `bad_loader` / `unsupported_loader` | 加载器名称或版本格式错误 / 该版本组合无法运行 |
+| `install_failed` | HeadlessMC 未能安装加载器（该游戏版本可能没有对应构建） |
+| `bad_mod` / `mod_not_found` | 模组参数错误 / 找不到模组文件或 Modrinth 上没有适配的版本 |
+| `mod_loading_failed` | 模组加载失败（缺少前置、版本不兼容等），错误信息附带日志 |
+| `extension_not_found` | 找不到扩展 jar |
+| `unknown_command` | 没有该扩展命令，可用 `list_extensions` 查看；扩展 jar 加载失败的原因见 `extensions()` 返回的 `error` |
 
 排查环境问题时，建议先运行 `calcite doctor`。
 
 ## 工作原理
 
 1. Calcite 解析 Mojang 版本清单，下载客户端、库与资源文件，并逐一校验哈希。
-2. 使用 [HeadlessMC](https://github.com/headlesshq/headlessmc) 启动游戏。每个实例拥有独立的游戏目录和启动参数。
-3. 向游戏注入一个轻量 Java Agent（探针）。探针借助 Mojang 官方映射表定位游戏内部类，并通过本地 TCP 连接与 Calcite 交换 JSON 消息。
+2. 使用 [HeadlessMC](https://github.com/headlesshq/headlessmc) 3 启动游戏。每个实例拥有独立的游戏目录、HeadlessMC 配置和启动参数，并发启动互不干扰。
+3. 向游戏注入一个轻量 Java Agent（探针）。探针借助 Mojang 官方映射表（模组环境下转换为 intermediary 或 SRG 名称）定位游戏内部类，并通过本地 TCP 连接与 Calcite 交换 JSON 消息。
 4. 在 Linux 无显示环境中，Calcite 启动共享的 Xvfb，并配置 Mesa 软件渲染。Minecraft 26.x 的渲染器改用 EGL。
 
 ## 许可

package/dist/accounts.d.ts

@@ -1,16 +1,35 @@
 import type { CalcitePaths } from './paths.js';
-/** HeadlessMC stores Microsoft sessions (refresh tokens) here; Calcite restricts it to the current user. */
+/** HeadlessMC files location holding the Microsoft sessions created by `calcite login`. */
+export declare function accountsHome(paths: CalcitePaths): string;
+/** Microsoft sessions of `calcite login`; Calcite restricts the file to the current user. */
 export declare function accountsFile(paths: CalcitePaths): string;
 export declare function accountsLock(paths: CalcitePaths): string;
 export interface AccountInfo {
     name: string;
     uuid?: string;
-    /** The account HeadlessMC uses for the next launch. */
+    /** The account used when a client does not name one. */
     primary: boolean;
 }
-/** Stored Microsoft accounts (no secrets). The first one is the primary account. */
+/** Stored Microsoft accounts (no secrets). */
 export declare function listAccounts(paths: CalcitePaths): Promise<AccountInfo[]>;
 export declare function removeAccount(paths: CalcitePaths, name: string): Promise<boolean>;
+/** UUID the vanilla server assigns to an offline player (version 3, from "OfflinePlayer:<name>"), without dashes. */
+export declare function offlineUuid(name: string): string;
+export type LaunchAccount = {
+    type: 'offline';
+    username: string;
+} | {
+    type: 'microsoft';
+    name?: string;
+};
+/**
+ * Prepares the private HeadlessMC location of one client so that HeadlessMC launches exactly this account.
+ * Microsoft sessions are copied from the `calcite login` store; {@link syncAccount} writes refreshed tokens back.
+ * Returns the account name.
+ */
+export declare function prepareAccount(paths: CalcitePaths, location: string, account: LaunchAccount): Promise<string>;
+/** Copies a Microsoft session refreshed by a launch back into the `calcite login` store. */
+export declare function syncAccount(paths: CalcitePaths, location: string, name: string): Promise<void>;
 export interface LoginHandle {
     /** Microsoft device login URL (contains the code); open it in a browser and approve. */
     url: Promise<string>;
@@ -20,7 +39,7 @@ export interface LoginHandle {
 }
 /**
  * Starts a Microsoft device-code login through HeadlessMC. The session (including the refresh token) is stored
- * in the shared HeadlessMC home and refreshed automatically on every launch.
+ * in Calcite's HeadlessMC location and refreshed automatically on every launch.
  */
 export declare function startLogin(paths: CalcitePaths, { timeoutMs }?: {
     timeoutMs?: number | undefined;

package/dist/accounts.js

@@ -1,70 +1,151 @@
-import { chmod, readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { ensureHmc, ensureHmcHome, killTree, runHmc } from './hmc.js';
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { ensureHmc, killTree, runHmc } from './hmc.js';
 import { ensureLauncherJava } from './java.js';
 import { withLock } from './lock.js';
-/** HeadlessMC stores Microsoft sessions (refresh tokens) here; Calcite restricts it to the current user. */
+/** HeadlessMC account providers. */
+const MICROSOFT = 'default';
+const OFFLINE = 'offline';
+/** HeadlessMC files location holding the Microsoft sessions created by `calcite login`. */
+export function accountsHome(paths) {
+    return paths.hmcHome;
+}
+/** HeadlessMC 3 stores the sessions (including refresh tokens) of one provider in this file. */
+function storeFile(location, provider) {
+    return join(location, '.auth', provider, '.accounts.json');
+}
+function lastUsedFile(location) {
+    return join(location, '.auth', 'last', '.accounts.json');
+}
+/** Microsoft sessions of `calcite login`; Calcite restricts the file to the current user. */
 export function accountsFile(paths) {
-    return join(paths.hmcHome, 'HeadlessMC', 'auth', '.accounts.json');
+    return storeFile(accountsHome(paths), MICROSOFT);
 }
 export function accountsLock(paths) {
     return join(paths.hmcHome, 'accounts.lock');
 }
-function findProfile(account) {
-    // FullJavaSession JSON: { mcProfile: { name, id, ... }, ... } (possibly nested)
-    const stack = [account];
+async function readStore(file) {
+    try {
+        const data = JSON.parse(await readFile(file, 'utf8'));
+        return data.accounts && typeof data.accounts === 'object' && !Array.isArray(data.accounts) ? data.accounts : {};
+    }
+    catch {
+        return {};
+    }
+}
+async function writeStore(file, accounts) {
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify({ accounts, version: 0 }, null, 2), { mode: 0o600 });
+    if (process.platform !== 'win32')
+        await chmod(file, 0o600).catch(() => undefined); // Windows: the profile ACL applies
+}
+function findKey(accounts, name) {
+    return Object.keys(accounts).find((k) => k.toLowerCase() === name.toLowerCase());
+}
+/** The Minecraft profile id inside a stored MinecraftAuth session (an object carrying both the name and the id). */
+function findUuid(session, name) {
+    const stack = [session];
     while (stack.length) {
         const node = stack.pop();
         if (!node || typeof node !== 'object')
             continue;
         const obj = node;
-        if (obj.mcProfile && typeof obj.mcProfile === 'object') {
-            const p = obj.mcProfile;
-            return { name: typeof p.name === 'string' ? p.name : undefined, uuid: typeof p.id === 'string' ? p.id : undefined };
-        }
+        if (typeof obj.name === 'string' && obj.name.toLowerCase() === name.toLowerCase() && typeof obj.id === 'string')
+            return obj.id;
         for (const v of Object.values(obj))
             if (v && typeof v === 'object')
                 stack.push(v);
     }
-    return {};
+    return undefined;
 }
-async function readAccounts(paths) {
-    try {
-        const data = JSON.parse(await readFile(accountsFile(paths), 'utf8'));
-        return Array.isArray(data.accounts) ? data.accounts : [];
-    }
-    catch {
-        return [];
-    }
+/** Name of the most recently used Microsoft account of a HeadlessMC location. */
+async function lastUsed(location) {
+    const latest = (await readStore(lastUsedFile(location))).latest;
+    if (!Array.isArray(latest))
+        return undefined;
+    const entry = latest.find((e) => e && typeof e === 'object' && e.provider === MICROSOFT);
+    return typeof entry?.name === 'string' ? entry.name : undefined;
 }
-/** Stored Microsoft accounts (no secrets). The first one is the primary account. */
+/** Stored Microsoft accounts (no secrets). */
 export async function listAccounts(paths) {
-    return (await readAccounts(paths)).map((a, i) => ({ ...findProfile(a), name: findProfile(a).name ?? `account-${i}`, primary: i === 0 }));
+    const accounts = await readStore(accountsFile(paths));
+    const names = Object.keys(accounts);
+    const last = await lastUsed(accountsHome(paths));
+    const primary = (last && findKey(accounts, last)) ?? names[0];
+    return names.map((name) => ({ name, uuid: findUuid(accounts[name], name), primary: name === primary }));
 }
 export async function removeAccount(paths, name) {
     return withLock(accountsLock(paths), async () => {
-        const accounts = await readAccounts(paths);
-        const kept = accounts.filter((a) => findProfile(a).name?.toLowerCase() !== name.toLowerCase());
-        if (kept.length === accounts.length)
+        const accounts = await readStore(accountsFile(paths));
+        const key = findKey(accounts, name);
+        if (!key)
             return false;
-        await writeFile(accountsFile(paths), JSON.stringify({ accounts: kept }, null, 2));
-        await restrictPermissions(paths);
+        delete accounts[key];
+        await writeStore(accountsFile(paths), accounts);
         return true;
     });
 }
-async function restrictPermissions(paths) {
-    if (process.platform === 'win32')
-        return; // stays under the user's profile ACL
-    await chmod(accountsFile(paths), 0o600).catch(() => undefined);
+/** UUID the vanilla server assigns to an offline player (version 3, from "OfflinePlayer:<name>"), without dashes. */
+export function offlineUuid(name) {
+    const hash = createHash('md5').update(`OfflinePlayer:${name}`, 'utf8').digest();
+    hash[6] = (hash[6] & 0x0f) | 0x30;
+    hash[8] = (hash[8] & 0x3f) | 0x80;
+    return hash.toString('hex');
+}
+/**
+ * Prepares the private HeadlessMC location of one client so that HeadlessMC launches exactly this account.
+ * Microsoft sessions are copied from the `calcite login` store; {@link syncAccount} writes refreshed tokens back.
+ * Returns the account name.
+ */
+export async function prepareAccount(paths, location, account) {
+    if (account.type === 'offline') {
+        const name = account.username;
+        await rm(storeFile(location, MICROSOFT), { force: true });
+        await writeStore(storeFile(location, OFFLINE), {
+            [name]: { provider: OFFLINE, name, uuid: offlineUuid(name), token: '', type: 'msa', xuid: '' },
+        });
+        await writeStore(lastUsedFile(location), { latest: [{ provider: OFFLINE, name }] });
+        return name;
+    }
+    return withLock(accountsLock(paths), async () => {
+        const accounts = await listAccounts(paths);
+        if (!accounts.length)
+            throw Object.assign(new Error('No Microsoft account is stored; run `calcite login` first'), { code: 'not_logged_in' });
+        const wanted = account.name;
+        const match = wanted ? accounts.find((a) => a.name.toLowerCase() === wanted.toLowerCase()) : accounts.find((a) => a.primary);
+        if (!match) {
+            throw Object.assign(new Error(`No stored Microsoft account named "${wanted}" (have: ${accounts.map((a) => a.name).join(', ')})`), { code: 'unknown_account' });
+        }
+        const session = (await readStore(accountsFile(paths)))[match.name];
+        await rm(storeFile(location, OFFLINE), { force: true });
+        await writeStore(storeFile(location, MICROSOFT), { [match.name]: session });
+        await writeStore(lastUsedFile(location), { latest: [{ provider: MICROSOFT, name: match.name }] });
+        return match.name;
+    });
+}
+/** Copies a Microsoft session refreshed by a launch back into the `calcite login` store. */
+export async function syncAccount(paths, location, name) {
+    const local = await readStore(storeFile(location, MICROSOFT));
+    const key = findKey(local, name);
+    if (!key)
+        return;
+    await withLock(accountsLock(paths), async () => {
+        const accounts = await readStore(accountsFile(paths));
+        const central = findKey(accounts, name);
+        if (!central || JSON.stringify(accounts[central]) === JSON.stringify(local[key]))
+            return; // removed meanwhile, or unchanged
+        accounts[central] = local[key];
+        await writeStore(accountsFile(paths), accounts);
+    });
 }
 /**
  * Starts a Microsoft device-code login through HeadlessMC. The session (including the refresh token) is stored
- * in the shared HeadlessMC home and refreshed automatically on every launch.
+ * in Calcite's HeadlessMC location and refreshed automatically on every launch.
  */
 export async function startLogin(paths, { timeoutMs = 15 * 60_000 } = {}) {
     const java = await ensureLauncherJava(paths);
     const hmcJar = await ensureHmc(paths);
-    await ensureHmcHome(paths);
     let resolveUrl;
     let rejectUrl;
     const url = new Promise((res, rej) => {
@@ -76,17 +157,16 @@ export async function startLogin(paths, { timeoutMs = 15 * 60_000 } = {}) {
     const run = runHmc({
         javaPath: java.path,
         hmcJar,
-        paths,
-        props: { 'hmc.store.accounts': 'true' },
+        location: accountsHome(paths),
         command: ['login'],
         onLine: (line) => {
-            const go = /Go to (https?:\/\/\S+)/.exec(line);
+            const go = /To login visit (https?:\/\/\S+)/.exec(line);
             if (go)
                 resolveUrl(go[1]);
-            const ok = /Logged into account (.+?) successfully/.exec(line);
+            const ok = /Logged in to account (.+?) successfully/.exec(line);
             if (ok)
                 account = ok[1];
-            if (/Failed to login|You can't play|Login process cancelled/.test(line))
+            if (/AuthException|Failed to login|You can't play|Exception:/.test(line) && !failure)
                 failure = line.trim();
         },
     });
@@ -98,7 +178,7 @@ export async function startLogin(paths, { timeoutMs = 15 * 60_000 } = {}) {
             rejectUrl(err);
             throw err;
         }
-        await restrictPermissions(paths);
+        await chmod(accountsFile(paths), 0o600).catch(() => undefined);
         return account;
     });
     done.catch(() => undefined);