🎮 KubeJS 6 新手实战：在 1.20.1 中创建你的第一个自定义物品与配方

想用 KubeJS 魔改 Minecraft，却被各种版本差异和复杂 API 搞得一头雾水？网上教程要么太旧不兼容 KubeJS 6，要么零散不成体系，让新手无从下手。别急，这篇文章帮你从零开始，用一个完整的「黑曜石熔炼」示例，手把手带你体验 KubeJS 6 的核心流程，让你听完就懂、跟着就学会！

📑 目录

一、在开始之前，需要先了解什么
二、环境准备：搭建脚本工作区
三、实战示例：添加一个「黑曜石熔炼配方」
3.1 创建配方脚本
3.2 进阶：删除原版配方，替换为新配方
四、自定义物品：创建「黑曜石碎片」
4.1 注册物品
4.2 添加纹理与本地化
五、让它更强：自定义流体「液态黑曜石」
六、自定义标签：将物品归入挖掘等级
七、事件监听：让世界活起来
八、小结

一、在开始之前，需要先了解什么

KubeJS 6 已全面拥抱 1.20.1 版本的 Forge 端，其脚本环境并非「傻瓜式一键化」，需要你：

频繁进入世界测试、查看日志，通过类型与运行结果不断修正认识。
参考社区示例时注意版本差异，不同作者、不同历史阶段的代码不能默认照抄。
具备基础的 JavaScript 语言理解，因为 KubeJS 不会屏蔽语言本身的复杂性。

二、环境准备：搭建脚本工作区

安装好 KubeJS 6 和辅助工具 ProbeJS 后，首次启动游戏会在 .minecraft 目录下生成 kubejs 文件夹，其结构如下：

kubejs/
├── client_scripts/  # 客户端脚本（仅本地资源加载等）
├── server_scripts/  # 服务端脚本（配方、事件、逻辑等，核心区域）
└── startup_scripts/ # 启动脚本（注册新物品、方块、流体等，重启才生效）

📌 重点：
– 修改 server_scripts 后可使用 /kubejs reload 热重载。
– 修改 startup_scripts 后必须重启游戏。

建议使用 VS Code 编辑 .js 文件，并借助 ProbeJS 的代码补全功能提升效率。

三、实战示例：添加一个「黑曜石熔炼配方」

我们将实现一个功能：在熔炉中放入黑曜石，即可产出钻石。这需要自定义配方，属于服务端脚本范畴。

3.1 创建配方脚本

在 kubejs/server_scripts/ 下新建 obsidian_recipes.js，输入以下代码：

ServerEvents.recipes(event => {
  // 添加黑曜石熔炼为钻石的配方
  event.smelting('minecraft:diamond', 'minecraft:obsidian')
})

运行 /kubejs reload，放入黑曜石就能烧出钻石了。

3.2 进阶：删除原版配方，替换为新配方

如果你想把原版「黑曜石→钻石」改为产出「黑曜石碎片」，并且移除原版铁砧配方，可以这样做：

ServerEvents.recipes(event => {
  // 1. 先删除原版铁砧配方
  event.remove({output: 'minecraft:anvil'})

  // 2. 改用黑曜石碎片（自定义物品）合成铁砧
  event.shaped('minecraft:anvil', [
    'AAA',
    ' I ',
    'III'
  ], {
    A: 'kubejs:obsidian_shard',
    I: 'minecraft:iron_ingot'
  })
})

这里的 kubejs:obsidian_shard 是我们接下来要创建的自定义物品。

四、自定义物品：创建「黑曜石碎片」

物品注册必须放在 startup_scripts 下，因为它是启动时一次性注册的。

4.1 注册物品

在 kubejs/startup_scripts/ 下新建 item_registry.js：

StartupEvents.registry('item', event => {
  event.create('kubejs:obsidian_shard', 'basic')
       .displayName('黑曜石碎片')
       .texture('kubejs:item/obsidian_shard')
})

💡 ‘basic’ 是普通物品的构建器类型。更多类型（如剑、盔甲）可查阅 Builder 系统。

4.2 添加纹理与本地化

为了让物品有图标，需要准备一张 obsidian_shard.png 放入 kubejs/assets/kubejs/textures/item/ 文件夹。同时，在 kubejs/assets/kubejs/lang/zh_cn.json 中添加：

{
  "item.kubejs.obsidian_shard": "黑曜石碎片"
}

重启游戏后，漂亮的碎片就出现了。

五、让它更强：自定义流体「液态黑曜石」

如果想进一步提升整合包深度，可以注册一种新流体，让它参与配方。

在 startup_scripts/ 下新建 fluid_registry.js：

StartupEvents.registry('fluid', event => {
  event.create('kubejs:liquid_obsidian')
       .thickTexture(0x1a0033)   // 静止颜色
       .thinTexture(0x2a0055)    // 流动颜色
       .bucketColor(0x1a0033)    // 桶内颜色
       .displayName('液态黑曜石')
})

✅ KubeJS 注册流体时会自动赠送一个对应的「流体桶」，非常贴心。

六、自定义标签：将物品归入挖掘等级

有了新物品，我们需要让它能被特定工具挖掘。通过修改方块标签实现。

在 server_scripts/ 下新建 tag_modify.js：

ServerEvents.tags('block', event => {
  // 将黑曜石碎片块 添加到 铁镐可挖掘 的标签中
  event.add('minecraft:mineable/pickaxe', 'kubejs:obsidian_shard_block')
  // 将其挖掘等级设定为 3（钻石级）
  event.add('minecraft:needs_diamond_tool', 'kubejs:obsidian_shard_block')
})

七、事件监听：让世界活起来

KubeJS 6 最强大的地方在于可以监听游戏中的各种事件。例如，让玩家踩在「黑曜石碎片块」上时获得一个负面效果：

BlockEvents.steppedOn('kubejs:obsidian_shard_block', event => {
  const player = event.player
  if (!player.isCrouching()) { // 如果玩家没有潜行
    player.potionEffects.add('minecraft:slowness', 100, 2) // 给予 5 秒缓慢 III
    player.tell(Text.red('你踩在了锋利的黑曜石碎片上！'))
  }
})

在 KubeJS 6 中，事件不再使用 onEvent，而是直接用 BlockEvents.steppedOn 这种新式语法，并且支持直接传入方块 ID 作为监听参数，比旧版更清晰。

八、小结

总结一下这次魔改的完整路线：

搭建环境——理解 kubejs 文件夹结构，分清 startup 与 server 脚本。
配方入门——在 server_scripts 中用 ServerEvents.recipes 添加/删除配方。
内容注册——在 startup_scripts 中用 StartupEvents.registry 创建物品、流体。
标签与事件——用标签改变方块属性，用事件监听赋予自定义交互。

按照这个流程走下来，哪怕你从未写过一行代码，也能在半小时内上手 KubeJS 6，打造出独一无二的整合包体验。赶紧打开 VS Code，让你的想象力在方块世界里自由驰骋吧！🎉

📎 相关资源链接：
– KubeJS 6 官方文档
– CrychicDoc 社区教程（1.20.1）
– MC 百科 KubeJS 教程区