--- START OF FILE developer.html --- 开发者 API - UEssential 官方文档

开发者跨插件 API 指南

基于 LLSE 的 ll.export / ll.import 机制，UEssential 向外暴露了 6 个强劲的数据层接口，允许你的插件无缝调用其高精度 TPS 监控、玩家画像库以及“绝对无损”的离线经济支付管线。

📦 快速开始

在您的其他 LLSE 插件（JavaScript）中，您可以使用 ll.import 来引入并在运行时执行这些接口。请注意：为了防止服主在配置文件中关闭了对应的功能模块，调用后务必进行判空处理。

// 导入方式：ll.import("命名空间", "导出函数名")
const getInstantTps = ll.import("UEssential", "getTpsInstant");

if (getInstantTps) {
    let tps = getInstantTps();
    console.log("当前TPS: " + tps);
} else {
    console.log("未安装 UEssential 或接口被禁用！");
}

TPS 监控接口

getTpsInstant
返回: Float | null

获取服务器过去 1 秒钟内的高精度瞬时 TPS（Ticks Per Second）。

  • 参数：无
  • 返回值：当开启 tps 模块时，返回 Float 值（最高 20.00）。被禁用时返回 null。
getTps1Min
返回: Float | null

获取服务器过去 60 秒的平均 TPS 值，非常适合用于你的其他插件来进行长期性能监控或触发清理任务。

  • 参数：无
  • 返回值：返回 1 分钟内的平均 TPS 值。禁用时返回 null。

玩家数据与审计接口

getOnlineTime
返回: Float | null

直接从 UEssential 高性能 KVDB 玩家数据库中获取指定玩家的累积历史游玩时间（哪怕他当前离线）。

  • xuid (String) - 目标玩家的 16 位 XUID。
  • 返回值：返回玩家的总在线时长（单位：分钟）。无记录返回 0，禁用模块则返回 null。
const getOnlineTime = ll.import("UEssential", "getOnlineTime");
let playTime = getOnlineTime ? getOnlineTime("2535421234567890") : 0;
queryPlayers
返回: Array<Object> | null

根据玩家名称的片段模糊搜索玩家画像库。支持匹配当前名称和曾用名记录，可用于自行开发带查水表功能的插件。

  • queryStr (String) - 要搜索的玩家名称片段（不区分大小写，最少需要 3 个字符）。
  • 返回值：包含对象 { xuid, name, onlineTime } 的数组。查无此人返回空数组 []。
isBanned
返回: Boolean | null

对一个玩家身份进行综合的本地黑名单拦截检测（支持多维度模糊匹配拦截）。

  • xuid (String | null) - 玩家 XUID
  • name (String | null) - 玩家游戏内名称
  • ip (String | null) - 玩家连接 IP（接口内部会自动剥离多余端口）
  • clientId (String | null) - 设备的物理特征码
  • 返回值：true 表示命中黑名单，false 表示安全。禁用则返回 null。

当你无法获取全量数据时，缺失的数据可以传入 null 进行空安全检测。

无损跨插件转账管线

transferMoneyApi
返回: Boolean

核心重磅接口：为指定玩家增加或扣除资金。它完美抹平了底层 LLMoney 与“原版计分板”经济机制上的差异。如果使用计分板且玩家不在线，该接口会自动将你的操作推入离线结算队列，当玩家下次上线时自动扣除或发放，绝不丢单！

  • targetXuid (String) - 目标玩家的 XUID (必填)。
  • targetName (String | null) - 目标玩家名称。若无法提供可传 null，仅用于离线挂账日志。
  • amount (Number) - 金额。正数表示增加款项，负数表示扣除款项。
  • note (String) - 资金变动备注留言（玩家上线时会在屏幕中央展示此留言）。
  • senderIdentity (String) - 发起方名称标识（例如你写的插件的英文名）。
const ecoTransfer = ll.import("UEssential", "transferMoneyApi");

// 【示例】 - 商店插件的离线或在线扣款（扣1000）：
if (ecoTransfer) {
    let success = ecoTransfer("253542...", "Steve", -1000, "购买钻石剑", "MyShop");
    if (!success) console.log("在线扣费失败：玩家余额不足");
}

处理在线玩家的扣款（负数）时，如果其余额不足，接口将严格拦截并返回 false。但如果是针对“离线玩家”进行计分板扣费，由于无法凭空读取离线计分板，将会直接塞入强制扣费列队（可能会导致他上线时分数变为负数）。

开发者注意事项

1. 模块开关检测：因为服主极有可能在 config.json 中关闭了某些非必需模块（如关闭了数据库或TPS模块），这会导致接口方法虽然被导入成功，但在执行时直接返回 null。务必在你的逻辑中进行非空（Null Safety）校验，否则可能引起你的插件崩溃。

2. 极速响应与无阻塞：绝大多数 API 直接从 UEssential 内存状态或底层的高性能 KVDatabase 读取数据，耗时在亚毫秒级别，属于同步即时响应，可放心在诸如 onTick 或其他高频交互事件中使用。