KubeJS Atlas Builder zh

English | 中文

图谱构建器

在 SkillAtlasEvents.definitions 中使用构建器。脚本修改的是基础图谱（config/skill_atlas/atlas.json）的暂存副本，结果经过完整校验后才会成为生效图谱。

SkillAtlasEvents.definitions(event => {
  event.createNode('pack_harvest_health')
    .name('耕作体魄')
    .category('farming')
    .icon('minecraft:golden_carrot')
    .position(0, 0)
    .level(1, rank => {
      rank.cost({ type: 'skill_points', amount: 1 })
      rank.attributeReward('minecraft:generic.max_health', 2, 'add')
    })
})

事件方法

方法	用途
createNode(id) / createCategory(id) / createPool(id)	新建并返回构建器
modifyNode(id, callback) / modifyCategory(id, callback) / modifyPool(id, callback)	修改已有对象
removeNode(id) / removeCategory(id) / removePool(id)	删除对象
hasNode(id) / getNodeIds() / getSnapshot()	查看暂存图谱

事件回调结束后构建器会关闭。如果把构建器留到之后再写入，会报错。

技能构建器

方法	含义
category(id)	所属分类
name(text) / description(text)	名称与提示文本
icon(物品ID或图标对象)	'minecraft:diamond'，或类似 {type:'texture', id:'minecraft:textures/item/diamond.png'}
position(x, y)	画布坐标
hidden(boolean)	满足前置条件之前隐藏
requireAll(boolean)	true 需要全部前置；false 需要任一前置
requires(id)	需要 id 至少 1 级
requiresLevelGreaterThan(id, level)	需要等级严格大于 level
clearPrerequisites()	清空前置
choiceGroup(groupId)	加入互斥组；传 '' 表示移出
condition(typeId, data) / clearConditions()	对所有可学习等级生效的自定义条件
level(n, callback)	新建或修改第 n 级（从 1 开始）
clearLevels()	清空全部等级，同时清掉各级的附属声明
json(patch)	合并原生节点 JSON 字段

requiresLevelGreaterThan('haste', 2) 表示至少 3 级。

等级从 1 开始，必须连续定义，不能跳级。每一级的奖励只在该等级为当前等级时生效，不会和低等级叠加。如果二级总共要加 2，就在二级写 amount = 2。

互斥组

互斥组 ID 相同的节点互相排斥。玩家学习了组内任一节点后，同组其他节点会被锁定，状态显示为「已互斥」。已学的节点被重置到 0 级后，其他节点恢复可学。

SkillAtlasEvents.definitions(event => {
  event.createNode('warrior_path').category('combat').choiceGroup('class').level(1, r => r.cost({ type: 'skill_points', amount: 1 }))
  event.createNode('mage_path').category('combat').choiceGroup('class').level(1, r => r.cost({ type: 'skill_points', amount: 1 }))
})

• 组 ID 规则与节点 ID 相同：小写、不能有冒号、最多 64 个字符。
• 互斥组在整个图谱范围内生效，不同分类的节点也可以在同一组。
• 已经学会的节点不会被互斥锁定。如果设置互斥组之前已经学了两个，两个都保留，也都能继续升级。
• 检查在服务端执行，被拦截时失败代码为 choice_excluded。
• 图谱编辑者也可以在游戏内节点编辑器的「互斥组」中设置，JSON 中对应字段为 "choice_group"。

等级构建器

方法	含义
cost({type, amount})	type 为 'skill_points' 或 'experience'（实际经验值）
item(物品ID, 数量[, NBT或组件字符串])	需要交付的物品
clearItems()	清空交付物
attributeReward(属性, 数值, 运算)	属性修饰奖励
effectReward(...) / immunityReward(...) / commandReward(...)	原生奖励类型
reward(json)	任意原生奖励 JSON，或用 {type:'pack:类型', data:{...}} 添加自定义奖励
clearRewards()	只清原生奖励
condition(typeId, data) / clearConditions()	该等级的自定义条件
customReward(typeId, data) / clearCustomRewards()	该等级的自定义奖励
json(patch)	合并原生等级 JSON 字段

交付物字段名仍然叫 nbt。1.20.1 中它是完整的物品 NBT 条件；1.21.1 和 26.1.2 中它是本体定义的组件补丁格式。旧版 NBT 不能原样用在新版本上。

分类构建器

方法	含义
name(text) / icon(...)	显示
pool(poolId)	点数池；'' 表示没有点数池，费用改用实际经验
background(纹理ID, 是否平铺)	画布背景
json(patch)	原生 JSON 字段

点数池构建器

方法	含义
name(text) / description(text) / color(rgb) / initial(points)	显示与初始点数
acquisition(method, count, points, limit)	原生规则：kill、mine、harvest、craft、smelt、fish、movement、advancement、playtime
targets(数组)	原生规则的目标，例如 ['#minecraft:crops']
customAcquisition(typeId, data, count, points, limit)	绑定到已注册的行为获取类型
json(patch)	原生 JSON 字段

自定义池不接受原生 targets。切回原生 acquisition，或在 json 中显式设置 method，都会清除自定义绑定。

json(patch)

json 合并顶层字段，数组整体替换，不能修改对象 ID。结果仍要经过完整的原生解析与校验，所以所有原生字段都能配置：形状、大小、别名、前置连线、背景图片等。取值范围和总数限制与基础图谱一致，不会为脚本放宽。