KubeJS 工作室

KubeJS Studio

KubeJS Studio 是 KubeJS 的游戏内前端。按下 K 键，你就会得到一个用于配方、标签、战利品表、物品和方块属性以及新注册表条目工作区，外加一个知晓你整合包中已加载内容的代码编辑器。Studio 会在 kubejs/ 下写入普通文件：脚本、数据包 JSON、语言文件和模型。没有需要导出的项目格式，生成的文件在没有 Studio 的情况下依然可以正常工作。

需要 KubeJS。在 Forge 1.20.1 上还需要 Kotlin for Forge。LDLib2 已内置于 jar 中。仅客户端侧，永远不需要放在服务器上。

GUI 还是代码，由你决定

GUI 可能比手写脚本更快。其他时候，直接编辑脚本会更好。Studio 两者都支持，你可以随时切换，或者同时使用两者。

如果你从未编写过 KubeJS 脚本，请从五个可视化标签页开始。选择一个配方、标签、战利品表或物品，用真实的物品槽和普通字段进行修改，然后点击 Queue（入队）。在 Studio 实际写入任何内容之前，它会准确显示将要写入的内容。

如果你已经会写 KubeJS，Files（文件）标签页就是一个真正的编辑器。自动补全、悬停文档和错误检查都来自正在运行的实例，而不是两个版本前就已过时的类型定义文件。输入 event.recipes.，列表就是该整合包中已加载的配方类型，包括模组在内。

工作区

配方

所有已加载的配方都在浏览器中，可按模组、类型或物品过滤。支持的类型会在表单中打开，物品槽会从选择器填充（或者使用 Held 按钮将你手中的物品堆叠复制到结果中），还有数量和类别字段，编辑时下方会显示生成的输出。你可以覆盖配方、禁用它、复制它，或者从头开始创建一个空白配方。

原版工作台、烹饪、切石和锻造都有手工构建的表单。Create 的处理配方也有，包括加热混合和序列组装。Farmer's Delight、Ars Nouveau 和常见的 Mekanism 机器类型都有自己的布局。

对于其他类型，Studio 会根据 KubeJS 已有的配方 schema 构建扁平表单：物品和流体字段变成槽位，数字和标志变成字段。这覆盖了许多带有 KubeJS 附加模组的模组，而我无需为每个模组编写任何内容。如果某个类型没有 schema，或者现有 JSON 比该表单能够往返处理的更复杂，它会以原始 JSON 打开，由你进行编辑。

配方 JSON 来自正在运行的世界，所以你看到的就是游戏加载的内容。JEI 和 EMI 的配方页面会获得一个 Edit（编辑）按钮，点击后会跳转到 Studio 并选中该配方（仅单人游戏、创造模式）。

标签

选择一个注册表（物品、方块、流体、实体，以及游戏暴露的任何动态注册表），找到标签，添加或移除成员。添加和移除会以内联方式显示在当前实时内容旁边，这样你可以在入队前看到差异。这是一种将模组物品加入 #minecraft:planks 或 #c:ingots/copper 的快捷方式，以便配方和机制能够识别它们。

战利品

真实的战利品表，以池和条目的树形结构进行原地编辑。Rolls、count 和 weight 保持内联。某行上的 ... 会打开该条目的完整编辑器，其中条件和函数以类型化表单的形式存在：工具检查、随机概率、Fortune 风格加成、爆炸衰减、名称、描述文本、组件或 NBT，以及嵌套的 all_of / any_of 逻辑。表级设置（context type、random sequence、表级函数）位于 Table… 下。目录跟随 Minecraft 版本，任何没有类型化表单的内容都可以作为原始 JSON 编辑。

属性

没有配方或标签能够触及的基础属性。物品暴露堆叠大小、耐久度、食物值、燃烧时间和仅用于启用的防火标志。方块暴露硬度、爆炸抗性、光照等级、摩擦力、是否需要工具、挖掘等级以及可用于挖掘的工具。Studio 会写入匹配的 ItemEvents.modification 或 BlockEvents.modification 启动脚本。

