Skip to content

KubeJS Guide zh_CN

hp-1e edited this page Nov 20, 2026 · 1 revision

语言 / Language: English | 简体中文

KubeJS 兼容与开发教程

Archogenum Addition 内置原生 KubeJS 扩展(ArchogenumEvents、ArchogenumJS / ArchogenumAPI),支持通过脚本注册自定义词条(Trait)、基因(Gene)、生物基因组(Genome)与基因标签(Gene Tag),监听运行时事件,并支持秒级热重载。


1. 脚本存放位置与秒级热重载

ArchogenumEvents.registry 同时支持 kubejs/startup_scripts/ 与 kubejs/server_scripts/。

  • 推荐位置:将基因注册脚本放在 kubejs/server_scripts/(推荐命名空间:kubejs:、archogenum_addition: 或 archogenum:)。
  • 秒级热重载指令:在游戏内执行 /genereload(别名 /genecore reload,需 OP 2 级权限)。该指令会仅重载 server_scripts,直接将最新的 trait → gene → genome 热写入运行中的服务端与客户端注册表,刷新在线玩家属性修饰符、同步基因标签与客户端翻译,无需执行原版 /reload。
    • 注意:新增或修改 PNG 贴图仍需按 F3 + T 重载资源包;刷新 JEI 列表需重载 JEI 或重进存档。

2. 注册词条、基因与生物基因组

在 kubejs/server_scripts/custom_genes.js 中使用 ArchogenumEvents.registry(event => { ... }):

ArchogenumEvents.registry(event => {
    // 1)属性修饰词条(Modifier Trait)
    // operation 支持:'addition'、'multiply_base'、'multiply_total'
    event.createModifierTrait('kubejs:modifiers/dwarf_mining')
        .add('minecraft:generic.armor', 'addition', 2.0)
        .add('minecraft:generic.attack_speed', 'multiply_base', 0.15)

    // 2)自定义脚本词条(在界面展示名称,具体逻辑通过下方事件编写)
    event.createCustomTrait('kubejs:ember_resonance', 'beneficial', '余烬共鸣')

    // 3)原生 JSON 词条(可直接传入任意 Archogenum 原生词条结构)
    // event.createTraitJson('kubejs:custom_effect', { type: 'archogenum:effects', ... }, '自定义效果')

    // 4)注册基因
    event.createGene('kubejs:dwarf_vigor')
        .beneficial()              // .beneficial() 正面 | .harmful() 负面 | .cosmetic() 外观
        .offense()                 // .offense() 输出 | .defense() 防御 | .utility() 功能
        .complexity(1)             // 复杂度点数
        .metabolicEfficiency(-1)   // 代谢效率(负值增加饥饿消耗,正值抵消)
        .maxExpression(3)          // 最高表达等级(1~5)
        .color('#ff6b2b')          // 十六进制主题色
        .texture('kubejs:textures/gui/gene/dwarf_vigor.png')
        .cost('minecraft:iron_ingot', 8)
        .cost('minecraft:blaze_powder', 4)
        .trait('kubejs:modifiers/dwarf_mining')
        .trait('kubejs:ember_resonance')
        .tag('pyro')               // 或 .tags(['pyro', 'core'])
        .displayName('矮人体魄')
        .description('继承自地底工匠的顽强体魄,强化战斗韧性。')

    // 5)为生物绑定可提取基因池(Genome)
    event.addGenome(
        'kubejs:nether_warriors',
        ['minecraft:blaze', 'minecraft:magma_cube'],
        ['kubejs:dwarf_vigor']
    )
})

GeneBuilderJS 链式方法速查

方法 说明
.beneficial() / .harmful() / .cosmetic() / .category(str) 设置基因类别
.offense() / .defense() / .utility() / .role(str) / .group(str) 设置基因轨道(开启双轨复杂度或 Curios 质粒槽时生效;.utility() 未显式设复杂度时默认为 1)
.complexity(int) 复杂度(>= 0)
.metabolicEfficiency(int) 代谢效率(可正可负)
.maxExpression(int) 最高表达等级(1~5)
.archogene(boolean) 设为太古/超凡基因(合成基底需消耗附魔金苹果)
.color(hex) 十六进制颜色(如 '#55ddff')
.texture(rl) 基因图标贴图路径(16x16 PNG)
.cost(itemId, count) 添加合成催化材料
.trait(traitId) 绑定词条 ID
.tag(tag) / .tags(list) 添加一个或多个基因标签
.displayName(str) / .description(str) 动态显示名与描述(可在语言文件中用 gene.<ns>.<path> 与 .desc 覆盖)

3. 基因标签系统(Gene Tags)

基因标签可用于流派分类与羁绊计数(如 pyro / 炽焰、frost / 冰霜 等):

ArchogenumEvents.registry(event => {
    // 可选:为英文标签 ID 注册显示名与十六进制配色
    // 若资源包存在翻译键 `gene_tag.archogenum_addition.<tag>`,则优先走多语言翻译
    event.defineGeneTag('pyro', '炽焰', '#ff6b2b')

    // 给原版或已有基因打标签
    event.tagGene('archogenum:pyrophobic_veins', 'pyro')
    // 也可以一次打多个标签,或直接传中文标签名:
    // event.tagGene('archogenum:lava_stride', ['炽焰', '机动'])
})
  • Tooltip 展示规则:
    • 默认配置(关闭双轨复杂度与质粒槽):显示 [炽焰] 畏火血脉 I(无标签时不显示括号)。
    • 开启双轨复杂度或 Curios 质粒槽时:显示 [防御/炽焰] 畏火血脉 I(无标签时仅显示 [防御])。
  • 统计身上某标签的生效基因数量(自动统计主基因 + Curios 外载质粒槽,不重复计数):
