kubejs-thaumcraft/README_EN.md

TC KubeJS Bridge (tckubejsbridge)

English | 中文

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.

# Run from the repository root
gradle :tckubejsbridge:build

Artifact:

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

For example:

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

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

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

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.

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

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

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

---

Replacing Existing Recipes

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

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

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:

icon: 'textures/research/my_research.png'

The file should be at:

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

You can also use a full path:

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:

{
  "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

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