同一个标签页可以为游戏中已有的任何内容重命名和重新贴图，这会作为语言条目和 kubejs/assets 下的模型覆盖写入。属性更改需要重启游戏，挖掘标签在 /reload 时应用，名称和纹理在 F3+T 时应用。每行都会标记它需要哪一种。

创建

无需触碰启动脚本即可创建新物品、方块和流体。给它一个 id，选择 Studio 的构建器类型之一（普通物品、工具、盔甲部件、台阶、楼梯、门、作物、带桶的流体等），然后填写你关心的字段。字段列表与版本对应，因此 1.20.1 只显示 1.20.1 KubeJS 支持的内容。你创建的所有内容都会列在左侧，以便你以后重新打开或删除。

编辑器

如果你用过 ProbeJS，这个目标会感觉很熟悉。ProbeJS 生成类型定义，以便外部 IDE 可以帮助你编写 KubeJS；我希望这种帮助存在于 Minecraft 内部。Studio 会对你实际拥有的 KubeJS 运行时进行反射（事件组和处理器、绑定到脚本作用域的全局对象、包括附加模组），并根据补全需要从打开的世界读取配方 schema 和游戏 id。没有类型定义步骤，也没有第二个窗口，并且符号索引的缓存副本可以覆盖实时反射失败的罕见情况。

Files（文件）标签页本身是一个用于整个实例的文件浏览器和多标签页编辑器，支持 JS、JSON、TOML 和日志的语法高亮。它可以编辑文本文件（最大 2 MB）、预览图片，并在有保护措施的情况下进行创建、重命名和删除。收藏夹和固定文件夹让你的 kubejs/ 目录树只需一键即可访问。

补全

输入 event.，你会得到该事件的成员。输入 event.recipes.，你会得到所有具有 KubeJS 配方 schema 的模组的命名空间，然后是它们下面的类型，然后是该类型支持的链式方法（Create 混合的 .heated()、冶炼的 .xp()）。字符串补全会遵循上下文：配方需要物品或标签 id 时提供它们（带图标），过滤器中的模组 id，注册表事件中的构建器类型，适合位置中的战利品表 id 和语言键。通过 Java.loadClass 加载的类会获得静态成员补全，数据包 JSON 会识别常见的 id 字段（item、tag、id、type）。

悬停文档和签名帮助

将鼠标悬停在 KubeJS 成员、变量、id 或诊断信息上，可以查看它是什么：签名和简短描述、类型、id 背后的物品、完整消息。当光标位于可识别调用内部时，其上方会出现一条签名栏。文档来自采集的运行时索引（包括 KubeJS 自身的 @Info 注解）以及一份小型内置参考，用于补充 KubeJS 没有对自身进行描述的部分。

诊断

错误和警告会在你输入时出现，编辑器下方显示数量，悬停时显示完整消息。包括未知成员和标识符、拼错的物品、标签、模组和配方 id、与配方 schema 不匹配的参数数量、位于错误类型槽位中的 id、从错误脚本类型使用的事件（在启动脚本中使用 ServerEvents）、格式错误的 // priority 和 // requires 头、括号不匹配和字符串未终止，以及 KubeJS 类过滤器会拒绝的 Java 类。上一次重载中带有源位置的 KubeJS 控制台错误也会落到出错的代码行上，因此一个损坏的配方会指回对应的语句，而不是日志文件。

控制台和重载

控制台面板列出上一次重载中的 KubeJS 错误和警告。点击一个可以跳转到其所在行，或者使用命令框运行 /kubejs errors、/reload 或任何其他命令，而无需离开屏幕。Reload 按钮会重载你正在编辑的文件的脚本类型（启动、服务器或客户端脚本，数据则执行 /reload），因此你不必为了测试客户端脚本而重建整个数据包。

其他功能

