怎么写插件

这份文档说明 QCL-CE 插件是什么、怎么打包、怎么提交。看完你应该能自己做一个。

先说最重要的一条

QCL-CE 没有插件运行时 —— 没有 DexClassLoader、没有沙箱、没有权限模型。

所以插件只能是资源：控键布局、界面排版。不能是代码。

包里出现 .dex / .jar / .so 一律拒装。

1. 两种插件

type是什么装到哪
control 一整套控键布局（按钮位置、大小、颜色） <应用内部>/control/<名称>/
layout 界面排版（哪个控件显示、什么顺序、多大） SETTING_DIR/qcl_layout.json

2. 包的结构

my-plugin-1.0.0.zip
├── plugin.json          # 清单，必须在 zip 根
└── my-plugin/           # 唯一的一个目录，名字 == plugin.json 的 target
    └── ...              # 按 type 不同，见下

三条硬规则

  1. zip 根只能有 plugin.json 一个文件 + 恰好一个目录。
  2. 那个目录的名字必须等于 plugin.json 里的 target。
  3. 目录名允许中文（control 类型时它就是布局名）。

为什么这么定：启动器里已有的「控键布局 → 导入」流程会解压 zip、 取第一个目录当布局名，并要求它等于 info.json 的 name。 照这个结构打包，同一个 zip 既能被市场一键装，也能被老流程手动导入。

plugin.json 字段

{
  "id": "control-bigbtn",          // 唯一标识，小写+连字符
  "name": "大按钮 · 易按",           // 显示名
  "version": "1.0.0",              // 语义化版本
  "type": "control",               // control | layout
  "target": "大按钮",               // zip 里那个目录的名字
  "author": "你的名字",
  "description": "一句话说明它改了什么",
  "license": "CC-BY-4.0"
}

3. control 类型怎么做

不要手写 info.json

控键布局的字段不少（每个按钮的坐标、尺寸、图标、映射的按键……）， 手写很容易错。

正确做法：在启动器里调好一套布局 → 「设置 → 控键布局」→ 导出 → 把导出的那个目录原封不动放进 zip 的 target/ 里。

这样格式一定对，因为就是启动器自己写出来的。

my-plugin-1.0.0.zip
├── plugin.json
└── 大按钮/
    ├── info.json          # 从启动器导出，别改结构
    ├── <布局1>.json
    ├── <布局2>.json
    └── ...

4. layout 类型怎么做

这个类型最简单：只要一个 qcl_layout.json，格式和启动器自己存的一样。

怎么拿到：在启动器里长按页面进编辑模式 → 改完保存 → 「插件页 → 界面 → 排版导入 / 导出」→ 复制到剪贴板 → 粘到文件里。

格式

{
  "main": {                          // 页面 id
    "launcher_play_button": {        // 控件 id（Android 里的 R.id）
      "order": 0,                    // 同层排序权重，小的在前
      "visible": true,               // false = 隐藏（GONE，不占位）
      "w": 0,                        // 宽度覆盖（px）；0 = 不改
      "h": 0                         // 高度覆盖（px）；0 = 不改
    }
  }
}

可用的页面 id

pageId页面pageId页面
main主页download下载
version_list版本列表setting设置
account账号game_manager游戏管理
lobby大厅lab实验室
backup备份diagnostic启动诊断
download_resource资源下载plugin插件
multiplayer联机

控件 id 怎么找

就在上面那个导出的 JSON 里 —— 启动器导出时写的就是真实控件 id。

想只留几个控件时，把不想要的那几条删掉即可（没写的控件按 XML 原样显示）。 想隐藏某个控件，写 "visible": false，别删它。

5. 怎么提交

到 QCL-Plugins 的 Issues 开一个，标题写：

【插件投稿】你的插件名 v1.0.0

正文里给这几样，缺一样就没法上架：

要给的说明
插件 zip按上面结构打好包的文件（直接拖进 issue 或给网盘链接）
sha256zip 的哈希，用来防篡改。命令见下
名称 / 版本和 plugin.json 里一致
一句话说明它会改变什么（会显示在市场和 App 里）
标签2~4 个，比如「控键 大按钮 易用」
适用启动器版本最低 versionCode。不确定就写 20004

怎么算 sha256

# Windows (PowerShell)
Get-FileHash .\my-plugin-1.0.0.zip -Algorithm SHA256

# macOS / Linux
shasum -a 256 my-plugin-1.0.0.zip

审核会看什么

6. 几个实用建议