KubeJS

https://kubejs.com
Admin
KubeJS is a Minecraft mod that lets you customize your modpack or server using JavaScript to manage...
Tokens:198,781
Snippets:1,428
Trust Score:7.5
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example usage of sound() method

Source: https://kubejs.com/wiki/tutorials/fluid-registry

Example of using the sound() method with loaded SoundActions and SoundEvents classes.

```javascript
sound($SoundActions.BUCKET_FILL, $SoundEvents.AMETHYST_BLOCK_BREAK)
```

--------------------------------

### Create Sequenced Assembly Recipes

Source: https://kubejs.com/wiki/addons/create

Examples of defining sequenced assembly recipes for precision mechanisms and spore blossoms. The first example uses a fixed number of loops, while the second demonstrates using a constant for the transitional item.

```javascript
ServerEvents.recipes(event => {
  event.recipes.create.sequenced_assembly(
      // Outputs:
      [
        CreateItem.of('create:precision_mechanism', 0.13), // Main output, will appear in JEI as the result
        CreateItem.of('create:golden_sheet', 0.008), // Rest of these items will be considered Random Salvage
        CreateItem.of('create:andesite_alloy', 0.008),
        CreateItem.of('create:cogwheel', 0.005),
        CreateItem.of('create:shaft', 0.002),
        CreateItem.of('create:crushed_gold_ore', 0.002),
        CreateItem.of('2x minecraft:gold_nugget', 0.002),
        CreateItem.of('minecraft:iron_ingot', 0.001),
        CreateItem.of('minecraft:clock', 0.001)
      ],
      // Input:
      'create:golden_sheet', 
      // Sequence:
      [
        // The transitional item set by `transitionalItem('create:incomplete_large_cogwheel')` is the item used during the intermediate stages of the assembly
        // Like a normal recipe function, it's used as a sequence step in this array. Input and output have the transitional item
        event.recipes.create.deploying('create:incomplete_precision_mechanism', ['create:incomplete_precision_mechanism', 'create:cogwheel',]),
        event.recipes.create.deploying('create:incomplete_precision_mechanism', ['create:incomplete_precision_mechanism', 'create:large_cogwheel',]),
        event.recipes.create.deploying('create:incomplete_precision_mechanism', ['create:incomplete_precision_mechanism', 'minecraft:iron_nugget',]),
      ]
    )
    .transitionalItem('create:incomplete_precision_mechanism') // Set the transitional item
    .loops(5) // Set the number of loops

  // For this code to work, kubejs:incomplete_spore_blossom needs to be added to the game
  const transitional = 'kubejs:incomplete_spore_blossom' // Making a constant to store the transitional item makes the code more readable
  event.recipes.create.sequenced_assembly(
      // Outputs:
      [
        CreateItem.of('minecraft:spore_blossom', 0.16), // Main output, will appear in JEI as the result
        CreateItem.of('minecraft:flowering_azalea_leaves', 0.16), // Rest of these items will be considered Random Salvage
        CreateItem.of('minecraft:azalea_leaves', 0.02),
        CreateItem.of('minecraft:oak_leaves', 0.01),
        CreateItem.of('minecraft:spruce_leaves', 0.01),
        CreateItem.of('minecraft:birch_leaves', 0.01),
        CreateItem.of('minecraft:jungle_leaves', 0.01),
        CreateItem.of('minecraft:acacia_leaves', 0.01),
        CreateItem.of('minecraft:dark_oak_leaves', 0.01)
      ],
      // Input:
      'minecraft:flowering_azalea_leaves',
      // Sequence:
      [
        // The transitional item is a constant, that is 'kubejs:incomplete_spore_blossom' and is used during the intermediate stages of the assembly.
        // Like a normal recipe function, is used as a sequence step in this array. Input and output have the transitional item.
        event.recipes.create.pressing(transitional, transitional),
        event.recipes.create.deploying(transitional, [transitional, 'minecraft:hanging_roots']),
        event.recipes.create.filling(transitional, [transitional, Fluid.of('minecraft:water', 420)]),
        event.recipes.create.deploying(transitional, [transitional, 'minecraft:moss_carpet']),
        event.recipes.create.cutting(transitional, transitional)
      ]
    )
    .transitionalItem(transitional) // Set the transitional item
    .loops(2) // Set the number of loops
})
```

--------------------------------

### Example usage of ServerEvents.compostableRecipes

Source: https://kubejs.com/wiki/events/ServerEvents/compostableRecipes

Example script showing how to add, remove, and clear compostable items using the event. The event is not cancellable and should be placed in the server_scripts folder.

```javascript
ServerEvents.compostableRecipes(event => {
  event.add('minecraft:nether_star', 0.25)
  event.add('#minecraft:leaves', 0.5)

  event.remove('minecraft:wheat_seeds')
  event.remove('#minecraft:saplings')

  event.removeAll()
})
```

--------------------------------

### Multiple Machines Example

Source: https://kubejs.com/wiki/addons/kubejs-tfmg

Example of adding multiple machines to a vat recipe by repeating the machine type in the machines method. This requires three electrodes.

```javascript
.machines("tfmg:electrode", "tfmg:electrode", "tfmg:electrode")
```

--------------------------------

### Registering basic commands for 1.21+

Source: https://kubejs.com/wiki/events/ServerEvents/basicCommand

Examples of using ServerEvents.basicCommand to create an icon command and a heal command for Minecraft 1.21 and newer.

