# TC KubeJS Bridge (tckubejsbridge)

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

Bridges the **Thaumcraft 4 (port)** recipe and research systems to **KubeJS**.

Modpack authors can use scripts in `kubejs/server_scripts/` to register:

- Infusion recipes
- Crucible recipes
- Shaped / shapeless arcane recipes
- Item aspect tags
- Custom research categories / research nodes
- Replacing existing TC recipes

Author: AlkSur ｜ License: GPL-3.0

---

## Requirements

| Mod | Version | Relation |
|---|---|---|
| NeoForge | 21.1.234 | Required |
| Minecraft | 1.21.1 | Required |
| Thaumcraft (TC4 port) | 0.2.2.34-port.1 | Required |
| KubeJS (NeoForge) | 2101.7.x | Required (plugin depends on its API) |

> KubeJS is declared **optional** in `neoforge.mods.toml`: without KubeJS the plugin part
> simply does not load, and the game still starts.

---

## Building & Installation

The project lives at `modules/tc-kubejs-bridge` inside a multi-module Gradle build.

```bash
# Run from the repository root
gradle :tckubejsbridge:build
```

Artifact:

```text
modules/tc-kubejs-bridge/build/libs/KubeJS Thaumcraft-<mod_version>+<neoforge_version>.jar
```

For example:

```text
KubeJS Thaumcraft-1.0.0+21.1.234.jar
```

Put the jar into your `mods/` folder.

---

## Quick Start

1. Create a `.js` file under `kubejs/server_scripts/`.
2. Use `ServerEvents.recipes(event => { ... })`.
3. Run `/reload` or restart the game.

All `thaumcraft.xxx` calls are **top-level bindings**; do not use `event.thaumcraft.xxx`.

---

## Recipe Registration

### 1. Infusion Recipe

```js
ServerEvents.recipes(event => {
    event.recipes.thaumcraft.infusion(
        'MY_INFUSION',               // research key (globally unique)
        'minecraft:diamond',         // result
        3,                           // instability
        ['ignis 64', 'potentia 32'], // required aspects
        'minecraft:golden_apple',    // central item
        'minecraft:blaze_rod',       // component
        'minecraft:ender_pearl'
    );
});
```

### 2. Crucible Recipe

```js
ServerEvents.recipes(event => {
    event.recipes.thaumcraft.crucible(
        'MY_CRUCIBLE',
        'minecraft:diamond',
        'minecraft:coal',            // catalyst
        { aer: 16, ignis: 8 }        // object syntax also works
    );
});
```

### 3. Shaped Arcane Recipe

```js
ServerEvents.recipes(event => {
    event.recipes.thaumcraft.arcane(
        'MY_ARCANE',
        'minecraft:diamond_sword',
        ['ignis 16', 'ordo 8'],
        [' I ', ' I ', ' S '],       // pattern: up to 3 rows
        { I: 'minecraft:iron_ingot', S: 'minecraft:stick' }
    );
});
```

### 4. Shapeless Arcane Recipe

> Note: `arcane_shapeless` ingredients must be provided as **one array**.

```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'
        ]
    );
});
```

---