支持查找和替换（区分大小写、全词匹配和正则表达式）、格式化、代码片段面板、自动换行、括号闭合和自动缩进、预览标签页、会话恢复，以及将附近输入批处理为单一步骤的撤销功能。Ctrl+I 在光标处打开物品选择器并插入一个 id（或将标签展开为其成员 id），Ctrl+R 插入配方的 JSON，Ctrl+P 搜索采集的 KubeJS 索引，{ } API 按钮打开同一个索引，并按其分组为全局对象、事件和类型。语言文件会获得一个 "Missing keys" 按钮，用于插入该命名空间尚未翻译的方块、物品、实体、效果和附魔键。

它内置了 JetBrains Mono 字体，在 1.20.1 上通过 SDF 管线渲染，因此在任何 GUI 缩放比例下都保持清晰。你资源包中的其他字体可以在设置中选择（Embers Text API 会扩大可选范围）。

入队、审阅、应用

可视化标签页中的任何内容都不会直接写入磁盘。更改会收集在屏幕底部的待处理列表中。默认情况下，Apply（应用）会显示即将写入文件的差异，在每个文件旁保留之前版本的 .bak 备份，并在之后重新加载。如果你不希望如此，这三项都是可配置的设置。

配方、标签和战利品更改可以按更改分别写入为 KubeJS 脚本或 kubejs/data 下的数据包 JSON，在你切换之前，数据包是默认选项。属性更改和新注册表条目始终是启动脚本，名称和纹理始终是资源文件。脚本放在 kubejs/server_scripts/kubejsstudio/ 和 kubejs/startup_scripts/kubejsstudio/ 下，每种类型一个文件。重新应用会按 id 合并到 Studio 之前写入的内容中，而不是整体替换文件，但请将这些文件视为生成输出，并将你自己的手写脚本放在其他地方。Studio 写入的任何内容都可以从创建它的同一个标签页中重置。

小细节

• 主题。 内置十八种：Studio Dark、Catppuccin 全部四种风味、Dracula、Everforest、GitHub dark 和 light、Gruvbox、Kanagawa、Monokai、Nord、One Dark、Rose Pine、Solarized dark 和 light、Tokyo Night。将 JSON 文件放入 config/kubejsstudio/themes 即可使用你自己的主题；首次运行时会在此处写入一个示例。
• 设置。 一个可搜索的对话框涵盖字体、编辑器行为、智能功能的开启情况及积极程度，以及上述工作流开关。
• 按键绑定。 用于标签页切换、搜索、入队和应用、补全、代码片段、格式化和文件操作的 Studio 快捷键都在同一个对话框中重新绑定。K 键以及每个标签页的可选直接绑定位于 Minecraft 的控制屏幕中。
• 布局。 主面板可以调整大小和折叠，对话框会记住其大小，设置中有一键重置功能，以备你把自己逼入死角。
• /kubejsstudio 可以从聊天中打开工作区，每个标签页有一个子命令。

兼容性

Minecraft	加载器	Java	需要
1.21.1	NeoForge 21.1.216+	21	KubeJS
1.20.1	Forge 47+	17	KubeJS, Kotlin for Forge 4.11+

清单文件没有固定 KubeJS 版本。此版本是在 1.21.1 上针对 KubeJS 2101.7.2、在 1.20.1 上针对 2001.6.5 构建的；其他版本很可能也能工作，但这些是我测试过的版本。NeoForge 的最低版本要求来自内置的 LDLib2，这就是它高于加载器自身基线的原因。

可选：Create（解锁其配方表单）、JEI 或 EMI（在其配方界面上显示编辑按钮；Forge 上 JEI 15.17.0.74+，NeoForge 上 19.27.0.335+）。

Studio 是一个客户端侧创作工具。将它安装在你构建整合包的实例中，发布生成的文件，它不需要出现在服务器或任何其他人的客户端上。浏览器从单人游戏服务器读取数据，因此在使用它们之前请先打开一个世界。

许可证

请参阅 tysontheember.dev/modding-licence。

捆绑的第三方作品（OFL 许可下的 JetBrains Mono，LGPL 许可下的 LDLib2）由 jar 内的 licenses/NOTICE.txt 覆盖，并附有完整许可证文本。