```javascript
ServerEvents.basicCommand('icons', event => {
	// Will print KubeJS icons from their characters, try `/icons BCDEFIJKNTWY`
	event.server.tell(TextIcons.icon(event.input))
})

ServerEvents.basicCommand('heal', event => {
	// Will heal the player
	event.player.heal()
})
```

--------------------------------

### @modify comment example

Source: https://kubejs.com/wiki/addons/probejs/document-specification

Attach @modify with a parameter name and a type to change the type of that method parameter. This example changes the key parameter of get() from Object to K.

```typescript
/**
 * @target java.util.Map
 */
class Map {
    /**
     * @modify key K
     */
    get(key: java.lang.Object): V;
}
```

--------------------------------

### Register a custom portal with PortalEvents.register

Source: https://kubejs.com/wiki/addons/portaljs

Use this snippet in startup scripts to create a custom portal. It demonstrates required and optional configuration methods such as frameBlock, setDestination, lightWithItem, lightWithWater, lightWithFluid, customIgnitionSource, forcedSize, returnDim, onlyLightInOverworld, flatPortal, tint, beforeTeleportation, afterTeleportation, and ambience sounds. The example includes comments explaining each option and shows how to cancel teleportation for non-player entities.

```javascript
PortalEvents.register(event => {
  // Here is where we start a new portal
  event.create()
    // (required) Set the frame block for the portal
    .frameBlock("minecraft:dirt")

    // Set the dimension to travel to when the portal is used
    .setDestination("minecraft:the_nether")

    // Now you can do one of the following (default flint and steel):
    // This lights the portal with a grass block
    .lightWithItem("minecraft:grass_block")

    // Lights the portal with water
    .lightWithWater()

    // Light the portal with a fluid
    .lightWithFluid("minecraft:lava")

    // (Optional) Custom ignition source by the namespace and path (as in mod_id:some_source)
    .customIgnitionSource("mod:source")

    // (optional) Set a forced size for the portal (width, height)
    .forcedSize(4, 5)

    // (Optional) Configure the portal's return dimension. `onlyIgniteInReturnDimension` specifies if the portal can only be ignited in the return dimension
    .returnDim("minecraft:the_end", true)

    // Or, you can just do .returnDim("minecraft:the_end") (false is the default)

    // (Optional) Restrict portal ignition to the Overworld. Use this if you want the portal to be ignitable only in the Overworld
    .onlyLightInOverworld()

    // (Optional) Use the flat portal style, similar to the End Portal
    .flatPortal()

    // (Optional) Set the RGB color for the portal's tint
    .tint(r, g, b) // (red, green, blue)
    // .tint(0x) // You can do your 0x[hex color code] here as well

    // .tintColor(r, g, b) // does the game thing as tint

    // (Optional) Event handling before/after the entity gets teleported
    .beforeTeleportation(entity => {
      // Example logic: cancel for non-player entities
      return entity instanceof Player ? ShouldTP.CONTINUE : ShouldTP.CANCEL
    })
    .afterTeleportation(entity => {
       // Example logic for after teleportation
       console.log("Teleported: " + entity.getName().getString())
    })

    // (optional) Create a sound from sound event data to play to the player before/after teleportation
    // Example: play the ALLAY_THROW sound at pitch 1 and volume 1
    .inPortalAmbienceSound(SoundEvents.ALLAY_THROW, 1, 1)

    // Example: play the ALLAY_DEATG sound at pitch 1 and volume 1
    .afterTeleportationAmbienceSound(SoundEvents.ALLAY_DEATH, 1, 1)
})
```

--------------------------------

### Cancel chat event when message starts with '!some_command' (1.18.2 and below)

Source: https://kubejs.com/wiki/tutorials/chat

Same functionality as the 1.19.2+ example but using the onEvent('player.chat') syntax for older versions. Cancels the event and replies 'Hi!' when the message starts with '!some_command'.

```javascript
onEvent('player.chat', event => {
  // Check if message starts with "!some_command"
  if (event.message.startsWith('!some_command')) {
    // Reply to the player and cancel the event
    event.player.tell('Hi!')
    event.cancel()
  }
})
```

--------------------------------

### Deploying recipes for 1.19.2 - 1.20.1

Source: https://kubejs.com/wiki/addons/create

Example for Create mod versions 1.19.2 to 1.20.1 using Item.of with withChance for chance-based outputs. Shows basic deploying, multiple outputs with keepHeldItem, and chance-based output.

```javascript
ServerEvents.recipes(event => {
  event.recipes.create.deploying('minecraft:diamond', ['minecraft:coal_block', 'minecraft:sand'])
  event.recipes.create.deploying(['minecraft:diamond', 'minecraft:emerald'], ['minecraft:coal_block', 'minecraft:sand']).keepHeldItem()
  event.recipes.create.deploying(['minecraft:diamond', Item.of('minecraft:diamond').withChance(0.5)], ['minecraft:coal_block', 'minecraft:sand'])
})
```

--------------------------------

### Centrifugation recipe examples

Source: https://kubejs.com/wiki/addons/vintage-kubejs

Centrifugation uses the Centrifuge with installed Basins. Supports multiple chance-based outputs, fluid inputs/outputs, and .processingTime() and .minimalRPM() methods.

```javascript
ServerEvents.recipes(event => {
  event.recipes.vintageimprovements.centrifugation(Fluid.of('create:honey', 1000), 'minecraft:honey_block', 100, 64)
  event.recipes.vintageimprovements.centrifugation(Fluid.of('create:honey', 1000), 'minecraft:honey_block').processingTime(100).minimalRPM(64)
  event.recipes.vintageimprovements.centrifugation([Item.of('minecraft:stick').withChance(0.5), 'minecraft:dead_bush'], '#minecraft:saplings').minimalRPM(128)
})
```