## Item Aspect Tags

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

    // remove
    thaumcraft.removeObjectTag('minecraft:stick');
});
```

---

## Replacing Existing Recipes

```js
ServerEvents.recipes(event => {
    // remove first
    thaumcraft.removeInfusion('INFUSIONPROVIDER');  // infusion
    // thaumcraft.removeArcane('RESEARCH_KEY');     // arcane
    // thaumcraft.removeCrucible('RESEARCH_KEY');   // crucible

    // then register a new recipe
    event.recipes.thaumcraft.infusion(
        'INFUSIONPROVIDER',
        'thaumicenergistics:infusion_provider',
        0,
        ['auram 10'],
        'ae2:interface',
        'minecraft:oak_planks'
    );
});
```

---

## Custom Research Categories / Nodes

### Add a Research Category

```js
ServerEvents.recipes(event => {
    thaumcraft.addResearchCategory(
        'MY_CATEGORY',
        'textures/research/cat_icon.png',
        'textures/research/cat_bg.png'
    );
});
```

- A two-argument form is also available: `addResearchCategory('MY_CATEGORY', 'textures/research/cat_icon.png')`
- Paths without a namespace default to the `kubejs:` namespace.

### Add a Research Node

```js
ServerEvents.recipes(event => {
    thaumcraft.addResearchNode({
        key: 'MY_RESEARCH',
        category: 'MY_CATEGORY',
        icon: 'textures/research/my_research.png',
        parents: ['PARENT_KEY'],
        autoUnlock: true,   // unlocked by default
        virtual: false,     // visible in the Thaumonomicon; true hides it
        hidden: false,
        col: 0,
        row: 0,
        complexity: 1,
        aspects: { aer: 1, ignis: 1 }
    });
});
```

Supported fields:

| Field | Description |
|---|---|
| `key` | Unique research node ID |
| `category` | Existing research category |
| `icon` | Icon path |
| `parents` / `parentsHidden` / `siblings` | Research dependencies |
| `autoUnlock` | Unlocked by default |
| `virtual` | Hidden from the Thaumonomicon when `true` |
| `hidden` / `concealed` / `lost` | Visibility flags |
| `special` / `stub` / `secondary` / `round` | Research type flags |
| `col` / `row` / `complexity` | Position and complexity on the research map |
| `aspects` | Associated aspects |

### Icon File Location

If you write:

```js
icon: 'textures/research/my_research.png'
```

The file should be at:

```text
kubejs/assets/kubejs/textures/research/my_research.png
```

You can also use a full path:

```js
icon: 'kubejs:textures/research/my_research.png'
```

### Research Names / Descriptions

TC research names use language files.  
Add this to `kubejs/assets/kubejs/lang/en_us.json`:

```json
{
  "tc.research_category.MY_CATEGORY": "My Category",
  "tc.research_name.MY_RESEARCH": "My Research",
  "tc.research_text.MY_RESEARCH": "This is a research description."
}
```

For Chinese, add the same keys to `kubejs/assets/kubejs/lang/zh_cn.json`.

---
## Aspect Tag Reference (actual values in the TC4 port)

**Important: the port uses the original Latin tags, not the TC4 English/localized names.**

| Aspect | Tag | Aspect | 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` |

## Hot Reload

| Content | `/reload` | Notes |
|---|---|---|
| Infusion / Crucible / Arcane recipes | ✅ | Can be hot-reloaded |
| Item aspect tags | ✅ | Can be hot-reloaded |
| Research categories / nodes | ❌ | Requires a game restart |

### Research key notes

- If `research` is **not** an existing TC research, the bridge registers a default-unlocked virtual research node and treats the recipe as having **no research requirement**.
- If `research` **is** an existing TC research, the recipe still requires that research to be completed.
- Research keys are globally unique; duplicate keys are skipped.
   
   
     
     
   
     

   
     
       
     
       

   
   
   
   


   

   

   
   

## Troubleshooting

| Symptom | Cause |
|---|---|
| `Constructor for thaumcraft:arcane_shapeless with N arguments not found` | Ingredients were not placed in an array |
| `Unknown aspect 'xxx'` | Wrong aspect tag |
| `Item with ID xxx does not exist` | Wrong item id |
| Research category name shows `tc.research_category.XXX` | Missing language file |
| Research icon / background is purple-black | Texture missing, wrong path, not a PNG, or KubeJS assets not loaded |
| `event.thaumcraft is undefined` | Use top-level `thaumcraft.xxx`, not `event.thaumcraft.xxx` |

## Project Layout

```text
src/main/java/tckubejsbridge/
├── TCKubeJSBridge.java            // @Mod main class
└── kubejs/
    ├── TCKubeJSPlugin.java        // KubeJS plugin: schemas + bindings
    ├── TCRecipeKJS.java           // Custom KubeRecipe base
    ├── TCRecipeBridge.java        // TC API calls / dedup / removal / research registration
    ├── AspectListComponent.java   // Aspect list component
    ├── InfusionRecipeKJS.java     // Infusion recipe
    ├── CrucibleRecipeKJS.java     // Crucible recipe
    ├── ShapedArcaneRecipeKJS.java // Shaped arcane recipe
    └── ShapelessArcaneRecipeKJS.java // Shapeless arcane recipe

src/main/resources/
├── kubejs.plugins.txt             // Plugin discovery file
└── META-INF/neoforge.mods.toml

example/infusion_example.js        // Example script
```