服务端 UI API 总览

这一页整理服务端接入时最常用的公开调用面。

服务端和客户端怎么分工

• 服务端：模板注册、UI 生命周期、状态权威写入、动作处理器注册。
• 客户端：模板运行、脚本交互、渲染、局部状态、最终视觉组合。
• 两边的桥接靠三条链：
  • sync:* 状态同步
  • command / query / event
  • 客户端异步存储读取

UI 生命周期

方法	作用
open(player, templateId, initialState)	打开 UI，并可附带初始同步状态
close(player, templateId)	关闭指定 UI
closeAll(player)	关闭该玩家全部 UI
hasOpen(player, templateId)	查询某个模板是否已打开
listOpen(player)	查询当前打开模板集合

常见问题：

• initialState 里混写 sync: 和裸 key
• 不做 hasOpen() 判断，重复打开同一模板

模板注册

方法	作用
registerFile(templateId, file, options)	第三方模板注册入口
unregister(templateId, notifyReload)	注销模板
reload(templateId)	重载模板
exists(templateId)	检查模板存在性
source(templateId)	获取模板源码
version(templateId)	获取模板版本
list()	列出全部模板 ID
listRegisteredFiles()	列出 file-only 注册表

TemplateRegisterOptions 里最重要的是：

• notifyReload
• pushUpdate

状态与展示物品

权威同步

方法	作用
setSyncValue(player, storeId, key, value)	写单个同步值
setSyncState(player, storeId, state)	批量写同步值
getSyncValue(player, storeId, key)	读同步值
removeSyncValue(player, storeId, key)	删除同步值

展示物品

方法	作用
setDisplayItem(...)	写单个展示物品
setDisplayItems(...)	写展示物品列表
setDisplayItemMap(...)	写展示物品映射
removeDisplayItem(...)	删除展示物品键

高级入口

setLocalValue()、updateStore()、getRawValue() 能做更多事，但也更容易把 sync: 和本地键搅乱。除非你明确需要 store 级操作，否则优先用前两组 API。

处理器注册

这组 API 默认分三层：

• command()：有副作用
• query()：纯读
• event()：通知 / 上报

统一管理入口包括：

• register
• registerGlobal
• remove
• removeGlobal
• clear
• clearAll

客户端存储读取

这组 API 全部是异步读取客户端 LocalStorage，不要按同步返回值理解。

方法	作用
read(...)	批量读键值
readItem(...)	读任意单值
readString(...)	读字符串
readInt(...)	读整数并带默认值
readDouble(...)	读浮点并带默认值
readBoolean(...)	读布尔并带默认值

一个最小接入链路

fun openRpg(player: Player) {
    if (!BUIServerAPI.template().exists("rpg/main")) return

    BUIServerAPI.ui().open(
        player = player,
        templateId = "rpg/main",
        initialState = mapOf("hp" to 100, "mp" to 50)
    )

    BUIServerAPI.action().command().register("rpg/main", "rpg.skill.cast") { p, _, storeId, _ ->
        BUIServerAPI.state().setSyncValue(p, storeId, "mp", 45)
        mapOf("ok" to true)
    }
}