--------------------------------

### Deploying recipes for 1.21.1

Source: https://kubejs.com/wiki/addons/create

Example for Create mod version 1.21.1 using CreateItem.of for chance-based outputs. Shows basic deploying, multiple outputs with keepHeldItem, and chance-based output.

```javascript
ServerEvents.recipes(event => {
  event.recipes.create.deploying('minecraft:diamond', ['minecraft:coal_block', 'minecraft:sand'])
  event.recipes.create.deploying(['minecraft:diamond', 'minecraft:emerald'], ['minecraft:coal_block', 'minecraft:sand']).keepHeldItem()
  event.recipes.create.deploying(['minecraft:diamond', CreateItem.of('minecraft:diamond', 0.5)], ['minecraft:coal_block', 'minecraft:sand'])
})
```

--------------------------------

### PlayerEvents.loggedIn - persistentData example (1.20.4)

Source: https://kubejs.com/wiki/tips/persistent-data

Example of using persistentData with bean syntax for 1.20.4.

```APIDOC
## PlayerEvents.loggedIn

### Description
Event handler that runs when a player logs in. Uses persistentData to check if it's the player's first join and gives items.

### Event
`PlayerEvents.loggedIn`

### Example
```js
PlayerEvents.loggedIn(event => {
  const pData = event.player.persistentData
  if (!pData.firstJoin) {
    pData.firstJoin = true
    // Do stuff only on first join, here we give the player some diamonds and a sword
    event.player.give('29x diamond')
    event.player.give('minecraft:diamond_sword[damage=2]')
  }
})
```
```

--------------------------------

### deploying(output[], input[])

Source: https://kubejs.com/wiki/addons/create

Adds a Create deploying recipe using the Deployer. Supports multiple chance-based outputs, requires exactly two inputs (the second is the item held by the Deployer), and supports .keepHeldItem().

```APIDOC
## deploying(output[], input[])

### Description
Adds a Create deploying recipe using the Deployer. Supports multiple chance-based outputs, requires exactly two inputs (the second is the item held by the Deployer), and supports `.keepHeldItem()`.

### Method
`deploying(output[], input[])`

### Parameters
- **output** (array) - Required - The output item(s). Can be a single item string, an array of items, or an array with chance-based items (e.g., `CreateItem.of('minecraft:diamond', 0.5)` or `Item.of('minecraft:diamond').withChance(0.5)`).
- **input** (array) - Required - Exactly two inputs. The second input is the item held by the Deployer.

### Features
- Supports multiple chance-based outputs.
- Requires exactly two inputs.
- Supports `.keepHeldItem()` to keep the held item.

### Example
```js
ServerEvents.recipes(event => {
  event.recipes.create.deploying('minecraft:diamond', ['minecraft:coal_block', 'minecraft:sand'])
  event.recipes.create.deploying(['minecraft:diamond', 'minecraft:emerald'], ['minecraft:coal_block', 'minecraft:sand']).keepHeldItem()
  event.recipes.create.deploying(['minecraft:diamond', CreateItem.of('minecraft:diamond', 0.5)], ['minecraft:coal_block', 'minecraft:sand'])
})
```

```js
ServerEvents.recipes(event => {
  event.recipes.create.deploying('minecraft:diamond', ['minecraft:coal_block', 'minecraft:sand'])
  event.recipes.create.deploying(['minecraft:diamond', 'minecraft:emerald'], ['minecraft:coal_block', 'minecraft:sand']).keepHeldItem()
  event.recipes.create.deploying(['minecraft:diamond', Item.of('minecraft:diamond').withChance(0.5)], ['minecraft:coal_block', 'minecraft:sand'])
})
```
```

--------------------------------

### Turning recipe example

Source: https://kubejs.com/wiki/addons/vintage-kubejs

Registers a turning recipe that outputs 12 create fluid pipes from a copper block with a processing time of 300 ticks.

```javascript
ServerEvents.recipes(event => {
  event.recipes.vintageimprovements.turning(Item.of('create:fluid_pipe', 12), 'minecraft:copper_block').processingTime(300)
})
```

--------------------------------

### Example usage of addDripstoneDripping() method

Source: https://kubejs.com/wiki/tutorials/fluid-registry

Example of using the addDripstoneDripping() method with a particle type and sound event.

```javascript
addDripstoneDripping(1, $ParticleTypes.DRIPPING_DRIPSTONE_LAVA, 'minecraft:lava_cauldron', $SoundEvents.POINTED_DRIPSTONE_DRIP_LAVA)
```

--------------------------------

### Register a basic block with StartupEvents.registry

Source: https://kubejs.com/wiki/tutorials/block-registry

Registers a new block with ID 'kubejs:example_block'. KubeJS auto-generates a texture and the name 'Example Block' if resources are left alone.

```javascript
StartupEvents.registry('block', event => {
  event.create('example_block') // Create a new block with ID 'kubejs:example_block'
})
```

--------------------------------

### ProjectE.getPlayerEMC

Source: https://kubejs.com/wiki/addons/projecte

Gets the EMC value of a player. Always returns a string because EMC values can get very large.

