kubejs-thaumcraft/README.md

TC KubeJS Bridge (tckubejsbridge)

中文 | English

将 神秘时代4（Thaumcraft 4 移植版） 的配方系统桥接到 KubeJS，让整合包作者/服务器管理员 可以在 KubeJS 脚本中直接注册 TC 的注魔、炼金、奥术合成配方以及物品固有要素，并支持替换原有配方。

作者：AlkSur ｜ 许可证：GPL-3.0

依赖

Mod	版本	关系
NeoForge	21.1.234	必需
Minecraft	1.21.1	必需
Thaumcraft (TC4 移植版)	0.2.2.34-port.1	必需
KubeJS (NeoForge)	2101.7.x	必需（插件依赖其 API）

本 mod 与 KubeJS 为可选依赖关系（mods.toml 中 kubejs 标记为 optional）： 未安装 KubeJS 时本 mod 不加载插件部分，不影响游戏启动。

构建

工程位于 modules/tc-kubejs-bridge，属多 module Gradle 工程：

# 在仓库根目录执行
gradle :tckubejsbridge:build

产物：modules/tc-kubejs-bridge/build/libs/KubeJS Thaumcraft-<mod_version>+<neoforge_version>.jar （例：KubeJS Thaumcraft-1.0.0+21.1.234.jar）

编译依赖（本地 jar，路径在 build.gradle 中可改）：

• KubeJS：F:/downloads/kubejs-neoforge-2101.7.2-build.368.jar
• Rhino：F:/downloads/rhino-2101.2.7-build.81.jar（KubeJS 的脚本引擎）
• Thaumcraft：modules/thaumicenergistics-neo/library/thaumcraft-0.2.2.34-port.1.jar

若本地路径不同，请修改 build.gradle 中 dependencies 的 files(...) 路径。

脚本用法

将脚本放入 kubejs/server_scripts/，然后重启游戏或执行 /reload 生效（见"注意事项"第 1 条）。

1. 注魔配方

ServerEvents.recipes(event => {
    event.recipes.thaumcraft.infusion(
        'MY_INFUSION',              // research 键（全局唯一，用于魔导手册/去重）
        'minecraft:diamond',        // 输出
        3,                          // 不稳定性
        ['ignis 64', 'potentia 32'],// 源质：要素 tag + 数量
        'minecraft:golden_apple',   // 中心物品
        'minecraft:blaze_rod',      // 祭品（可多个）
        'minecraft:ender_pearl'
    );
});

2. 坩埚炼金配方

ServerEvents.recipes(event => {
    event.recipes.thaumcraft.crucible(
        'MY_CRUCIBLE',
        'minecraft:diamond',
        'minecraft:coal',           // 催化剂
        { aer: 16, ignis: 8 }       // 对象写法
    );
});

3. 奥术有序合成配方

ServerEvents.recipes(event => {
    event.recipes.thaumcraft.arcane(
        'MY_ARCANE',
        'minecraft:diamond_sword',
        ['ignis 16', 'ordo 8'],
        [' I ', ' I ', ' S '],      // pattern：最多 3 行
        { I: 'minecraft:iron_ingot', S: 'minecraft:stick' }
    );
});

4. 奥术无序合成配方

ServerEvents.recipes(event => {
    event.recipes.thaumcraft.arcane_shapeless(
        'MY_SHAPELESS',
        'minecraft:diamond_helmet',
        ['aer 8', 'aqua 8'],
        'minecraft:leather_helmet',
        'minecraft:diamond',
        'minecraft:diamond',
        'minecraft:diamond'
    );
});

5. 物品固有要素

ServerEvents.recipes(event => {
    event.thaumcraft.addObjectTag('minecraft:stick', { aer: 1, ignis: 2 });
});

6. 替换（先删后注册）已有配方

ServerEvents.recipes(event => {
    // 注意：thaumcraft 是顶层绑定，不是 event.thaumcraft
    thaumcraft.removeInfusion('INFUSIONPROVIDER');   // 按 research 键删除 TC 注魔配方
    // thaumcraft.removeArcane('RESEARCH_KEY');      // 按 research 键删除奥术配方

    // 然后注册新配方，实现真正替换
    event.recipes.thaumcraft.infusion(
        'INFUSIONPROVIDER',
        'thaumicenergistics:infusion_provider',
        0,
        ['auram 10'],
        'ae2:interface',
        'minecraft:oak_planks'
    );
});

要素 tag 参考（TC4 移植版实际值）

