KubeJS Library — Guide
Script Types and Locations
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
| Folder | Purpose | Reload Method |
|---|---|---|
startup_scripts/ |
Used for registries (blocks, items, fluids) and worldgen modifications. | Requires game restart or /kubejs reload startup_scripts. |
server_scripts/ |
Used for recipes, tags, loot tables, and server events. | Use /reload or /kubejs reload server_scripts. |
client_scripts/ |
Used for tooltips, JEI/REI hiding, and client-side assets. | Use F3 + T or /kubejs reload client_scripts. |
Reloading Mechanics
- Server Scripts: These are the most commonly used. Running
/reloadin-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.
Mechanics and Utilities
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('') (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.