199 lines
7.6 KiB
Markdown
199 lines
7.6 KiB
Markdown
# TC KubeJS Bridge (tckubejsbridge)
|
||
|
||
将 **神秘时代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/`，**重启游戏生效**（见"注意事项"第 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` 不生效：
|
||
- TC 配方在 `ThaumcraftApi.getCraftingRecipes()` 内存列表，KubeJS `/reload` 不清空它
|
||
- 本 mod 的去重集合（按 research 键）也不随 `/reload` 清空
|
||
- 若将来需要 `/reload` 支持，可在脚本中调用 `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 // 示例脚本
|
||
```
|