Skip to content

KubeJS Server API zh

Jump to bottom
hp-1e edited this page Oct 25, 2026 · 1 revision

English | 中文

服务端 API

SkillAtlas 是 kubejs/server_scripts 中的全局绑定。

全局查询

方法 返回
SkillAtlas.player(player) 在线玩家的助手
getRevision() 当前生效定义的版本号
hasNode(id) 节点是否存在
getNode(id) / getCategory(id) / getPool(id) 不可变数据快照，不存在时为 null
getNodeIds() / getNodeIds(categoryId) 全部技能 ID，或某个分类内的技能 ID
getCategoryIds() / getPoolIds() ID 列表
exportDefinition() 当前生效图谱的只读 JSON 快照
validateDefinition(jsonObject) 校验结果，不提交

查询结果不能写回本体。导出结果不包含 JavaScript 函数，也不包含玩家进度。

节点属于互斥组时，节点快照中带有 choice_group 字段。

玩家助手

// player 必须是当前在线的服务端玩家，例如事件中的玩家。
const p = SkillAtlas.player(event.player)
方法 含义
getLevel(nodeId) 当前等级
hasSkill(nodeId) / hasSkill(nodeId, minLevel) 是否至少达到 minLevel 级，默认 1
isMaxed(nodeId) 是否满级
getLearnedSkills() ID → 等级的快照
getPoints(poolId) 点数池余额，最大 1000000000000
getProgress(poolId) unitsText、targetText、awardedText、limit、unit；大整数以文本返回
getRawExperience() 实际经验总量，不是经验等级
checkLearn(nodeId) 检查下一等级能否学习，detail 是该级费用与奖励的快照
getLearningQuote(nodeId) 当前服务端报价、条件结果、额外奖励说明与状态的只读快照
canLearn(nodeId) 原生检查是否通过，不运行 beforeLearn
learn(nodeId) 正常学习一级，沿用本体的校验、付款、奖励和同步
addPoints(poolId, amount, reason) 增加余额，不占自然行为的发放上限
spendPoints(poolId, amount, reason) 扣除余额，不足时整体失败，不记入技能付款账本
setPoints(poolId, value, reason) 设置余额，不清除累计余量和已发放数
grant(nodeId, targetLevel) 免费管理授予，保留本体逐级命令奖励；向下降级时按账本退款
reset({scope:'all'}) 重置全部已定义技能
reset({scope:'category', id:'mining'}) 重置某个分类内的技能
reset({scope:'node', id:'haste'}) 只重置指定节点
addProgress(poolId, units, reason) 按池的单位上报行为进度，经过事件和原生发放上限
emitAcquisition(typeId, payload, units) 按已注册类型筛选并结算外部行为
resetAcquisition(poolId) / resetAcquisition() 清除指定池或全部池的行为累计与发放额度
open() / open(categoryId) 让该玩家的客户端打开图谱
focus(nodeId) 让该玩家的客户端打开图谱并定位技能

返回结果

写入方法返回的结果包含 ok、code、本地化的 message 和 transactionId，并按操作附带 actualDelta、oldLevel、newLevel、detail。

图谱不存在、参数非法等编程错误，在部分查询和构建器中会直接抛出异常，并非所有错误都会包装成结果对象。

checkLearn / learn 常见的结果代码：ok、unknown_node、max_level、prerequisite、choice_excluded（被互斥组锁定）、insufficient_points、insufficient_experience、insufficient_items、condition_failed、script_error。在其他操作进行中写入会返回 reentrant_operation。

学习相关说明

  • checkLearn 不运行 beforeLearn。它会运行自定义条件、说明和纯计算的 learningCost 报价，并检查本体条件、动态资源费用和可见性。
  • learn 使用冻结的报价，并重新验证条件与资源。查询通过不代表下一瞬间一定能付费成功。
  • 点数、物品、经验不足按本体顺序报告，不保证一次列出全部缺项。
  • getLearningQuote 不会给客户端预留可提交的令牌。脚本直接调用 learn 即可。

点数与退款说明

  • 用 spendPoints 扣掉的点数在洗点时不会退还。
  • 退款按实际支付的货币和数额计算，不按当前标价。免费授予不产生退款。
  • 已交付的物品和已执行的一次性命令不会撤销。
  • 洗点后重新付费学习会再次触发 learned。只允许领一次的奖励需要脚本自己用持久标记去重。

外部模组行为

在 acquisitionTypes 中注册类型（见自定义类型），把点数池绑定到该类型，然后在所接入模组真实的 KubeJS 服务端事件回调中上报：

SkillAtlas.player(event.player).emitAcquisition('pack:machine', { machine: 'press' }, 1)

上报依次经过 progressing → pointsChanging → pointsChanged，source 为 acquire。reason 和 acquisitionType 是类型 ID，progressing.detail 是本次 payload。

  • actualDelta 是总实发额。
  • detail 是各池的 {poolId, ok, code, actualDelta} 列表。
  • 有池拒绝时 code 为 partial_failure，已经完成的其他池不会回滚。
  • 没有匹配的池时返回成功，实发 0。

资格沿用本体的 COUNT_CREATIVE 配置：默认排除创造和旁观模式，开启配置后允许。FakePlayer 始终排除。addProgress 仍是显式的管理上报入口（source 为 script）。不要对同一个真实行为同时调用两个入口。

清除行为累计

SkillAtlas.player(event.player).resetAcquisition('machine')
SkillAtlas.player(event.player).resetAcquisition()

会清除持久计数、已发放额度和尚未结算的移动缓冲。

  • **保留：**余额、技能等级、付款账本、实际经验和已发放的初始点数。
  • **不会：**补发初始点数，也不会触发虚假的 pointsChanged。

detail 列出 poolId、oldUnitsText、oldAwardedText、discardedPendingText、unitsText='0'、awardedText='0'。清除后该池的发放额度会重新开放，请由整合包自行控制调用时机。

Home · 中文首页

KubeJS (English)

KubeJS（中文）

Clone this wiki locally