插件开发者文档

1. 能力边界（先看这个）

UI 插件可深度换肤，但不能改系统桌面图标、系统字体、游戏内 UI，也不能替换布局 XML。 推荐一把梭：features.customTheme: true + theme 对象。

2. 手把手：做一个真正会生效的问候语插件

1在电脑建目录

D:\plugins\my-greeting\
└── booxin-plugin.json

文件名必须恰好是 booxin-plugin.json（全小写，中间是连字符）。

2写入以下内容（可原样复制）

{
  "id": "my-greeting",
  "name": "按时段问候",
  "version": "1.0.0",
  "type": "ui",
  "description": "启用后主页显示早上好/中午好/晚上好。禁用后恢复默认欢迎语。",
  "features": {
    "homeGreetingByTime": true
  }
}

3打 zip（结构必须对）

my-greeting.zip
└── booxin-plugin.json

my-greeting.zip
└── my-greeting/
    └── booxin-plugin.json

Windows 资源管理器：进入 my-greeting 文件夹 → 选中 booxin-plugin.json → 右键 →「发送到」→「压缩(zipped)文件夹」→ 改名为 my-greeting.zip。

PowerShell（推荐，结构更稳）：

cd D:\plugins\my-greeting
Compress-Archive -Path .\booxin-plugin.json -DestinationPath ..\my-greeting.zip -Force

也可用官方工具一键打包：文末 附录 · Booxin Studio （前往下载）。 推荐双击 BooxinStudio.exe 用微型 IDE「一键打包」；命令行则用 BooxinStudio-CLI.exe pack 插件目录。

不要用加密 zip、7z、rar、分卷包。客户端只按 zip 解。

4装进启动器后怎么验证

1. 手机打开 Booxin → 底部「插件」。
2. 左侧点「本机插件」（商店装完会自动切过来；ADB 推送则手动点）。
3. 应看到名称「按时段问候」，详情类似：ui · 已启用 · v1.0.0。
4. 再点底部「主页」。欢迎语应变成：
   • 0:00–10:59 → 早上好
   • 11:00–16:59 → 中午好
   • 17:00–23:59 → 晚上好
5. 回「本机插件」点「禁用」→ 再回主页 → 应恢复「欢迎使用 Booxin」。

3. UI 插件：清单字段与安装目录（具体）

3.1 安装落盘位置

/data/data/com.booxin.launcher/files/booxin-runtime/ui-plugins/<id>/
├── booxin-plugin.json
├── .ready                 ← 安装成功时写入时间戳
├── .disabled              ← 仅禁用时存在；删除即启用
└── （zip 里其它文件会一并解压到这里）

• 包名以实际安装为准：正式包一般为 com.booxin.launcher。
• <id> 来自清单 id；非法字符 \ / : * ? " < > | 会被替换成 _。
• 相同 id 再安装：先删整个旧目录再写入（覆盖更新）。

3.2 客户端实际读取的字段

3.3 清单放置位置

• 优先：zip 根目录 booxin-plugin.json。
• 也支持：任意子路径，只要条目名以 booxin-plugin.json 结尾（例如 pkg/booxin-plugin.json）。
• 若清单在 pkg/ 下，解压时会去掉 pkg/ 前缀，使文件落到安装根目录。

3.4 完整主题包示例（推荐）

