Skip to content

插件 API ​

协议版本为 1.4.6,自启动器 1.4.0 起逐步开放,当前 1.5.5 沿用该协议。协议原文见官方仓库的 docs/PLUGIN_GUIDE.md。

插件是一个普通 APK,不是代码模块。启动器不加载插件的 dex,也不与插件共享进程。启动器只读取 APK 内 assets/zplugin/ 下的配置,再用原生控件渲染页面。

因此,插件能实现什么功能,取决于插件自身的应用。启动器只提供入口、渲染和若干系统动作。

按步骤编写插件的教程见帮助文档的「插件」专题;本页只说明协议本身。

插件类型 ​

类型标记作用
资源插件target: "minecraft" 与 files/把文件树覆盖到游戏目录,用于模组、资源包与配置
皮肤插件ui: "<标识>" 与 ui.json只改变外观,包括配色、圆角与玻璃渲染
自带界面插件entry: true 与 label插件本身是一个已安装的应用,启动器为它提供一个入口

三类标记可以同时出现在一个 APK 中。本页以自带界面插件为主,这类插件同时可以使用页面协议。

目录结构 ​

text
assets/zplugin/
├── plugin.json      # 必需:清单
├── pages.json       # 可选:页面、版块接管、左栏入口
├── ui.json          # 可选:皮肤
├── files/           # 可选:要覆盖到游戏目录的文件树
└── res/             # 可选:icon 积木引用的图片

启动器判断一个 APK 是否为插件,只看包内是否存在 assets/zplugin/plugin.json。文件缺失时,导入会被拒绝,并提示「不是有效的插件 APK」。

plugin.json ​

json
{
  "name": "基岩版管理器",
  "version": "1.0.12",
  "author": "Zalith",
  "description": "管理、安装并启动 Minecraft 基岩版的独立应用。",
  "target": "launcher",
  "enabled": true,
  "entry": true,
  "label": "基岩版"
}
字段类型说明
namestring插件名,用于列表与提示
versionstring展示用版本号。升级判定不读取该字段,读取的是 APK 的 versionCode
author / descriptionstring展示用信息
targetstring取 "minecraft" 或 "launcher",表示插件装给谁
enabledbool安装后是否立即启用,默认为 true
uistring皮肤标识。填写后按皮肤插件处理
entrybool是否为自带界面插件,此类插件可以没有 files/
labelstring入口名称,用于首页入口与插件列表中的「打开」

entry 为 true 时,启动器通过 getLaunchIntentForPackage 打开插件自身的应用,不读取插件代码。

pages.json ​

顶层有三个数组:pages 为页面,sections 为整块接管版块,entries 为向版块左栏追加条目。

json
{
  "pages": [
    { "id": "home", "title": "基岩版", "blocks": [] }
  ],
  "sections": [
    { "section": "home", "left": "side", "content": "home" }
  ],
  "entries": [
    {
      "section": "download",
      "label": "下载基岩版",
      "page": "bedrock-download",
      "position": "top",
      "display": "content"
    }
  ]
}

页面 ​

字段说明
id页面 id。page 动作、sections 与 entries 通过它引用页面
title二级页标题
left字符串数组。提供后在左栏列出,为纯文本,不可点击
blocks积木数组,按数组顺序从上到下渲染
footer贴在底部的积木,不随内容滚动
layout布局名,默认为 scroll

sections ​

sections 用于整块接管某个版块。

json
{ "section": "home", "left": "side", "content": "home" }

section 取 home、download、link、setup 或 other。left 与 content 各指向一个页面 id,两者都可以省略,省略时沿用启动器原有的页面。

sections 是整块替换。接管某个版块后,该版块原有的左栏不再显示,entries 向同一版块添加的条目也不会出现,因此两者对同一版块互斥。

接管只在插件模式下生效,即首页选中该插件时。

entries ​

entries 用于向版块左栏追加一个条目。

json
{
  "section": "download",
  "label": "下载基岩版",
  "page": "bedrock-download",
  "position": "top",
  "display": "content"
}
字段说明
section条目加入哪个版块的左栏
label条目文字
page点击后显示的页面
positiontop 紧跟第一个系统条目,与原版游戏并列;end 追加到末尾,为默认值
displaycontent 画在右侧主栏;page 打开二级页,为默认值

