KubeJS Library — Reference
Custom Blocks and Items
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.
Common Item Properties:
| Property | Method | Description |
|:--- |:--- |:--- |
| Display Name | .displayName('Name') | Sets the name shown in-game. |
| Max Stack | .maxStackSize(int) | Sets the maximum stack size (default 64). |
| Rarity | .rarity('rare') | Changes the color of the item name (common, uncommon, rare, epic). |
| Glow | .glow(true) | Gives the item a permanent enchantment glint. |
| Tooltip | .tooltip('Text') | Adds a static description to the item. |
Custom Blocks
Blocks are more complex and support properties like hardness, blast resistance, and tool requirements.
Common Block Properties:
| Property | Method | Description |
|:--- |:--- |:--- |
| Material | .mapColor('color') | Sets the color on maps and material type. |
| Hardness | .hardness(float) | Determines how long it takes to mine. |
| Resistance | .resistance(float) | Determines explosion resistance. |
| Light Level | .lightLevel(float) | Sets the amount of light emitted (0.0 to 1.0). |
| Tool Tier | .tagBlock('mineable/pickaxe') | Assigns the block to a specific mining category. |
Recipe Management
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.
| Removal Type | Syntax Example |
|---|---|
| By Output | event.remove({output: 'minecraft:stick'}) |
| By ID | event.remove({id: 'minecraft:glowstone'}) |
| By Mod | event.remove({mod: 'ironchest'}) |
| By Type | event.remove({type: 'minecraft:campfire_cooking'}) |
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')
Entity and Mob Modification
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
| Event | Description | Use Case |
|---|---|---|
entity.spawned |
Fired when a mob enters the world. | Increase health or speed of specific mobs. |
entity.hurt |
Fired when a mob takes damage. | Create custom damage resistances or thorns effects. |
entity.death |
Fired when a mob dies. | Add custom drops or trigger explosions on death. |
entity.check_spawn |
Fired before a mob spawns. | Prevent specific mobs from spawning in certain biomes. |
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.
Worldgen and Biomes
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.