{
  "id": "demo-full-theme",
  "name": "Full Theme Pack",
  "version": "1.0.0",
  "type": "ui",
  "description": "品牌 + 配色 + 壁纸 + 字体 + 图标",
  "launcherIcon": "icon.png",
  "font": "fonts/MyFont.ttf",
  "features": {
    "customTheme": true,
    "homeGreetingByTime": true
  },
  "theme": {
    "brandName": "MyLauncher",
    "welcome": "欢迎回来",
    "welcomeMorning": "早上好",
    "welcomeNoon": "中午好",
    "welcomeEvening": "晚上好",
    "backgroundImage": "backgrounds/bg.png",
    "backgroundVideo": "backgrounds/loop.mp4",
    "backgroundAlpha": 0.85,
    "colors": {
      "primary": "#449AD8",
      "accent": "#FF8A2B",
      "text": "#F2F6FF",
      "textSecondary": "#B4C0D4",
      "rim": "#88FFFFFF",
      "glassPrimary": "#CC2A6FA8",
      "surface": "#141A26",
      "navSelected": "#FFFFFF",
      "navUnselected": "#B4C0D4"
    },
    "nav": {
      "home": "主页",
      "versions": "版本",
      "community": "社区",
      "multiplayer": "联机",
      "ai": "AI",
      "pluginStore": "插件",
      "settings": "设置"
    }
  }
}

demo-full-theme.zip
├── booxin-plugin.json
├── icon.png
├── fonts/MyFont.ttf
└── backgrounds/
    ├── bg.png
    └── loop.mp4

3.5 操控布局接口（贴图 + CSS JSON 绘制）

目录结构示例：

my-control-pack/
├── booxin-plugin.json
├── control_layout.json
└── assets/
    └── btn.png

booxin-plugin.json：

{
  "schema": 1,
  "id": "my-control-pack",
  "name": "My Control Pack",
  "version": "1.0.0",
  "type": "control",
  "features": { "controlLayout": true },
  "layoutFile": "control_layout.json"
}

布局文件候选（相对安装目录，声明优先）：

• layoutFile（清单字段）
• control_layout.json / layout.json / controls.json / assets/control_layout.json

buttons[] 主要字段：

kind 行为：

• KEY_TAP：抬起点击一次
• KEY_HOLD / MOUSE_HOLD：按住；手指滑出按钮后交给触控板转视角
• KEY_FOLLOW / MOUSE_FOLLOW：按住时按钮跟手移动并保持按下，松开回弹原位
• SOFT_KEYBOARD：切换软键盘；布局未写时启动器会自动补一个，用户拖动位置会记住
• SCROLL：滚轮（code ≥0 为上）

joystick.follow（默认 true）：按下时轮盘移到指下，拖出外圈底盘追手，松开回弹；编辑时可点选轮盘后用「跟手」开关。

启用操控插件后，用户在游戏内拖动的按键/轮盘/软键盘位置会写入本机并与插件合并（插件管贴图样式，本机覆盖坐标），避免每次重置。

布局级默认样式：buttonStyle / buttonCss（结构同单键 style）。

绘制优先级：icon 贴图 → style/css → 默认圆形底。

buttons[].icon 规则：

• 相对本插件安装目录，例如 assets/btn.png
• 扩展名：png / webp / jpg / jpeg
• 禁止绝对路径、禁止路径含 ..；解析结果必须落在插件目录内
• 多个已启用的 controlLayout 包时，只取扫描到的第一个

style / css 字段：

control_layout.json 片段：

{
  "version": 4,
  "buttonStyle": {
    "shape": "oval",
    "backgroundColor": "#AA2A6FA8",
    "borderColor": "#88FFFFFF",
    "borderWidth": 2,
    "textColor": "#FFFFFFFF"
  },
  "buttons": [
    {
      "id": "jump",
      "label": "跳",
      "kind": "KEY_HOLD",
      "code": 32,
      "x": 0.90,
      "y": 0.70,
      "sizeDp": 64,
      "style": {
        "gradient": ["#CCFF8AC8", "#CC88CCFF"],
        "gradientOrientation": "tl_br",
        "borderWidth": 2,
        "borderColor": "#FFFFFFFF"
      }
    }
  ],
  "joystick": { "x": 0.13, "y": 0.80, "sizeDp": 150 },
  "floatingBall": { "x": 0.96, "y": 0.38 },
  "gestureQuick": { "x": 0.96, "y": 0.30 }
}

