347 lines
8.9 KiB
Markdown
347 lines
8.9 KiB
Markdown
# TC KubeJS Bridge (tckubejsbridge)
|
||
|
||
> **中文** | [English](README_EN.md)
|
||
|
||
将 **神秘时代4（Thaumcraft 4 移植版）** 的配方与研究系统桥接到 **KubeJS**。
|
||
|
||
整合包作者可以通过 `kubejs/server_scripts/` 下的 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） |
|
||
|
||
> KubeJS 在 `neoforge.mods.toml` 中声明为 **optional**：
|
||
> 未安装 KubeJS 时本 mod 不会加载插件部分，不影响游戏启动。
|
||
|
||
---
|
||
|
||
## 构建与安装
|
||
|
||
工程位于 `modules/tc-kubejs-bridge`，属于多 module Gradle 工程。
|
||
|
||
```bash
|
||
# 在仓库根目录执行
|
||
gradle :tckubejsbridge:build
|
||
```
|
||
|
||
构建产物：
|
||
|
||
```text
|
||
modules/tc-kubejs-bridge/build/libs/KubeJS Thaumcraft-<mod_version>+<neoforge_version>.jar
|
||
```
|
||
|
||
例如：
|
||
|
||
```text
|
||
KubeJS Thaumcraft-1.0.0+21.1.234.jar
|
||
```
|
||
|
||
把 jar 放入 `mods/` 文件夹即可。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
1. 在 `kubejs/server_scripts/` 下新建一个 `.js` 文件。
|
||
2. 在脚本里使用 `ServerEvents.recipes(event => { ... })`。
|
||
3. 保存后执行 `/reload`，或重启游戏。
|
||
|
||
所有 `thaumcraft.xxx` 都是**顶层绑定**，不要写成 `event.thaumcraft.xxx`。
|
||
|
||
---
|
||
|
||
## 配方注册
|
||
|
||
### 1. 注魔配方
|
||
|
||
```js
|
||
ServerEvents.recipes(event => {
|
||
event.recipes.thaumcraft.infusion(
|
||
'MY_INFUSION', // research 键（全局唯一）
|
||
'minecraft:diamond', // 输出
|
||
3, // 不稳定性
|
||
['ignis 64', 'potentia 32'], // 所需源质
|
||
'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. 奥术无序合成配方
|
||
|
||
> 注意：`arcane_shapeless` 的材料必须放在**一个数组**里。
|
||
|
||
```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'
|
||
]
|
||
);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 物品固有要素
|
||
|
||
```js
|
||
ServerEvents.recipes(event => {
|
||
// 添加
|
||
thaumcraft.addObjectTag('minecraft:stick', { aer: 1, ignis: 2 });
|
||
|
||
// 移除
|
||
thaumcraft.removeObjectTag('minecraft:stick');
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 替换已有配方
|
||
|
||
```js
|
||
ServerEvents.recipes(event => {
|
||
// 先删
|
||
thaumcraft.removeInfusion('INFUSIONPROVIDER'); // 注魔
|
||
// thaumcraft.removeArcane('RESEARCH_KEY'); // 奥术
|
||
// thaumcraft.removeCrucible('RESEARCH_KEY'); // 坩埚
|
||
|
||
// 后注册，实现真正替换
|
||
event.recipes.thaumcraft.infusion(
|
||
'INFUSIONPROVIDER',
|
||
'thaumicenergistics:infusion_provider',
|
||
0,
|
||
['auram 10'],
|
||
'ae2:interface',
|
||
'minecraft:oak_planks'
|
||
);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 自定义研究分类 / 研究节点
|
||
|
||
### 添加研究分类
|
||
|
||
```js
|
||
ServerEvents.recipes(event => {
|
||
thaumcraft.addResearchCategory(
|
||
'MY_CATEGORY',
|
||
'textures/research/cat_icon.png',
|
||
'textures/research/cat_bg.png'
|
||
);
|
||
});
|
||
```
|
||
|
||
- 两个参数也可以：`addResearchCategory('MY_CATEGORY', 'textures/research/cat_icon.png')`
|
||
- 不带命名空间的路径默认使用 `kubejs:` 命名空间。
|
||
|
||
### 添加研究节点
|
||
|
||
```js
|
||
ServerEvents.recipes(event => {
|
||
thaumcraft.addResearchNode({
|
||
key: 'MY_RESEARCH',
|
||
category: 'MY_CATEGORY',
|
||
icon: 'textures/research/my_research.png',
|
||
parents: ['PARENT_KEY'],
|
||
autoUnlock: true, // 默认解锁
|
||
virtual: false, // 显示在魔导手册中；true 会隐藏
|
||
hidden: false,
|
||
col: 0,
|
||
row: 0,
|
||
complexity: 1,
|
||
aspects: { aer: 1, ignis: 1 }
|
||
});
|
||
});
|
||
```
|
||
|
||
支持字段：
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `key` | 研究节点唯一 ID |
|
||
| `category` | 所属研究分类，必须已存在 |
|
||
| `icon` | 图标路径 |
|
||
| `parents` / `parentsHidden` / `siblings` | 研究依赖关系 |
|
||
| `autoUnlock` | 是否默认解锁 |
|
||
| `virtual` | 是否虚拟节点（`true` 不会显示在魔导手册） |
|
||
| `hidden` / `concealed` / `lost` | 可见性控制 |
|
||
| `special` / `stub` / `secondary` / `round` | 研究类型标记 |
|
||
| `col` / `row` / `complexity` | 研究树位置和复杂度 |
|
||
| `aspects` | 研究关联要素 |
|
||
|
||
### 图标文件位置
|
||
|
||
脚本里写：
|
||
|
||
```js
|
||
icon: 'textures/research/my_research.png'
|
||
```
|
||
|
||
对应文件：
|
||
|
||
```text
|
||
kubejs/assets/kubejs/textures/research/my_research.png
|
||
```
|
||
|
||
也可以写完整路径：
|
||
|
||
```js
|
||
icon: 'kubejs:textures/research/my_research.png'
|
||
```
|
||
|
||
### 研究名称 / 描述
|
||
|
||
TC 的研究名称通过语言文件翻译。
|
||
在 `kubejs/assets/kubejs/lang/zh_cn.json` 中添加：
|
||
|
||
```json
|
||
{
|
||
"tc.research_category.MY_CATEGORY": "我的分类",
|
||
"tc.research_name.MY_RESEARCH": "我的研究",
|
||
"tc.research_text.MY_RESEARCH": "这是研究描述。"
|
||
}
|
||
```
|
||
|
||
英文则写在 `kubejs/assets/kubejs/lang/en_us.json`。
|
||
|
||
---
|
||
## 要素 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` |
|
||
|
||
## 热重载说明
|
||
|
||
| 内容 | `/reload` | 说明 |
|
||
|---|---|---|
|
||
| 注魔 / 坩埚 / 奥术配方 | ✅ | 可以热重载 |
|
||
| 物品固有要素 | ✅ | 可以热重载 |
|
||
| 研究分类 / 研究节点 | ❌ | TC 研究系统缓存较多，需要重启游戏 |
|
||
|
||
### research 键说明
|
||
|
||
- 如果 `research` 不是 TC 已有研究，桥接会自动注册一个**默认解锁的虚拟研究节点**，并按“无研究要求”处理。
|
||
- 如果 `research` 是 TC 已有研究，则仍然要求玩家完成对应研究。
|
||
- `research` 键全局唯一，重复键会被跳过。
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
## 排障
|
||
|
||
| 现象 | 原因 |
|
||
|---|---|
|
||
| `Constructor for thaumcraft:arcane_shapeless with N arguments not found` | 材料没有放在数组里 |
|
||
| `Unknown aspect 'xxx'` | 要素 tag 写错 |
|
||
| `Item with ID xxx does not exist` | 物品 id 错误 |
|
||
| 研究分类名字显示为 `tc.research_category.XXX` | 缺少语言文件 |
|
||
| 研究图标 / 背景紫黑色 | 贴图不存在、路径不对、不是 PNG，或 KubeJS assets 未被加载 |
|
||
| `event.thaumcraft is undefined` | 顶层绑定是 `thaumcraft.xxx`，不是 `event.thaumcraft.xxx` |
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
src/main/java/tckubejsbridge/
|
||
├── TCKubeJSBridge.java // @Mod 主类
|
||
└── kubejs/
|
||
├── TCKubeJSPlugin.java // KubeJS 插件：schema + bindings
|
||
├── TCRecipeKJS.java // 自定义 KubeRecipe 基类
|
||
├── TCRecipeBridge.java // TC API 调用 / 去重 / 移除 / 研究注册
|
||
├── AspectListComponent.java // 源质列表组件
|
||
├── InfusionRecipeKJS.java // 注魔配方
|
||
├── CrucibleRecipeKJS.java // 坩埚配方
|
||
├── ShapedArcaneRecipeKJS.java // 奥术有序配方
|
||
└── ShapelessArcaneRecipeKJS.java // 奥术无序配方
|
||
|
||
src/main/resources/
|
||
├── kubejs.plugins.txt // 插件发现文件
|
||
└── META-INF/neoforge.mods.toml
|
||
|
||
example/infusion_example.js // 示例脚本
|
||
```
|