```APIDOC
## ProjectE.getPlayerEMC

### Description
Gets the EMC value of a player. Always returns a string because EMC values can get very large.

### Method
`ProjectE.getPlayerEMC(player)`

### Parameters
- **player** (Player) - Required - The player whose EMC to get.

### Returns
- **string** - The player's EMC value as a string.

### Example
```js
const emc = ProjectE.getPlayerEMC(player)
player.tell('Your emc is ' + emc)
```
```

--------------------------------

### Creating a Ponder Scene

Source: https://kubejs.com/wiki/addons/ponder-for-kubejs

This example demonstrates how to register a scene for an item, show a structure, animate an entity, display colored text, and show controls with specific interactions.

```javascript
// for 1.18 pls use: onEvent("ponder.registry", event => { ... })
Ponder.registry((event) => {
    event.create("minecraft:paper").scene("our_first_scene", "First example scene", (scene, util) => {
        /**
         * Shows the whole structure.
         * Alternatively, `scene.showBasePlate()` can be used to show the base plate.
         * Useful for animating different parts of the structure.
         */
        scene.showStructure();
        
        /**
         * Encapsulate the structure bounds to given positions. This is useful if the custom structure has no proper bounds.
         * scene.showStructure() automatically encapsulates the bounds.
         */
        // scene.encapsulateBounds(blockPos)

        /**
         * idle(ticks) or idleSeconds(seconds) is used to wait for a certain amount of time.
         * 20 ticks = 1 second
         */
        scene.idle(10);

        /**
         * `.createEntity()` returns an entity link from Create which will be used
         * as reference in the future
         * [x, y, z] is the position but any KubeJS way to represent a position can be used.
         *
         * Don't modify the entity directly!
         */
        const creeperLink = scene.world.createEntity("creeper", [2.5, 1, 2.5]);

        /**
         * 50 -> the tick length of the instruction
         * [x, y, z] -> the position that the text should point at
         */
        scene
            .text(60, "Example text", [2, 2.5, 2.5])
            /**
             * Optional | Sets the color of the text.
             * Possible values:
             * - PonderPalette.WHITE, PonderPalette.BLACK
             * - PonderPalette.RED, PonderPalette.GREEN, PonderPalette.BLUE
             * - PonderPalette.SLOW, PonderPalette.MEDIUM, PonderPalette.FAST
             * - PonderPalette.INPUT, PonderPalette.OUTPUT
             */
            .colored(PonderPalette.RED)
            /**
             * Optional | Places the text closer to the target position.
             */
            .placeNearTarget()
            /**
             * Optional | Adds a keyframe to the scene.
             */
            .attachKeyFrame();

        /**
         * 120 -> the tick length of the instruction
         * [x, y, z] -> the position that the controls should point at
         * "down" -> the direction that is used by the controls for pointing
         */
        scene
            .showControls(60, [2.5, 3, 2.5], "down")
            /**
             * Uses mouse right click as icon.
             * Alternatively, `.leftClick()` can be used
             * or `.showing(icon)` for a custom icon.
             */
            .rightClick()

            // Defines the item that should be shown with the icon.
            .withItem("shears")

            /**
             * Optional | Defines that controls are only shown when sneaking.
             * `.whileSneaking()` and `.withCTRL()` can not be used simultaneously.
             */
            .whileSneaking()
            
            /**
             * Optional | Defines that controls are only shown when holding CTRL.
             * `.whileSneaking()` and `.withCTRL()` can not be used simultaneously.
             */
            .whileCTRL();
    });
});
```

--------------------------------

### PlayerEvents.loggedIn - persistentData example (1.20.1 - 1.19.2)

Source: https://kubejs.com/wiki/tips/persistent-data

Example of using persistentData with bean syntax and Item.of for older versions.

```APIDOC
## PlayerEvents.loggedIn

### Description
Event handler that runs when a player logs in. Uses persistentData to check if it's the player's first join and gives items.

### Event
`PlayerEvents.loggedIn`

### Example
```js
PlayerEvents.loggedIn(event => {
	const pData = event.player.persistentData
	if (!pData.firstJoin) {
		pData.firstJoin = true
		// Do stuff only on first join, here we give the player some diamonds and a sword
		event.player.give('29x diamond')
		event.player.give(Item.of('minecraft:diamond_sword', '{Damage:2}'))
	}
})
```
```

--------------------------------

### Distillation recipe example (1.20.1)

Source: https://kubejs.com/wiki/addons/kubejs-tfmg

Creates a distillation recipe using the tfmg namespace. Requires one fluid ingredient and up to six fluid outputs. Output order is from bottom to top (lower to higher index).

```javascript
ServerEvents.recipes(event => {
  event.recipes.tfmg.distillation("minecraft:water", ["tfmg:air", "minecraft:lava"])
})
```

--------------------------------

### Section Animation Example

Source: https://kubejs.com/wiki/addons/ponder-for-kubejs

An example of registering a Ponder scene for a cake that shows sections layer by layer and then hides them.