旧客户端无 icon/style 接口时仍可加载布局，只是忽略绘制字段。

4. 问候语 / 图标 / 字体：具体判定规则

4.1 问候语

代码在进入/回到主页时执行（onResume）。判定顺序：

1. 扫描 ui-plugins/*/ 下所有已安装插件。
2. 跳过带 .disabled 的目录。
3. 读取各自清单；任一启用插件的 homeGreetingByTime == true 即生效。
4. 取手机本地时区的小时 HOUR_OF_DAY（0–23）：

• 未启用任何问候语插件时：固定显示「欢迎使用 Booxin」。
• 装了但点了「禁用」：等同未启用。
• 多个插件都开了该 feature：只要有一个启用即可（并集）。

4.2 customLauncherIcon（主页品牌图标）

只替换主页左侧品牌圆标，不会改 Android 桌面上的应用图标。

1. 启用插件且 customLauncherIcon == true。
2. 按名称排序后取第一个找到有效图片的插件。
3. 图片路径优先用清单 launcherIcon（或 icon）；未写则依次尝试： icon.png / icon.webp / icon.jpg / icon.jpeg / launcher-icon.png / assets/icon.png。
4. 找不到可用图 → 回退默认 ic_launcher_round。

{
  "id": "my-brand-icon",
  "name": "自定义主页图标",
  "version": "1.0.0",
  "type": "ui",
  "launcherIcon": "icon.png",
  "features": {
    "customLauncherIcon": true
  }
}

4.3 customFont（界面字体）

只替换启动器 App 内文字（主页、商店、设置、聊天等），不改 Android 系统字体，也不改游戏内字体。 等宽日志区域会保留 monospace。

1. 启用插件且 customFont == true。
2. 按名称排序后取第一个找到有效字体文件的插件。
3. 路径优先用清单 font（或 fontFile）；未写则依次尝试： font.ttf / font.otf / fonts/font.ttf / fonts/font.otf / assets/font.ttf / assets/font.otf。
4. 支持扩展名：.ttf、.otf、.ttc。请确认字体许可允许分发。
5. 启用/禁用/卸载后会立即重刷当前界面；若个别页面未变，切页或回前台即可。

{
  "id": "my-ui-font",
  "name": "自定义界面字体",
  "version": "1.0.0",
  "type": "ui",
  "font": "fonts/MyFont.ttf",
  "features": {
    "customFont": true
  }
}

4.4 customTheme（完整主题包，权限最大）

开 customTheme（或清单里写了 theme 对象）后，同一包还可直接带上 图标 / 字体文件，无需再单独开 customLauncherIcon / customFont。

• theme.brandName：顶栏品牌文字
• theme.welcome*：主页欢迎语（可按时段）
• theme.homeLaunchText / homeSwitchVersionText / homeAccountText：主页按钮文案
• theme.homeStatusText / homeSelectedVersionLabel：主页状态与「当前版本」标签
• theme.hideOrbs：隐藏背景装饰光斑
• theme.colors.*：主色 / 文字色 / 按钮玻璃色 / 导航选中色等（#RRGGBB 或 #AARRGGBB）
• theme.nav.*：顶栏各页文案
• theme.backgroundImage / backgroundVideo：覆盖设置里的内置壁纸
• theme.backgroundAlpha：0~1，默认 0.85
• theme.applyAllText：默认 true，把文字色铺到界面 TextView

插件不能运行任意代码；只能改启动器已接线的这些字段。想加新能力需要发版启动器。

多个主题包同时启用时，按插件名称排序取第一个。

5. 本地自测（不上架）

5.1 ADB 推送 UI 插件

电脑已装 platform-tools，手机开 USB 调试，启动器包名为 com.booxin.launcher：

# 在电脑当前目录放好 booxin-plugin.json

adb shell mkdir -p /data/data/com.booxin.launcher/files/booxin-runtime/ui-plugins/my-greeting

# 无 root 时优先用 run-as（debug 包通常可用；release 可能受限）
adb shell run-as com.booxin.launcher mkdir -p files/booxin-runtime/ui-plugins/my-greeting

adb push booxin-plugin.json /sdcard/booxin-plugin.json
adb shell run-as com.booxin.launcher cp /sdcard/booxin-plugin.json \
  files/booxin-runtime/ui-plugins/my-greeting/booxin-plugin.json

adb shell run-as com.booxin.launcher sh -c \
  "echo $(date +%s) > files/booxin-runtime/ui-plugins/my-greeting/.ready"

然后：打开启动器 → 插件 → 本机插件 → 点「刷新」→ 回主页看文案。

测禁用：

adb shell run-as com.booxin.launcher sh -c \
  "echo 1 > files/booxin-runtime/ui-plugins/my-greeting/.disabled"

测卸载：

adb shell run-as com.booxin.launcher rm -rf \
  files/booxin-runtime/ui-plugins/my-greeting

5.2 渲染器本地导入

1. 启动器 → 插件 → 左侧「本机渲染器」。
2. 点「导入 APK」。
3. 选你的 .apk。
4. 成功后列表出现名称、版本、类型「渲染器」、状态「已安装/已启用」。

UI 插件更省事的新建/打包见文末 附录 · Booxin Studio；渲染器请用本页「导入 APK」。

6. 渲染器 / 驱动：具体打包要求

6.1 APK 内部结构（按这个做）

my-renderer.apk
├── plugin.json                 ← 推荐（也认 assets/plugin.json）
├── AndroidManifest.xml
└── lib/
    ├── arm64-v8a/              ← 真机主流，强烈建议有
    │   ├── libmygl.so          ← 文件名 = glLib
    │   └── （其它依赖 .so）
    └── armeabi-v7a/            ← 可选
        └── libmygl.so

6.2 plugin.json 读写位置

客户端按顺序找：

1. assets/plugin.json
2. plugin.json（APK 根）

都没有时，会按 so 文件名猜（含 gl4es / ltw / angle / OSMesa / mobileglues 等），不稳定，别靠猜。

6.3 推荐完整清单

{
  "id": "my-gl-renderer",
  "name": "My GL Renderer",
  "version": "1.0.0",
  "type": "RENDERER",
  "glLib": "libmygl.so",
  "eglLib": "libEGL.so",
  "rendererToken": "opengles3",
  "libGlEs": "3",
  "kindName": null,
  "disguiseAsGl4es": false,
  "extraEnv": {
    "LIBGL_ES": "3"
  }
}

6.4 ABI 提取顺序（客户端行为）

1. 先按设备 Build.SUPPORTED_ABIS 顺序找 lib/<abi>/*.so。
2. 某个 ABI 解出至少一个 so 就停，不再解其它 ABI。
3. 只解一层文件名（不要 lib/arm64-v8a/subdir/a.so）。
4. 解压后检查是否存在 glLib；没有则尝试在已解压 so 里找近似名并复制改名。

6.5 可选 Manifest 元数据

<meta-data android:name="booxin.plugin" android:value="renderer" />
<meta-data android:name="org.lwjgl.opengl.libname" android:value="libmygl.so" />

用于扫描「本机已安装的第三方渲染器插件 APK」。普通导入本地 APK 主要仍看 plugin.json + so。

7. 商店点「下载安装」时，客户端具体怎么走

下载始终在启动器内部完成（不跳系统浏览器），并自动跟随 HTTP 重定向（短链 / CDN 跳转可用）。

1. 读上架记录的 downloadUrl（空则提示缺少下载链接）。
2. 在 App 内下载文件（支持重定向；最终 URL / Content-Disposition / Content-Type 会参与判断）。
3. 再判定包类型并安装：
   • renderer / driver → 按 APK 装进「本机渲染器」
   • URL/响应头像 .apk，或包内有 AndroidManifest.xml / classes.dex → APK
   • 包内有 booxin-plugin.json，或类型为 UI 类 / 其它未知 → 按 UI zip 装进「本机插件」

短链可以，但最终必须落到可下载的 zip/apk 文件。UI 包务必含 booxin-plugin.json； 渲染器用 renderer/driver。

8. 申请上架：逐步点哪里、填什么

1. 启动器登录联机账号（未登录不能提交）。
2. 底部导航点「插件」。
3. 左侧点「申请上架」（或底部申请按钮，以你版本文案为准）。
4. 第 1 步填：
   • 插件名称：商店显示名，例如「按时段问候」。
   • 类型 / 分区：UI 选「UI 插件」；渲染器选「渲染器」。
   • 简介：写清用途 + 使用步骤 + 能力边界。
5. 第 2 步：上传文件（≤250MB）或填 HTTPS 外链（可只填一种）。
6. 提交成功提示「申请已提交，请等待审核」。
7. 在「我的申请」可看状态：审核中 / 已通过 / 未通过（未通过有原因）。

简介可直接套用

【功能】启用后，主页欢迎语按本地时间显示早上好/中午好/晚上好。
【安装】商店下载安装 → 左侧「本机插件」保持「已启用」→ 回到主页查看。
【关闭】本机插件 → 禁用 或 卸载。
【说明】本插件不会修改主题色；当前版本支持问候语 / 主页品牌图标 / 界面字体。
【包格式】zip，内含 booxin-plugin.json，id=my-greeting。

9. 类型对照表

10. 常见报错 / 现象对照

11. 发布前逐条勾

• UI：zip 内能直接看到 booxin-plugin.json，id 非空
• 问候语：真机验证 启用→主页文案变 / 禁用→恢复默认
• 图标：真机验证 启用→主页左侧圆标变 / 禁用→恢复默认
• 字体：真机验证 启用→界面文字变 / 禁用→恢复默认；确认许可可分发
• 主题包：品牌名、配色、导航/主页按钮文案、壁纸、hideOrbs 至少验证一项可见变化
• 渲染器：arm64-v8a 下存在与 glLib 同名的 so；可用「导入 APK」装上
• 商店 type 与包格式一致；下载链最终能落到 .zip / .apk（可用短链重定向）
• 简介写了「会做什么 / 不会做什么」，不夸大未接线能力
• 更新版本时保持同一 id，只改 version
• 无恶意行为；资源与库许可合规

附录 · Booxin Studio（微型 IDE）

官方插件工具：编辑项目、校验清单、一键打包 zip。绿色包免装 Node（Windows）。 前往下载

包内两个版本

推荐流程（窗口版 2.0）

1. 解压绿色包，双击 BooxinStudio.exe。
2. 主页点「打开项目」或「新建主题包」；也可双击最近历史进入。
3. 在左侧文件树双击编辑 booxin-plugin.json 等文本，按 README 放入资源。
4. 点顶部「一键打包」（或 Ctrl+B），保存 zip。
5. 手机 Booxin →「插件」→ 本机安装或走「申请上架」上传该 zip。

命令行版示例

BooxinStudio-CLI.exe help
BooxinStudio-CLI.exe new theme
BooxinStudio-CLI.exe new theme D:\plugins\cool-theme cool-theme
BooxinStudio-CLI.exe pack
BooxinStudio-CLI.exe pack D:\plugins\cool-theme D:\plugins\cool-theme.zip
BooxinStudio-CLI.exe validate D:\plugins\cool-theme

注意

• zip 根目录必须能直接看到 booxin-plugin.json（不要多套一层空文件夹）。
• 装到手机请用启动器安装 zip；命令里的 push 依赖 run-as，正式版常失败，仅 debug 用。
• 插件只能改启动器已接线的字段，不能运行任意代码；新能力需等启动器发版。

打好的 zip 结构不确定时，先 validate 再上传商店，可少踩「安装失败」。