KubeJS Events zh

English | 中文

事件

所有服务端事件都在 SkillAtlasEvents 事件组中，用于 kubejs/server_scripts。

事件列表

事件	可取消	过滤 ID	用途
definitions	可以拒绝整份新定义	无	用暂存构建器覆盖基础图谱
conditionTypes	可以拒绝整份新注册	无	注册带校验、检测与说明的条件类型
rewardTypes	可以拒绝整份新注册	无	注册一次性奖励与可撤销的持续奖励
acquisitionTypes	可以拒绝整份新注册	无	注册外部行为获取类型
learningCost	是	技能 ID	计算下一等级的费用报价
beforeLearn	是	技能 ID	正常学习最终扣费前增加门禁
learned	否	技能 ID	正常学习提升了一级，原生奖励已处理
learnFailed	否	技能 ID	原生实际学习失败；查询不会触发
beforeReset	是	单节点重置时的节点 ID	重置前检查；批量重置用无过滤监听
reset	否	同上	重置与账本退款完成
pointsChanging	是	点数池 ID	独立余额操作或自然发点前调整数额
pointsChanged	否	点数池 ID	余额实际变化后观察
progressing	是	点数池 ID	匹配后的 Skill Atlas 行为累计
levelChanged	否	技能 ID	学习、授予、重置、定义修正导致等级变化
reloaded	否	无	启动或重载成功，可以查询当前有效图谱
reloadFailed	否	无	定义解析或脚本覆盖失败

无过滤监听：

SkillAtlasEvents.learned(event => { /* ... */ })

只监听某个 ID：

SkillAtlasEvents.learned('haste', event => { /* ... */ })

一次正常学习只触发一次 learned。管理授予和重新登录时的刷新不会触发。

取消

• 用 event.cancel() 取消。
• beforeLearn 等决策事件还提供 event.deny(Text.red('原因'))。
• 提交前抛出的异常按拒绝处理。
• 提交后抛出的异常会保留已经发生的结果，不能靠报错回滚外部物品或指令。

公共字段

按事件提供：player、server、source、reason、transactionId、revision、nodeId、poolId、categoryId、oldLevel、newLevel、detail。

• 定义生命周期事件中 player 为 null。
• 不要把空的 nodeId / poolId 当成真实 ID。

学习事件

学习事件带有下一等级的 cost 快照。在 beforeLearn 里修改 cost、newLevel 等展示字段不会改变实际交易。动态价格请用 learningCost。

beforeLearn 增加的临时门禁不会出现在客户端预览中。如果要让玩家提前看到条件，请注册条件类型并挂到节点或等级上。

被互斥组锁定的节点，会在 beforeLearn 之前的原生检查中失败，失败代码为 choice_excluded。

重置事件

重置事件提供 affectedNodes 和 refund。

• beforeReset 中的 refund 是根据付款账本得出的预览。
• reset 中的 refund 是实际的原生返回结果。

重置只处理明确指定的节点，不会自动连带后继节点。删除节点或降低最高等级导致的强制修正不能被 beforeReset 阻止。

点数

pointsChanging 中 delta 可以修改，另有 oldPoints、newPoints、requestedDelta 可供参考。修改后必须是合法整数，不能把发点改成扣点，反之亦然。pointsChanged 提供实际变化量 actualDelta 和新余额。

source 的取值：

来源	含义
learn	正常学习
reset	洗点
script	脚本余额操作
command	原生命令或管理授予
acquire	自然行为
definition_change	定义修正
login	登录时发放初始点数

学习付款、洗点退款、初始点数和定义修正不经过可取消的 pointsChanging，只在变化后触发 pointsChanged。所以不要把所有正值的 pointsChanged 都算作自然奖励。

行为累计

取消 progressing 只取消本模组的行为累计，不会撤销已经发生的破坏、击杀、收获或钓鱼。事件提供 poolId、acquisitionType、可修改的 units 以及 unit（count、seconds 或 centimeters）。它不会伪造缺失的方块、物品或实体上下文。如需额外筛选，可以在 KubeJS 原有事件中决定是否调用 addProgress。

• 自然获取仍受原有匹配、创造模式/FakePlayer 排除和发放上限限制，倍率在约束上限之前结算。
• 发点被拒绝或为零时保留待领取余量，不增加已发放数。余额已满也不会吞掉这一轮的累计。
• 移动按玩家和点数池汇总，每 20 tick 发布一次。不足阈值的余量会保留，玩家退出和服务器停止前会冲刷待结算量。
• 取消一个池不会影响同一行为匹配到的其他池。

重入保护

同一玩家正在学习、重置、授予、发点或派发提交后事件时，通过玩家助手再次写入会返回 reentrant_operation。需要后续操作时，请显式安排到下一 tick，并使用不同的 source，避免循环发点。