let count = ArchogenumJS.countGenesWithTag(player, 'pyro')
let hasAny = ArchogenumJS.hasGeneTag(player, 'pyro')
let exprSum = ArchogenumJS.getTagExpressionSum(player, 'pyro')
let list = ArchogenumJS.getGenesWithTag(player, 'pyro') // List<GeneInstanceWrapper>

4. 运行时事件(kubejs/server_scripts/)

战斗事件(geneAttack / geneHurt)

按基因 ID 监听:

// 当携带 'kubejs:dwarf_vigor' 的实体造成伤害时触发
ArchogenumEvents.geneAttack('kubejs:dwarf_vigor', event => {
    let attacker = event.entity
    let pyroCount = ArchogenumJS.countGenesWithTag(attacker, 'pyro')
    // 示例:每个炽焰标签基因提供 +5% 增伤,并随表达等级成长
    event.damage = event.damage * (1.0 + pyroCount * 0.05 * event.scale)
})

// 当携带 'kubejs:dwarf_vigor' 的实体受到伤害时触发
ArchogenumEvents.geneHurt('kubejs:dwarf_vigor', event => {
    if (event.source.is('inFire') || event.source.is('onFire')) {
        event.damage = event.damage * 0.8
    }
})

可用属性:event.entity、event.attacker、event.target、event.source、event.geneId、event.expression、event.scale、event.damage(getDamage() / setDamage(float))。

周期 Tick 事件(geneTick)

ArchogenumEvents.geneTick('kubejs:dwarf_vigor', event => {
    let player = event.player
    if (player && event.level.time % 40 === 0) {
        // 每 2 秒执行一次
    }
})

可用属性:event.level、event.entity、event.player、event.geneId、event.expression、event.scale。

活体采样事件(liveExtract,可取消)

ArchogenumEvents.liveExtract(event => {
    // 可检查采样结果、替换产出的回响基因瓶,或取消采样
    let genes = event.extractedGenes
    // event.vesselStack = ...
    // event.cancel()
})

可用属性:event.player、event.target、event.extractor、event.resonant、event.vesselStack、event.extractedGenes。

异种基因果合成事件(synthesize,可取消)

ArchogenumEvents.synthesize(event => {
    // event.player, event.genes, event.complexity, event.hasArchogene(), event.resultStack
    // event.cancel() // 阻止本次合成
})

基因型变更事件(xenotypeChanged)

ArchogenumEvents.xenotypeChanged(event => {
    // event.entity, event.player, event.genes, event.empty, event.complexity,
    // event.metabolicEfficiency, event.hasGene('kubejs:dwarf_vigor'), event.getExpression('kubejs:dwarf_vigor')
})

5. 全局工具类(ArchogenumJS / ArchogenumAPI)

脚本中可直接使用全局对象 ArchogenumJS(别名 ArchogenumAPI):

方法 返回值 说明
ArchogenumJS.hasGene(entity, geneId) boolean 实体是否激活指定基因
ArchogenumJS.getGeneExpression(entity, geneId) int 获取指定基因表达等级(未拥有返回 0)
ArchogenumJS.getGenes(entity) List<GeneInstanceWrapper> 获取全部生效基因(支持 id、expression、maxExpression、complexity、metabolicEfficiency、category、role、archogene、scale、tags、hasTag(tag))
ArchogenumJS.countGenesWithTag(entity, tag) int 统计身上带有指定标签的生效基因数量
ArchogenumJS.hasGeneTag(entity, tag) boolean 是否至少拥有 1 个带指定标签的生效基因
ArchogenumJS.getGenesWithTag(entity, tag) List<GeneInstanceWrapper> 获取身上带指定标签的全部生效基因
ArchogenumJS.getTagExpressionSum(entity, tag) int 统计身上指定标签基因的表达等级总和
ArchogenumJS.getGeneTags(geneId) List<String> 查询某个基因 ID 配置的全部标签
ArchogenumJS.getTotalComplexity(entity) int 实体当前基因型总复杂度
ArchogenumJS.getRoleComplexity(entity, role) int 获取 'offense' 或 'defense' 轨道复杂度
ArchogenumJS.getMaxRoleComplexity(role) int 获取对应轨道的配置上限
ArchogenumJS.getTotalMetabolicEfficiency(entity) int 获取实体当前总代谢效率
ArchogenumJS.addGene(entity, geneId[, expr]) boolean 服务端为实体添加/更新基因
ArchogenumJS.removeGene(entity, geneId) boolean 服务端移除实体指定基因
ArchogenumJS.setGenes(entity, geneMap) void 服务端按 { '基因ID': 阶数 } 替换基因型
ArchogenumJS.clearXenotype(entity) void 服务端清空实体全部基因
ArchogenumJS.discoverGene(player, geneId) / forgetGene / hasDiscoveredGene / discoverAllGenes boolean / int 管理玩家图鉴解锁状态
ArchogenumJS.createSingleVessel(geneId, expr) ItemStack 创建单基因回响基因瓶
ArchogenumJS.createEchoVessel(geneMap) ItemStack 按 { '基因ID': 阶数 } 创建回响基因瓶
ArchogenumJS.createXenofruit(geneMap) ItemStack 按 { '基因ID': 阶数 } 创建异种基因果
ArchogenumJS.getStoredGenes(stack) Map<String, Integer> 读取回响基因瓶或异种基因果内封存的基因