entries 不受插件模式限制。插件安装后条目即显示。

可用积木 ​

type关键字段说明
titletext段落标题,加粗并大一号
texttext、muted正文。muted: true 时使用次要色
cardtitle、blocks卡片容器,可以嵌套
rowblocks横排,子元素等宽
buttontext、action、primary、height按钮。primary: true 为高亮主按钮
switchtext、checked、action开关。状态只在本次停留期间有效
divider无分割线
spaceheight竖向留白,单位为 dp,取值 0 至 200
statuspackage、text显示指定应用的安装状态,如「已安装 v1.21.90」或「未安装」。回到前台时自动刷新
iconresource、size引用 assets/zplugin/res/ 下的图片
version_collection见下文数据通道由插件提供数据的版本列表,启动器以原生样式渲染

可用动作 ​

type字段行为
hinttext在底部显示一条提示,3 秒后消失
pageid打开同一份 pages.json 中的另一页
sectionvalue切换到内置版块,取 home、download、link、setup 或 other
launch无打开本插件的界面,即拉起插件自身的 Activity
openurl用系统浏览器或应用商店打开链接
copytext复制到剪贴板并提示
install无让用户选择一个本地 APK,交给系统安装器处理,不需要存储权限
apppackage启动另一个已安装的应用
app_infopackage打开系统的应用信息页

只有上表中的 9 种动作会被执行,其余类型直接忽略。

json
{
  "type": "button",
  "text": "启动",
  "primary": true,
  "action": { "type": "app", "package": "com.example.app" }
}

数据通道 ​

页面是静态数据,无法得知此刻有哪些版本。需要动态数据时,使用 version_collection 积木,并由插件在自身应用中实现 ContentProvider 提供数据。

xml
<provider
    android:name=".PluginProvider"
    android:authorities="${applicationId}.pclplugin"
    android:exported="true" />

authorities 必须是 <包名>.pclplugin,否则启动器找不到该 Provider。

启动器按以下方式调用,arg 可以传空字符串:

kotlin
val bundle = contentResolver.call(
    Uri.parse("content://<插件包名>.pclplugin"), method, arg, null
)
val json  = bundle?.getString("json")     // 成功
val error = bundle?.getString("error")    // 失败,原样显示给用户

积木声明如下:

json
{
  "type": "version_collection",
  "title": "版本列表",
  "method": "list",
  "detail_method": "details",
  "groups": ["正式版", "预览版"],
  "group_icons": { "正式版": "pcl_block_grass", "预览版": "pcl_block_command_block" },
  "options": [
    { "value": "v8a", "label": "ARM64" },
    { "value": "v7a", "label": "ARM32" }
  ]
}

method 返回版本列表:

json
{
  "items": [
    {
      "id": "1.21.90",
      "title": "1.21.90",
      "subtitle": "2025-06-10 · 620 MB",
      "group": "正式版",
      "latest": true
    }
  ]
}

id 为必需字段且必须唯一。group 对应 groups 中的名字。latest 为 true 时标注「最新」。

detail_method 返回下载源。调用时 arg 为两行文本,第一行是版本 id,第二行是选项的 value。

json
{
  "items": [
    { "title": "夸克网盘", "url": "https://pan.quark.cn/s/xxxx", "password": "a1b2" },
    { "title": "123 云盘", "url": "https://www.123pan.com/s/xxxx" }
  ]
}

返回内容有三条约束:

  • url 必须以 http:// 或 https:// 开头,否则该条目被丢弃
  • 含 password 的条目显示为「提取码 xxx」,选中时先自动复制,再打开链接
  • 返回空数组表示没有可用源,页面显示「没有可用的下载源」

启动器只发起这两种调用,也只渲染返回的条目。它不内置任何下载源,也不识别具体站点。

安装与升级 ​

行为说明
安装来源设备上装有带 assets/zplugin/ 的 APK 时自动识别;也可在插件管理中选择 APK 文件
存储位置<外部 files>/plugins/<id>/,内含 plugin.apk、meta.json、files/ 与 pages.json
启用与停用停用只改变状态,不删除文件。pages.json 仅在启用时加载
升级下次扫描发现 versionCode 变化时重新解包,页面与素材一并更新
页面刷新进入首页时重新读取 pages.json,无需重启启动器

