使用脚手架为 SJMCL 开发扩展｜ SJMCL 开发者

从新发布的 SJMC Launcher 1.0.0-beta5 版本开始，SJMC Launcher 支持用户创建与使用各式各样的自定义拓展，自由发挥创意。

你可以使用发布在 npm 的脚手架方便地为 SJMC Launcher 创建扩展，以拓展启动器的界面与功能。

准备环境

使用脚手架前，请先确保本机安装了 Node.js 18.18.0 或更高版本。

第一步：安装脚手架

先全局安装：

npm install -g create-sjmcl-extension

第二步：创建项目

安装完成后，运行：

npx create-sjmcl-extension

第三步：按提示填写扩展信息

脚手架会依次询问这些字段：

Project directory：项目目录，默认是 my-sjmcl-extension
Extension identifier：扩展标识，必须符合 org.example.hello 这样的命名空间格式
Extension name：扩展显示名称
Extension description：（可选）扩展描述
Extension author：（可选）扩展作者
Extension version：（可选）扩展版本
Minimal launcher version：（可选）扩展要求的最低启动器版本
Frontend entry：最终写入 sjmcl.ext.json 的前端入口

第四步：理解生成出来的工程

脚手架会创建一个可直接构建的扩展项目，典型结构如下：

my-extension/
├─ README.md
├─ package.json
├─ sjmcl.ext.json
├─ tsconfig.json
├─ scripts/
│  ├─ build.mjs
│  └─ bump.mjs
└─ src/
   ├─ index.ts
   ├─ widgets/
   │  └─ home-widget.ts
   ├─ pages/
   │  ├─ settings-page.ts
   │  └─ example-page.tsx
   └─ types/
      └─ host.ts

模板默认已经包含：

一个首页卡片 homeWidget
一个设置页 settingsPage
一个自定义页面，同时可在主窗口内跳转显示或在独立新窗口显示；这个页面使用标准 JSX 语法撰写组件树，脚手架在编译时会转换为和 homeWidget 相同的扩展语法（即 React.createElement）
一套最小可用的本地类型定义与扩展注册入口

其中 src/index.ts 是你的源码入口，真正打包进扩展包的前端文件会由构建脚本生成到 frontend/index.js 或你填写的其他入口路径。

第五步：安装依赖并构建

创建完成后，进入项目目录并执行：

cd <你的项目目录>
npm install
npm run build

npm run build 会完成这些事情：

使用 esbuild 将 src/index.ts 打包成单个前端入口文件
按 sjmcl.ext.json 中的 frontend.entry 输出到扩展目录
复制 sjmcl.ext.json
如果存在，也会复制 icon.png、assets/ 和 data/
生成 dist/<identifier>/
额外打包出 dist/<identifier>-<version>.sjmclx

第六步：安装到 SJMCL

构建完成后，在启动器中导入 dist/<identifier>-<version>.sjmclx 即可：

打开启动器。
进入“设置”。
打开“扩展”页面。
点击“添加”并选择刚才生成的 .sjmclx 文件。

现在，你就可以看到示例扩展创建的主页卡片、独立窗口和自定义页面了。

之后，你可以修改 src/widgets/home-widget.ts 和 src/pages 下的内容，实现属于你的奇思妙想。未来，我们也将开放更多扩展能力。

在完成扩展后，你可以在 https://github.com/SJMC-Dev/awesome-SJMCL-extensions 分享你的扩展，请遵守相关法律法规。

参考

SJMCL 扩展系统介绍：https://mc.sjtu.cn/sjmcl/dev/extension/

SJMCL 扩展 API 文档：https://mc.sjtu.cn/sjmcl/dev/extension/api.html

SJTU Minecraft Club