Python 🎉Economy适用于LumenBridge的经济转换插件！ 1.0.0

[MD]# Economy 统一经济插件 使用文档 ## 一、插件简介 Economy 是 LumenBridge 的**统一经济服务子插件**。它把底层各种经济实现翻译成同一套 API，发布到框架共享变量池，供其他子插件（如 picture_rank 统计签到）统一调用： ``` UMoney / ARC Core / JsonMoney / 记分板 / 自定义提供器 │ 来源适配层（全部收在本插件内） ┌───────┴───────┐ │ economy 子插件 │ get_balance / change_balance └───────┬───────┘ lumen.env["economy_provider"]（共享变量池） │ picture_rank 等业务子插件（用时获取） ``` **核心特性**： - 5 种经济来源可切换：UMoney / ARC Core / JsonMoney / 记分板（objective）/ 自定义提供器（`env: rank3_money_provider`） - WebUI 下拉切换经济来源，改完**即时生效**，无需重启 - 两个 API 均可在任意线程安全调用（内部自动经 `call_on_main` 桥接到 Endstone 主线程执行；主线程内调用则直接同步执行，零调度开销） - 内置余额不足校验、金额上限（10 亿）、四舍五入规则与各来源兼容调用方式 - 支持热重载：卸载时自动置空共享池引用，重载后业务插件自动拿到新实例 ## 二、环境要求 | 项目 | 要求 | |---|---| | LumenBridge | ≥ 1.0.0，且为包含 `call_on_main` 的构建（框架源码已修补，重新构建 whl 后即可） | | 经济插件（可选其一） | UMoney / ARC Core / JsonMoney 任一，或使用记分板模式（无需额外插件） | | Python 依赖 | 无 | ## 三、安装方法 ### 方法 1：插件市场安装 1. 打开 WebUI 管理面板，进入「插件市场」页面（若未开启，先在 WebUI 设置中开启市场功能并配置市场地址） 2. 在搜索框输入 `economy` 3. 在搜索结果中找到本插件，点击进入详情页 4. 点击「安装」，等待下载完成（市场安装自动校验 SHA-256 并处理 pip 依赖） 5. 安装完成后在「子插件」页面确认 economy 已启用 ### 方法 2：上传 ZIP 到 WebUI 安装 1. 打开 WebUI 管理面板，进入「子插件」页面 2. 点击「安装子插件」按钮，弹出安装对话框 3. 将 `economy_v1.0.0.zip` 拖入上传区（或点击上传区选择文件） 4. 等待上传进度完成，框架会自动校验清单、安装依赖并加载插件 5. 也可以使用对话框中的「或从链接安装」，填入 ZIP 下载直链（如 `https://test.huang1111.cn/f/xxxx/economy_v1.0.0.zip`）安装 > 注意：WebUI 上传安装对**同名插件要求更高版本号**才能覆盖升级；全新安装无此限制。 ### 方法 3：手动解压到子插件文件夹安装 1. 关闭服务器 2. 解压 `economy_v1.0.0.zip`，得到 `economy/` 文件夹（内含 `main.py` 与 `lumen.json`） 3. 将 `economy/` 文件夹放入 BDS 的子插件目录： ``` plugins/lumenbridge/plugins/economy/ ├── main.py └── lumen.json ``` 4. 启动服务器，控制台出现 `Economy 统一经济服务已加载` 即安装成功 ## 四、配置说明 安装后通过 WebUI「子插件」→ economy → 配置进行设置： | 配置项 | 说明 | 默认值 | |---|---|---| | 经济来源 | 所有依赖本服务的子插件共用的经济数据来源，切换后立即生效 | UMoney | | UMoney 插件名 | UMoney 插件在服务器的注册名 | umoney | | ARC Core 插件名 | ARC Core 插件在服务器的注册名 | arc_core | | JsonMoney 插件名 | JsonMoney 插件在服务器的注册名 | ye111566-jsonmoney | | 记分板项目名 | 记分板模式读取的 objective 名称 | money | **各来源说明**： - **UMoney**：调用 `api_get_player_money` / `api_change_player_money`，支持离线玩家查询，仅支持整数金额 - **ARC Core**：自动兼容新旧参数签名，支持离线玩家查询，保留两位小数 - **JsonMoney**：优先插件实例方法，其次数据 API，最后兜底直接读写 `plugins/money/money.json` - **计分板**：读取指定 objective，需玩家在线；写入为整数 - **自定义提供器**：从共享变量池取 `rank3_money_provider`（只读，不支持加/扣钱） ## 五、对外 API（供其他子插件开发者使用） ```python provider = lumen.env.get("economy_provider") if provider is not None: # 查询余额：返回 float；来源不可用/玩家无效时返回 None balance = provider.get_balance("Steve") # 增减余额：正数增加、负数扣除 # 返回 (成功: bool, 错误信息: str) ok, error = provider.change_balance("Steve", 100) ``` 使用要点： - **每次使用时重新 `env.get()`**，不要缓存引用——economy 热重载后自动拿到新实例 - 两个 API **任意线程可安全调用**（OneBot 线程、WebUI 线程、MC 主线程均可） - 查询失败返回 `None` 时，调用方应保留自己的最近一次持久化余额 ## 六、更新与卸载 - **更新**：WebUI「子插件」→ economy → 更新，上传版本号更高的 ZIP（或手动替换文件夹后重启） - **卸载**：WebUI「子插件」→ economy → 卸载；卸载时自动置空 `env["economy_provider"]`，依赖它的业务插件会优雅降级（余额类功能退化为各自持久化的最近值） ## 七、常见问题 **Q：切换经济来源后需要重启吗？** 不需要，WebUI 保存配置后立即生效。 **Q：经济插件没装/注册名填错会怎样？** 不会崩溃。读取返回 `None`（调用方保留旧值），控制台**每种问题只告警一次**，修复配置后自动恢复。 **Q：picture_rank 提示「economy 统一经济服务未启用」？** 说明 economy 子插件未安装或未启用。先安装启用本插件，无需重启 picture_rank（它每次使用时实时获取）。 **Q：扣钱时余额不足会怎样？** `change_balance` 返回 `(False, "余额不足（当前 xx 金币）")`，不会写入负数。[/MD]