```javascript
// for 1.18 use: onEvent("ponder.registry", event => { ... })
Ponder.registry((event) => {
    event
        .create("minecraft:cake")
        .scene("animate_section", "The cake is a lie.", "ponderjs:the_cake_is_a_lie", (scene, util) => {
            // Layer 0
            for (let x = 0; x < 5; x++) {
                for (let z = 0; z < 5; z++) {
                    scene.world.showSection([x, 0, z], Facing.DOWN);
                }
                // Idle can be used to create animations.
                scene.idle(3);
            }

            //Layer 1
            for (let z = 0; z < 5; z++) {
                for (let x = 0; x < 5; x++) {
                    scene.world.showSection([x, 1, z], Facing.DOWN);
                }
                scene.idle(3);
            }

            // Layer 2
            for (let x = 0; x < 5; x++) {
                for (let z = 0; z < 5; z++) {
                    scene.world.showSection([x, 2, z], Facing.DOWN);
                    scene.idle(2);
                }
            }

            // Top layer
            for (let x = 0; x < 5; x++) {
                for (let z = 0; z < 5; z++) {
                    scene.world.showSection([x, 3, z], Facing.DOWN);
                    scene.idle(1);
                }
            }

            scene.text(30, "What a great cake!", [2.5, 3.5, 2.5]);
            scene.idle(40);

            scene.world.hideSection([0, 0, 0, 1, 4, 1], Facing.NORTH);

            scene.text(30, "Yummy!", [1, 1.5, 2.5]).colored(PonderPalette.MEDIUM);
            scene.idle(40);
        });
});
```

--------------------------------

### PlayerEvents.loggedIn - persistentData example (1.21.1+)

Source: https://kubejs.com/wiki/tips/persistent-data

Example of using persistentData to detect a player's first join and give items.

```APIDOC
## PlayerEvents.loggedIn

### Description
Event handler that runs when a player logs in. Uses persistentData to check if it's the player's first join and gives items accordingly.

### Event
`PlayerEvents.loggedIn`

### Example
```js
PlayerEvents.loggedIn(event => {
	const pData = event.player.persistentData
	if (!pData.getBoolean('firstJoin')) {
		pData.putBoolean('firstJoin', true)
		// Do stuff only on first join, here we give the player some diamonds and a sword
		event.player.give('29x diamond')
		event.player.give('minecraft:diamond_sword[damage=2]')
	}
})
```
```

--------------------------------

### Atomizer recipe example

Source: https://kubejs.com/wiki/addons/alchemistry-chemlib/recipes

Creates an atomizer recipe that converts a fluid into an item. The input can be a fluid string or a Fluid object, and the output can be an item string or an Item object.

```javascript
ServerEvents.recipes(event => {
  event.recipes.alchemistry.atomizer("minecraft:lava", "minecraft:netherrack")
  event.recipes.alchemistry.atomizer(Fluid.of("minecraft:milk", 250), Item.of("chemlib:calcium", 8))
})
```

--------------------------------

### worldgen.remove event example script

Source: https://kubejs.com/wiki/tutorials/worldgen/1605

Example script for the worldgen.remove event, demonstrating how to remove ores, spawns by ID, and spawns by category.

```javascript
onEvent("worldgen.remove", event => {
  event.removeOres(ores => {
    ores.blocks = ["minecraft:coal_ore", "minecraft:iron_ore"] // Removes coal and iron ore
    ores.biomes.values = ["minecraft:plains"] // Removes it only from plains biomes
  })
  
  event.removeSpawnsByID(spawns => {
    spawns.entities.values = [
      "minecraft:cow",
      "minecraft:chicken",
      "minecraft:pig",
      "minecraft:zombie"
    ]
  })
  
  event.removeSpawnsByCategory(spawns => {
    spawns.biomes.values = [
      "minecraft:plains"
    ]
    spawns.categories.values = [
      "monster"
    ]
  })
})
```

--------------------------------

### Liquifier recipe example

Source: https://kubejs.com/wiki/addons/alchemistry-chemlib/recipes

Creates a liquifier recipe that converts an item into a fluid. The input can be an item string or an Item object, and the output can be a fluid string or a Fluid object.

```javascript
ServerEvents.recipes(event => {
  event.recipes.alchemistry.liquifier("minecraft:netherrack", "minecraft:lava")
  event.recipes.alchemistry.liquifier(Item.of("chemlib:calcium", 16), Fluid.of("minecraft:milk", 250))
})
```

--------------------------------

### @hidden comment example

Source: https://kubejs.com/wiki/addons/probejs/document-specification

Attach @hidden to a class, method, or field to exclude it from the generated dump. This example hides the campfireCooking field of RecipeEventJS.

```typescript
/**
* @target dev.latvian.mods.kubejs.recipe.RecipeEventJS
*/
class RecipeEventJS {
    /**
     * @hidden
     */
    campfireCooking: dev.latvian.mods.kubejs.recipe.RecipeFunction;
}
```

--------------------------------

### Compacting recipes for 1.19.2 - 1.20.1 (alternative syntax)

Source: https://kubejs.com/wiki/addons/create

Alternative example of compacting recipes using KubeJS for Create mod, using string tags and Item.of with withChance for chance-based output.

```javascript
ServerEvents.recipes(event => {
  event.recipes.create.compacting('minecraft:diamond', 'minecraft:coal_block')
  event.recipes.create.compacting('minecraft:diamond', 'minecraft:coal_block').heated()
  event.recipes.create.compacting('minecraft:diamond', 'minecraft:coal_block').superheated()
  event.recipes.create.compacting([Fluid.of('minecraft:water', 10), 'minecraft:dead_bush'], ['#minecraft:saplings', '#minecraft:saplings'])
  event.recipes.create.compacting(['minecraft:diamond', Item.of('minecraft:diamond').withChance(0.3)], 'minecraft:coal_block')
})
```

--------------------------------

### Casting recipe example (1.20.1)

Source: https://kubejs.com/wiki/addons/kubejs-tfmg

