KubeJS Library Wiki

KubeJS is a powerful utility mod designed for Minecraft, and beyond. It utilizes a fork of the Rhino JavaScript engine by Mozilla to convert JS code into Java classes at runtime. This allows for deep integration with Minecraft's internal systems without the need for complex Java development environments.

By wrapping Minecraft classes and utilizing the Architectury framework, KubeJS provides a unified API for both Forge and Fabric/Quilt loaders. It is primarily used to:

• Create entirely new items and blocks with custom properties.
• Modify or remove recipes from any mod.
• Change block and item tags.
• Handle complex server-side events like player interactions and entity deaths.
• Customize the user interface and tooltips on the client side.

KubeJS scripts are organized into three distinct folders within the /kubejs/ directory of your Minecraft instance. Each folder serves a specific purpose and has different reloading rules.

Script Folders

Reloading Mechanics

• Server Scripts: These are the most commonly used. Running /reload in-game will re-read all scripts in this folder, allowing you to test recipe changes instantly.
• Startup Scripts: Because these scripts register new objects into the game's registry, they generally require a full game restart to take effect, though some simple modifications can be reloaded via command.
• Client Scripts: These handle visual elements. Reloading them usually requires refreshing the game's resource manager.

KubeJS allows you to register new content in the startup_scripts folder. These custom objects are added to the kubejs namespace (e.g., kubejs:example_item).

Custom Items

Items can be created with various properties such as rarity, stack size, and special effects.

Custom Blocks

Blocks are more complex and support properties like hardness, blast resistance, and tool requirements.

One of the core features of KubeJS is the ability to manipulate recipes from any mod that uses the standard Minecraft datapack system. This is done in the server_scripts folder using the ServerEvents.recipes event.

Adding Recipes

KubeJS supports all vanilla recipe types and many modded ones.

• Shaped: event.shaped('output', ['AAA', ' B ', 'AAA'], {A: 'ingredient1', B: 'ingredient2'})
• Shapeless: event.shapeless('output', ['input1', 'input2'])
• Smelting/Blasting: event.smelting('output', 'input')

Removing Recipes

You can remove recipes by output, ID, mod, or type.

Modifying Existing Recipes

You can replace specific inputs or outputs across all recipes in the game:

• event.replaceInput({input: 'minecraft:iron_ingot'}, 'minecraft:iron_ingot', 'minecraft:gold_ingot')
• event.replaceOutput({}, 'minecraft:stone', 'minecraft:cobblestone')

While KubeJS is a library and does not add new mob entities by default, it provides an exhaustive event system to modify every creature in the game. This is handled via EntityEvents in server scripts.

Mob Mechanics

Example Behaviors:

• Custom Drops: By listening to entity.death, you can check the entity type and manually spawn items at its location, effectively creating custom loot tables.
• Stat Scaling: You can use entity.spawned to check the player's progression (using Game Stages) and buff mobs accordingly by modifying their attributes.

KubeJS can modify the world generation process through WorldgenEvents. This allows modpack creators to fine-tune the distribution of resources and features.

• Adding Features: You can add new ore veins, trees, or lake features to specific biomes or biome categories.
• Removing Features: You can remove vanilla features like diorite/andesite veins or specific structures to clean up the world generation.
• Biome Properties: Through client scripts, you can modify the visual properties of biomes, such as changing the water color, fog color, or grass tint to create a unique atmosphere.

KubeJS includes several built-in utilities to simplify complex tasks.

Text and Chat

The Text utility allows for advanced chat formatting, including colors, click events, and hover tooltips.

• Text.green('Success!').bold
• Text.of('Click here').click('https://example.com') (Note: External links are handled by the Minecraft client).

Scheduling

You can schedule tasks to run after a certain amount of time:

• server.scheduleInTicks(20, callback) - Runs code after 1 second (20 ticks).

NBT Handling

KubeJS provides full access to NBT (Named Binary Tag) data. You can read, modify, and write NBT to item stacks, entities, and block entities (like chests or furnaces).

Inventory and Items

• Item Stacks: Use Item.of('id') to create item objects with custom NBT or counts.
• Ingredients: Use Ingredient.of('#tag') to refer to groups of items in recipes.

KubeJS adds several administrative commands to help with script development and debugging.