注意：移植版的要素 tag 是拉丁文原名，不是 TC4 汉化/英文名。

要素	tag	要素	tag
风 AIR	aer	土 EARTH	terra
火 FIRE	ignis	水 WATER	aqua
秩序 ORDER	ordo	混沌 ENTROPY	perditio
虚空 VOID	vacuos	光 LIGHT	lux
天气 WEATHER	tempestas	运动 MOTION	motus
水晶 CRYSTAL	vitreus	生命 LIFE	victus
能量 ENERGY	potentia	交换 EXCHANGE	permutatio
死亡 DEATH	mortuus	黑暗 DARKNESS	tenebrae
灵魂 SOUL	spiritus	异域 ELDRITCH	alienis
魔法 MAGIC	praecantatio	灵气 AURA	auram
粘液 SLIME	limus	植物 PLANT	herba
树 TREE	arbor	野兽 BEAST	bestia
肉体 FLESH	corpus	亡灵 UNDEAD	exanimis
心智 MIND	cognitio	感知 SENSES	sensus
人类 MAN	humanus	工具 TOOL	instrumentum
贪婪 GREED	lucrum	工艺 CRAFT	fabrico
布料 CLOTH	pannus	机制 MECHANISM	machina

注意事项

1. 支持热重载：改脚本后执行 /reload 即可生效，无需重启游戏。
   • KubeJS 每次 /reload 都会重新执行 ServerEvents.recipes，脚本会再次运行。
   • 若脚本使用"先删后注册"（thaumcraft.removeInfusion(...) 再 infusion(...)）写法， 删除步骤会清掉本 mod 的去重键并移除 TC 内存列表中的旧配方，因此新配方能正确重新注册。
   • 纯新增（不先删）的脚本重复 /reload 会被去重拦截（skipping），请配合 thaumcraft.clearRegistered() 使用或在脚本开头调用它。
2. research 键全局唯一：重复键会被跳过（防止重复注册）。如需同名配方，请改键。
3. 配方不进原版 RecipeManager：TC 注魔/炼金/奥术配方是 TC 自己的内存列表。 本桥接在脚本执行时直接调用 TC API 注册，并对 KubeJS 输出无害占位配方， 不影响其他 mod 的配方操作（schema 的 typeOverride 指向 minecraft:crafting_shapeless 以满足 KubeJS 的 serializer 查找）。
4. 源质列表两种写法：数组 ['ignis 64'] 或对象 {ignis: 64} 均可。
5. 物品参数：支持物品 id 字符串（minecraft:xxx / ae2:xxx）、Item.of(...)、物品 tag（#minecraft:planks）。
6. AE2 物品命名空间是 ae2：如 AE2 接口是 ae2:interface，不是 appliedenergistics2:interface。
7. KubeJS 版本兼容：桥接层基于 KubeJS 2101.7.x 的 RecipeSchema API（标注 @ApiStatus.Experimental），升级 KubeJS 小版本后如遇编译错误，可能需要同步调整。

排障

现象	原因
日志 Serializer for type thaumcraft:infusion is not found	缺 typeOverride（已内置修复，重新构建即可）
日志 Unknown aspect 'xxx'	要素 tag 写错，对照上面要素表
日志 Item with ID xxx does not exist	物品 id 错误，注意 ae2: 命名空间
日志无任何 TC-KubeJS-Bridge 输出	mod 未装入 mods、或脚本未放入 server_scripts
脚本报 event.thaumcraft is undefined	顶层绑定用 thaumcraft.xxx，不要写 event.thaumcraft.xxx

项目结构

src/main/java/tckubejsbridge/
├── TCKubeJSBridge.java            // @Mod 主类
└── kubejs/
    ├── TCKubeJSPlugin.java        // KubeJS 插件：注册 schema + bindings
    ├── TCRecipeKJS.java           // 自定义 KubeRecipe 基类（桥接 + 占位序列化）
    ├── TCRecipeBridge.java        // TC API 调用 + 去重 + 移除 + 占位 JSON
    ├── AspectListComponent.java   // 源质列表 RecipeComponent
    ├── InfusionRecipeKJS.java     // 注魔配方
    ├── CrucibleRecipeKJS.java     // 坩埚炼金配方
    ├── ShapedArcaneRecipeKJS.java // 奥术有序配方
    └── ShapelessArcaneRecipeKJS.java // 奥术无序配方
src/main/resources/
├── kubejs.plugins.txt             // 插件发现文件
└── META-INF/neoforge.mods.toml
example/infusion_example.js        // 示例脚本