Creates a casting recipe using the tfmg namespace. Requires one fluid ingredient and up to three item outputs. Processing time defaults to 100 ticks if not specified.

```javascript
ServerEvents.recipes(event => {
  event.recipes.tfmg.casting("minecraft:lava", "minecraft:sand", 150)
})
```

--------------------------------

### Hide Recipes (1.19.2+)

Source: https://kubejs.com/wiki/addons/jei

Uses JEIEvents.removeRecipes to hide a recipe from JEI. Replace 'example:crafting_catagory' and 'example:item_or_recipe' with the category and recipe ID.

```javascript
JEIEvents.removeRecipes(event => {
  event.remove('example:crafting_catagory', 'example:item_or_recipe')
})
```

--------------------------------

### Spring Item Creation Example

Source: https://kubejs.com/wiki/addons/vintage-kubejs

Shows how to create a spring item using the Vintage Improvements KubeJS addon. Supports .setStiffness().

```javascript
ServerEvents.recipes(event => {
  event.create("small_spring", 'vintageimprovements:spring').texture("example:item/small_spring").tag("vintageimprovements:small_springs")
  event.create("spring", 'vintageimprovements:spring').texture("example:item/spring").tag("vintageimprovements:springs").setStiffness(150)
})
```

--------------------------------

### Vacuumizing recipe example

Source: https://kubejs.com/wiki/addons/vintage-kubejs

Registers a vacuumizing recipe that outputs a powder snow bucket from a bucket and a snow block with a processing time of 500 ticks.

```javascript
ServerEvents.recipes(event => {
  event.recipes.vintageimprovements.vacuumizing('minecraft:powder_snow_bucket', ['minecraft:bucket', 'minecraft:snow_block']).processingTime(500)
})
```

--------------------------------

### Hide Recipes (1.18.2 and below)

Source: https://kubejs.com/wiki/addons/jei

Uses onEvent('jei.remove.recipes') to hide a recipe from JEI. Replace 'example:crafting_catagory' and 'example:item_or_recipe' with the category and recipe ID.

```javascript
onEvent('jei.remove.recipes', event =>{
  event.remove('example:crafting_catagory', 'example:item_or_recipe')
})
```

--------------------------------

### Hide Items and Fluids (1.19.2+)

Source: https://kubejs.com/wiki/addons/jei

Uses JEIEvents.hideItems and JEIEvents.hideFluids to hide items and fluids from JEI. Replace 'example:ingredient' and 'example:fluid' with your targets.

```javascript
JEIEvents.hideItems(event => {
  event.hide('example:ingredient')
})

JEIEvents.hideFluids(event => {
  event.hide('example:fluid')
})
```

--------------------------------

### StartupEvents.registry('item')

Source: https://kubejs.com/wiki/tutorials/item-registry

Registers custom items in a startup script. The event is not cancellable and cannot be reloaded without restarting the game.

```APIDOC
## StartupEvents.registry('item')

### Description
Registers custom items in a startup script. The event is not cancellable and cannot be reloaded without restarting the game.

### Event
`StartupEvents.registry('item', event => { ... })`

### Parameters
- **event** (RegistryEvent) - The event object with a `create` method to define new items.

### Methods
#### `event.create(id, type?)`
Creates a new item with the given ID and optional type.
- **id** (string) - Required - The item ID (e.g., 'test_item').
- **type** (string) - Optional - The item type. Default is `basic`. Valid types: `basic`, `sword`, `pickaxe`, `axe`, `shovel`, `shears`, `hoe`, `helmet`, `chestplate`, `leggings`, `boots`.

#### Builder Methods (chainable after `create()`)
- `maxStackSize(size)` - Sets the maximum stack size.
- `unstackable()` - Sets max stack size to 1.
- `maxDamage(damage)` - Sets the maximum damage.
- `burnTime(ticks)` - Sets the burn time in ticks.
- `fireResistant(true/false)` - Makes the item fire resistant.
- `rarity(rarity)` - Sets the rarity.
- `glow(true/false)` - Enables or disables the glowing effect.
- `tooltip(text...)` - Adds tooltip lines.
- `color(index, colorHex)` - Sets the color for a tint index.
- `color((itemstack, tintIndex) => ...)` - Sets color via a function.
- `displayName(name)` - Sets the display name.
- `name(itemstack => ...)` - Sets the name via a function.
- `translationKey(key)` - Sets the translation key.
- `textureJson(json)` - Sets the texture JSON.
- `modelJson(json)` - Sets the model JSON.
- `parentModel(customParentModelLocation)` - Sets the parent model.
- `texture(customTextureLocation)` - Sets the texture location.
- `texture(key, customTextureLocation)` - Sets a texture for a specific key.
- `barColor(itemstack => ...)` - Sets the durability bar color.
- `barWidth(itemstack => ...)` - Sets the durability bar width.
- `useAnimation(animation)` - Sets the use animation.
- `useDuration(itemstack => ...)` - Sets the use duration.
- `use((level, player, hand) => ...)` - Defines behavior when used.
- `finishUsing((itemstack, level, entity) => ...)` - Defines behavior when finished using.
- `releaseUsing((itemstack, level, entity, tick) => ...)` - Defines behavior when releasing use.
- `tag(resourceLocation)` - Adds a tag.
- `modifyAttribute(attribute, identifier, d, operation)` - Modifies an attribute.
- `group(groupId)` - Sets the creative tab.
- `containerItem(itemId)` - Sets the container item.
- `subtypes(itemstack => ...)` - Defines subtypes.
- `food(foodBuilder => ...)` - Sets food properties.

#### Tool Type Methods (for `sword`, `pickaxe`, `axe`, `shovel`, `hoe`)
- `tier(toolTier)` - Sets the tool tier.
- `modifyTier(tier => ...)` - Modifies the tier.
- `attackDamageBaseline(damage)` - Sets the base attack damage.
- `attackDamageBonus(damage)` - Sets the attack damage bonus.
- `speedBaseline(speed)` - Sets the base speed.
- `speed(speed)` - Sets the speed.

#### Armor Type Methods (for `helmet`, `chestplate`, `leggings`, `boots`)
- `tier(armorTier)` - Sets the armor tier.
- `modifyTier(tier => ...)` - Modifies the tier.

### Example
```js
StartupEvents.registry('item', event => {
  event.create('test_item')
  event.create('test_item_1').texture('mobbo:item/lava')
  event.create('test_item_2').maxStackSize(16).glow(true)
  event.create('custom_sword', 'sword').tier('diamond').attackDamageBaseline(10)
})
```

### Notes
- Textures must be placed in `kubejs/assets/kubejs/textures/item/` by default.
- Custom models can be placed in `kubejs/assets/kubejs/models/item/`.
- Valid tool tiers: `wood`, `stone`, `iron`, `gold`, `diamond`, `netherite`.
- Valid armor tiers: `leather`, `chainmail`, `iron`, `gold`, `diamond`, `turtle`, `netherite`.
- Valid creative tab IDs: `search`, `buildingBlocks`, `decorations`, `redstone`, `transportation`, `misc`, `food`, `tools`, `combat`, `brewing`.
```

