# TC KubeJS Bridge (tckubejsbridge)

> **中文** | [English](README_EN.md)

将 **神秘时代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 工程：

```bash
# 在仓库根目录执行
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. 注魔配方

```js
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. 坩埚炼金配方

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

### 3. 奥术有序合成配方

```js
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. 奥术无序合成配方

```js
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. 物品固有要素

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

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

```js
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        // 示例脚本
```