RosettaMC

一次编写 Minecraft 插件，转译到 LegacyScriptEngine (BDS) 和 MC-JS (Paper/Spigot) 双平台。

RosettaMC 是一个 CLI 转译器：使用统一的 TypeScript API 编写插件源码，构建时通过 rolldown 注入对应平台的适配器（shim），输出平台特定的 JavaScript 文件。

快速开始

# 安装
npm install -g rosettamc

# 编写插件
cat > my-plugin.ts << 'EOF'
import { Event, Command, Player, Server } from 'rosettamc';

Server.onEnable(() => {
  Command.register('hello', '发送问候', (ctx) => {
    ctx.reply('你好, ' + (ctx.getPlayer()?.getName() ?? '控制台') + '!');
  });

  Event.listen('player.join', (ctx) => {
    const p = ctx.getPlayer();
    if (p) Player.sendMessage(p, '欢迎!');
  });
});
EOF

# 构建双平台
rosettamc build my-plugin.ts --target lse  -o dist
rosettamc build my-plugin.ts --target mcjs -o dist

# 输出: dist/my-plugin.lse.js  和  dist/my-plugin.mcjs.js

支持平台

| 目标 | 运行环境 | 服务端 | JS 引擎 | |---|---|---|---| | lse | LegacyScriptEngine | LeviLamina (BDS) | QuickJS / Node.js | | mcjs | MC-JS | Paper / Spigot | Rhino (Mozilla) |

统一 API

所有模块从 'rosettamc' 导入：

| 模块 | 说明 | |---|---| | Event | 监听服务器事件 | | Command | 注册玩家/控制台命令 | | Player | 玩家管理（消息、传送、背包、游戏模式） | | Item | 物品栈创建与操作 | | Block | 方块获取/设置/破坏 | | World | 世界时间、天气、爆炸 | | Server | 广播、执行命令、生命周期钩子 | | Scheduler | 延时与循环任务 | | GUI | 简易表单与自定义表单 | | Database | 键值持久化存储 | | File | 文件读写删除 | | Network | HTTP GET/POST 请求 | | Logger | 服务端控制台日志 | | Color | 颜色代码转换与剥离 | | Utils | JSON、哈希、编解码、随机工具 |

完整 API 参考见 docs/api.md。

示例插件

位于 example/essential-kit.rosetta.ts 是一个功能丰富的示例插件，演示了：

• 进出服消息
• /kit GUI 界面选礼包
• /home / /sethome 传送回家
• /heal 治疗命令
• 定时自动广播 + 提示
• 聊天内容过滤
• 数据库持久化
• 冷却系统
• 彩色文本

rosettamc build example/essential-kit.rosetta.ts --target lse  -o dist
rosettamc build example/essential-kit.rosetta.ts --target mcjs -o dist

工作原理

plugin.ts  ───→  rolldown (resolve 插件) ───→  lse-adapter.ts  ───→  plugin.lse.js
plugin.ts  ───→  rolldown (resolve 插件) ───→  mcjs-adapter.ts ───→  plugin.mcjs.js

1. 用户从 'rosettamc' 导入（如 import { Event } from 'rosettamc'）。
2. 构建时，rolldown 通过 resolve 插件将导入解析到目标平台的适配器。
3. 适配器使用平台原生全局 API（LSE 的 mc.*，MC-JS 的 api.*）实现统一接口。
4. 构建输出末尾注入生命周期代码（onEnable/onDisable），适配各平台的插件加载机制。

无需 AST 变换，纯 shim 注入。

跨平台差异

| 特性 | LSE | MC-JS | |---|---|---| | Player 对象 | JS 对象，直接属性 (.name) | Bukkit Java 对象（包装） | | 颜色代码 | § 原生支持 | & 通过 shim 转换 | | NBT | 完整 NBT API | 不可用 | | 经济系统 | money.* 内置 | 需 Vault（可选） | | 模拟玩家 | 支持 | 不可用 | | GUI | SimpleForm / CustomForm | SimpleForm 通过 Inventory GUI | | 数据库 | KVDB | 存根 | | 粒子 | ParticleSpawner | api.spawnParticle | | 事件 | mc.listen("onJoin", cb) | api.registerEvent("player.PlayerJoinEvent", cb) | | 命令 | mc.newCommand 构建器 | api.registerCommand |

项目结构

rosettamc/
├── bin/rosettamc.js              # CLI 入口
├── src/
│   ├── cli/index.ts              # Commander CLI
│   ├── transpiler/index.ts       # rolldown 打包器
│   ├── shims/
│   │   ├── lse-adapter.ts        # LSE 适配器 (mc.*, player.*)
│   │   └── mcjs-adapter.ts       # MC-JS 适配器 (api.*, Bukkit.*)
│   └── types/
│       ├── roseta.d.ts           # 统一 API TypeScript 声明
│       ├── lse-ambient.d.ts      # LSE 全局类型桩
│       └── mcjs-ambient.d.ts     # MC-JS 全局类型桩
├── docs/api.md                   # 完整 API 文档
├── example/
│   └── essential-kit.rosetta.ts   # 示例插件
├── README.md
├── README.zh.md
├── package.json
└── tsconfig.json

许可

MIT