--------------------------------

### Cancel chat event when message starts with '!some_command' (1.19.2+)

Source: https://kubejs.com/wiki/tutorials/chat

Cancels the chat event when the message starts with '!some_command'. Replies to the player with 'Hi!' before cancelling.

```javascript
PlayerEvents.chat(event => {
  // Check if message starts with "!some_command"
  if (event.message.startsWith('!some_command')) {
    // Reply to the player and cancel the event
    event.player.tell('Hi!')
    event.cancel()
  }
})
```

--------------------------------

### Vibrating Recipe Example

Source: https://kubejs.com/wiki/addons/vintage-kubejs

Shows how to register a vibrating recipe using the Vintage Improvements KubeJS addon. Supports multiple chance-based outputs and .processingTime().

```javascript
ServerEvents.recipes(event => {
  event.recipes.vintageimprovements.vibrating('minecraft:flint', 'minecraft:gravel')
  event.recipes.vintageimprovements.vibrating(['minecraft:flint', Item.of('minecraft:gravel').withChance(0.1)], 'minecraft:gravel')
})
```

--------------------------------

### Filling recipe using Spout

Source: https://kubejs.com/wiki/addons/create

Example for Create mod filling recipe. Requires two inputs (item and fluid) and one output. Uses Fluid.of for the fluid input.

```javascript
ServerEvents.recipes(event => {
  event.recipes.create.filling('minecraft:water_bucket', [Fluid.of('minecraft:water'), 'minecraft:bucket'])
})
```

--------------------------------

### @returns comment example

Source: https://kubejs.com/wiki/addons/probejs/document-specification

Attach @returns with a string or full class name to change the return type of a method. This example changes the return type of getRecipes() to Document.RecipeHolder.

```typescript
/**
* @target dev.latvian.mods.kubejs.recipe.RecipeEventJS
*/
class RecipeEventJS {
    /**
     * Holds all the recipes collected from documents.
     * @returns Document.RecipeHolder
     */
    getRecipes(): java.util.Map<java.lang.String, java.lang.Object>;
}
```

--------------------------------

### Register custom items with StartupEvents.registry('item', ...)

Source: https://kubejs.com/wiki/tutorials/item-registry

Creates custom items in a startup script. The event cannot be reloaded without restarting the game and is not cancellable. The texture for 'test_item' must be placed at kubejs/assets/kubejs/textures/item/test_item.png; custom models can be placed at kubejs/assets/kubejs/models/item/test_item.json. The example shows chaining builder methods and using the 'sword' item type with a diamond tier and attack damage baseline of 10.

```javascript
// Listen to item registry event
StartupEvents.registry('item', event => {
  // The texture for this item has to be placed in kubejs/assets/kubejs/textures/item/test_item.png
  // If you want a custom item model, you can create one in Blockbench and put it in kubejs/assets/kubejs/models/item/test_item.json
  event.create('test_item')

  // If you want to specify a different texture location you can do that too, like this:
  event.create('test_item_1').texture('mobbo:item/lava') // This texture would be located at kubejs/assets/mobbo/textures/item/lava.png

  // You can chain builder methods as much as you like
  event.create('test_item_2').maxStackSize(16).glow(true)

  // You can specify item type as 2nd argument in create(), some types have different available methods
  event.create('custom_sword', 'sword').tier('diamond').attackDamageBaseline(10)
})
```

--------------------------------

### @mod comment example

Source: https://kubejs.com/wiki/addons/probejs/document-specification

Attach @mod with a mod id to a class document to load it only when that mod is present. In this example, the RecipeHolder class is loaded only when the mod 'cucumber' is present.

```typescript
/**
 * @mod cucumber
 */
class RecipeHolder {
    cucumber: Document.CucumberRecipes;
}
```

--------------------------------

### Compacting recipes for 1.21.1/1.19.2 - 1.20.1

