KubeJS Client API zh

English | 中文

客户端 API

在 kubejs/client_scripts 中使用 SkillAtlasClient 和 SkillAtlasClientEvents。两者只在物理客户端存在，专用服务器不会加载客户端辅助类。

提示事件

SkillAtlasClientEvents.tooltip('haste', event => {
  event.add(Text.gold('任务提示：可先完成采矿入门'))
})

节点过滤 ID 可以省略。事件提供 player、nodeId、categoryId、level、maxLevel、revision 和 hints。hints 为 true 时是悬浮提示，为 false 时是详情界面。

• event.baseLines 是原提示的只读副本。
• event.add(Component) 追加样式文本：最多 32 行，单行最多 2048 字符，合计最多 16384 字符。
• 把已关闭的事件保存下来再写入会报错。
• 回调报错时保留原提示，并且至少 100 tick 内不再执行该脚本。

追加的行按节点和悬浮/详情两种模式分别缓存，最多 128 项，缓存 20 tick。定义、玩家进度、客户端脚本变化以及断开连接时缓存失效。不提供逐帧绘制，也不会逐帧向服务端查询。提示回调里不能调用 open / focus，只读的提示调用有递归保护。

方法

方法	含义
SkillAtlasClient.isReady()	完整定义和首次玩家进度都已到达
SkillAtlasClient.getLevel(nodeId)	本地同步的等级；未就绪或不存在时为 0
SkillAtlasClient.tooltip(nodeId)	原生完整提示加脚本追加行的只读副本；未就绪、未知或隐藏时为空列表
SkillAtlasClient.open() / open(categoryId)	打开图谱，可指定分类
SkillAtlasClient.focus(nodeId)	打开图谱、切换分类、移动镜头并高亮技能

任务书按钮可以调用 SkillAtlasClient.focus('haste')。

• 本地显式调用会打开图谱并替换当前的任务界面；如果已经打开了图谱，就复用当前界面。
• 还没收到定义或首次进度时，只保留最后一个导航请求，等待同步，最多 200 tick。
• 更换连接、断开、客户端脚本重载或超时都会丢弃待办请求。
• 每 5 tick 最多接受一次本地导航。

由服务端发起导航

在服务端任务回调中使用 SkillAtlas.player(event.player).open('mining') 或 .focus('haste')。

1. 请求只发给该玩家。服务端先检查玩家在线、目标存在且可见，并按每玩家 5 tick 节流。
2. 客户端再次校验，并等待所需的定义 revision。
3. 如果玩家正打开其他界面，服务端导航会短暂等待玩家关闭，超时后丢弃。

读取图谱不要求 canEdit，导航也不会强制显示隐藏节点。

服务端返回 detail.state = 'sent' 只表示请求已发出。客户端本地返回 opened 或 queued。没有界面实际打开的回执。导航包只从服务端发往客户端，只携带受限的动作、ID 和 revision，客户端无法借它上报计点、重置或其他玩家写入。