升级时 versionCode 必须递增。 只修改 plugin.json 中的 version 而 versionCode 不变时,启动器视为同一版本,不会重新解包,界面停留在旧配置。

最小示例 ​

assets/zplugin/plugin.json:

json
{
  "name": "示例插件",
  "version": "1.0.0",
  "target": "launcher",
  "entry": true,
  "label": "示例"
}

assets/zplugin/pages.json:

json
{
  "sections": [{ "section": "home", "content": "home" }],
  "pages": [
    {
      "id": "home",
      "title": "示例",
      "blocks": [
        { "type": "title", "text": "示例插件" },
        { "type": "status", "package": "com.example.app", "text": "安装状态" },
        { "type": "space", "height": 8 },
        { "type": "button", "text": "启动", "primary": true,
          "action": { "type": "app", "package": "com.example.app" } },
        { "type": "button", "text": "打开插件界面", "action": { "type": "launch" } }
      ]
    }
  ]
}

把这两个文件放入 assets/zplugin/,打包签名后安装,首页会出现「示例」入口,点击后进入该页面。

问题排查 ​

症状可能原因
提示「不是有效的插件 APK」APK 中缺少 assets/zplugin/plugin.json。旧的资源包不视为插件
已安装但首页没有入口entry 未填写,或 label 与 name 为空,或插件已停用
界面未更新versionCode 未递增,未重新解包;或该版块已被 sections 接管
页面空白sections 或 entries 指向的页面 id 在 pages 中不存在
版本列表持续加载Provider 的 authorities 不是 <包名>.pclplugin,或返回的 Bundle 中没有 json
提示「插件没有返回数据」Provider 返回了 null Bundle,或错误信息写入了 json 而非 error
下载源列表为空url 不是 http 或 https,或返回结构不是 {"items":[...]}

接口状态与版本 ​

插件可以依赖的接口分为两类。标注「稳定」的属于正式契约,改名会随大版本进行;标注「试验」的当前可用,但字段细节可能调整。

接口起始版本状态
plugin.json 清单1.4.0稳定
pages 页面(footer、layout 除外)1.4.0稳定
pages[].footer 与 pages[].layout1.4.0试验
sections 整块接管版块1.4.1稳定
entries 左栏追加条目1.4.1稳定
entries[].display = content1.4.3稳定
积木 9 种(icon、version_collection 之外的 9 种)1.4.0 至 1.4.2稳定
icon 与 version_collection 积木1.4.0 至 1.4.2试验
动作 9 种1.4.0 至 1.4.1稳定
button.primary 主按钮1.4.1稳定
status 按包名显示安装状态1.4.1稳定
版本列表 method1.4.2试验
下载源 detail_method1.4.2试验
错误返回 error1.4.2试验

启动器的内部实现不属于接口,包括 PclUiRuntime、渲染器、皮肤字段与 plugins/<id>/ 的目录布局,不应依赖。

各版本开放的接口:

启动器新增的开放接口
1.4.0清单、页面、基础积木与动作
1.4.1launch、status、open、copy、install、app、app_info 动作,以及 sections、entries、primary 与页面热加载
1.4.2version_collection 积木与 ContentProvider 数据通道
1.4.3entries[].display = content
1.4.4下载源原生选择,数据契约不变
1.4.5entries 支持 setup 版块
1.4.6升级重解包,属行为修复

能力边界 ​

启动器不加载插件代码,插件也拿不到启动器的进程内数据。

启动器不绑定 AIDL,不反向调用插件的 Activity,也不向插件传递任何内部对象。

页面能触发的动作仅限于上表所列的 9 种,不包含文件读写,也不包含任意代码执行。

插件能实现什么功能,由插件自身应用决定。启动器只负责发现、拉起与渲染。

协议原文更新后,本页可能滞后。遇到表述不一致时,以官方仓库的 docs/PLUGIN_GUIDE.md 为准。

ZPCL Launcher 是 Zalith Launcher 2 的非官方修改版,遵循 GPLv3 开源协议