Source: https://kubejs.com/wiki/addons/create

Example of compacting recipes using KubeJS for Create mod. Supports multiple inputs/outputs, heated/superheated variants, fluid output with item output, and chance-based output using CreateItem.

```javascript
ServerEvents.recipes(event => {
  event.recipes.create.compacting('minecraft:diamond', 'minecraft:coal_block')
  event.recipes.create.compacting('minecraft:diamond', 'minecraft:coal_block').heated()
  event.recipes.create.compacting('minecraft:diamond', 'minecraft:coal_block').superheated()
  event.recipes.create.compacting([Fluid.of('minecraft:water', 10), 'minecraft:dead_bush'], [Ingredient.of('#minecraft:saplings'), Ingredient.of('#minecraft:saplings')])
  event.recipes.create.compacting(['minecraft:diamond', CreateItem.of('minecraft:diamond', 0.3)], 'minecraft:coal_block')
})
```

--------------------------------

### Hide Items and Fluids (1.18.2 and below)

Source: https://kubejs.com/wiki/addons/jei

Uses onEvent('jei.hide.items') and onEvent('jei.hide.fluids') to hide items and fluids from JEI. Replace 'example:ingredient' and 'example:fluid' with your targets.

```javascript
onEvent('jei.hide.items', event => {
  event.hide('example:ingredient')
})

onEvent('jei.hide.fluids', event => {
  event.hide('example:fluid')
})
```

--------------------------------

### Cutting recipe examples (1.19.2 - 1.20.1)

Source: https://kubejs.com/wiki/addons/create

Shows how to add Cutting recipes using the Create mod in KubeJS for Minecraft 1.19.2 to 1.20.1. Includes basic output, processing time, and chance-based output using Item.of with withChance.

```javascript
ServerEvents.recipes(event => {
  event.recipes.create.cutting('minecraft:diamond', 'minecraft:coal_block')
  event.recipes.create.cutting('minecraft:diamond', 'minecraft:coal_block').processingTime(500)
  event.recipes.create.cutting(['minecraft:diamond', Item.of('minecraft:diamond').withChance(0.5)], 'minecraft:coal_block')
})
```

--------------------------------

### worldgen.add event example script

Source: https://kubejs.com/wiki/tutorials/worldgen/1605

Example script for the worldgen.add event, demonstrating how to add lakes, ores, and entity spawns. All values are optional and all feature types have a biomes field.

```javascript
onEvent("worldgen.add", event => {
  event.addLake(lake => { // Create new lake feature
    lake.block = "minecraft:diamond_block" // Block ID (Use [] syntax for properties)
    lake.chance = 3 // Spawns every ~3 chunks
  })

  event.addOre(ore => {
    ore.block = "minecraft:glowstone" // Block ID (Use [] syntax for properties)
    ore.spawnsIn.blacklist = false // Inverts spawn whitelist
    ore.spawnsIn.values = [ // List of valid block IDs or tags that the ore can spawn in
      "#minecraft:base_stone_overworld" // Default behavior - ores spawn in all stone types
    ]
    
    ore.biomes.blacklist = true // Inverts biome whitelist
    ore.biomes.values = [ // Biomes this ore can spawn in
      "minecraft:plains", // Biome ID
      "#nether" // OR #category, see list of categories below
    ]
    
    ore.clusterMinSize = 5 // Min blocks per cluster (currently ignored, will be implemented later, it's always 1)
    ore.clusterMaxSize = 9 // Max blocks per cluster
    ore.clusterCount = 30 // Clusters per chunk
    ore.minHeight = 0 // Min Y ore spawns in
    ore.maxHeight = 64 // Max Y ore spawns in
    ore.squared = true // Adds random value to X and Z between 0 and 16. Recommended to be true
    // ore.chance = 4 // Spawns the ore every ~4 chunks. You usually combine this with clusterCount = 1 for rare ores
  })
  
  event.addSpawn(spawn => { // Create new entity spawn
    spawn.category = "creature" // Category, can be one of "creature", "monster", "ambient", "water_creature" or "water_ambient"
    spawn.entity = "minecraft:pig" // Entity ID
    spawn.weight = 10 // Weight
    spawn.minCount = 4 // Min entities per group
    spawn.maxCount = 4 // Max entities per group
  })
})
```

--------------------------------

### Create a custom element with the Element Builder

Source: https://kubejs.com/wiki/addons/alchemistry-chemlib/custom-items

Place this script in the startup_scripts folder. It registers a custom element with the required properties and optional settings. The element becomes available for recipes and JEI/REI/EMI after the next game startup.

```javascript
StartupEvents.registry("item", event => {
  event.create("chemlib:deuterium", "chemlib:element")
    .elementColor("1e90ff")
    .groupName("Isotopes")
    .abbreviation("²H")
    .atomicNumber(1)
    .chemicalGroup(1)
    .period(1)
    .matterState(MatterType.GAS)
    .metalType(Metal.NONMETAL)
    .hasItems(false)
    .artificial(false)
    .withEffect("minecraft:levitation", 5, 2)
})
```

--------------------------------

### FTBQuestsEvents.started - Quest Start Handler

Source: https://kubejs.com/wiki/addons/ftb-xmod-compat

Executes code when a player starts a quest. Replace 'quest_id' with the quest's ID, obtainable by right-clicking a quest and selecting 'Copy ID'.

```javascript
FTBQuestsEvents.started('quest_id', event => {
    event.server.tell('A player started a quest!')
})
```
Tokens:
Raw