Custom Blocks

This is a startup script, meaning that you will need to restart your game each time you want to make changes to it.

You can register many types of custom blocks in KubeJS. Here's the simplest way:

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

That's it! Launch the game, and assuming you've left KubeJS's auto-generated resources alone, there should be a fully-textured block in the Creative menu under KubeJS (purple dye). KubeJS will also generate the name "Example Block" for you. 

To make modifications to this block, we use the block builder returned by the event.create() call. The block builder allows us to chain together multiple modifications. Let's try making some of the more common modifications:

StartupEvents.registry("block", (event) => {
    event.create("example_block") // Create a new block
    .displayName("My Custom Block") // Set a custom name
    .material("wood") // Set a material (affects the sounds and some properties)
    .hardness(1.0) // Set hardness (affects mining time)
    .resistance(1.0) // Set resistance (to explosions, etc)
    .tagBlock("my_custom_tag") // Tag the block with `#minecraft:my_custom_tag` (can have multiple tags)
    .requiresTool(true) // Requires a tool or it won't drop (see tags below)
    .tagBlock("my_namespace:my_other_tag") // Tag the block with `#my_namespace:my_other_tag`
    .tagBlock("mineable/axe") //can be mined faster with an axe
    .tagBlock("mineable/pickaxe") // or a pickaxe
    .tagBlock('minecraft:needs_iron_tool') // the tool tier must be at least iron
})

All Block Builder Methods

In case it wasn't covered above, here's list of each method you can use when building a block.

• displayName('name')
  • Sets the item's display name.
    
• material('material') (No longer supported in 1.20+, see below!)
  • Set the item's material to an available material from the Materials List:
    

Materials List

air
amethyst
bamboo
bamboo_sapling
barrier
bubble_column
buildable_glass
cactus
cake
clay
cloth_decoration
decoration
dirt
egg
explosive
fire
froglight
frogspawn
glass
grass
heavy_metal
ice
ice_solid
lava
leaves
metal
moss
nether_wood
piston
plant
portal
powder_snow
replaceable_fireproof_plant
replaceable_plant
replaceable_water_plant
sand
sculk
shulker_shell
snow
sponge
stone
structural_air
top_snow
vegetable
water
water_plant
web
wood
wool

• property(BlockProperty)
  • • Adds more blockstates to the block, like being waterlogged or facing a certain direction. A full list of properties is available in the Properties List:

Properties List

Usage: .property(BlockProperties.PICKLES)

Boolean Properties (true/false):

attached,
berries,
bloom,
bottom,
can_summon,
conditional,
disarmed,
down,
drag,
east,
enabled,
extended,
eye,
falling,
hanging,
has_book,
has_bottle_0,
has_bottle_1,
has_bottle_2,
has_record,
inverted,
in_wall,
lit,
locked,
north,
occupied,
open,
persistent,
powered,
short,
shrieking,
signal_fire,
snowy,
south,
triggered,
unstable,
up,
vine_end,
waterlogged,
west

Integer properties:

age_1,
age_2,
age_3,
age_4,
age_5,
age_7,
age_15,
age_25,
bites,
candles,
delay,
distance,
eggs,
hatch,
layers,
level,
level_cauldron,
level_composter,
level_flowing,
level_honey,
moisture,
note,
pickles,
power,
respawn_anchor_charges,
rotation_16,
stability_distance,
stage

Directional Properties:

facing,
facing_hopper,
horizontal_facing,
vertical_direction

Other (enum) Properties:

attach_face,
axis,
bamboo_leaves,
bed_part,
bell_attachment,
chest_type,
door_hinge,
double_block_half,
dripstone_thickness,
east_redstone,
east_wall,
half,
horizontal_axis,
mode_comparator,
north_redstone,
north_wall,
noteblock_instrument,
orientation,
piston_type,
rail_shape,
rail_shape_straight,
sculk_sensor_phase,
slab_type,
south_redstone,
south_wall,
stairs_shape,
structureblock_mode,
tilt,
west_redstone,
west_wall

•  tagBlock('namespace:tag_name')
  • adds a tag to the block
    
• tagItem('namespace:tag_name')
  • adds a tag to the block's item, if it has one
    
• tagBoth('namespace:tag_name')
  • adds both block and item tag if possible
• hardness(float)
  
  • Sets the block's Hardness value. Used for calculating the time it takes for the block to be destroyed.
• resistance(float)
  
  • Set's the block's resistance to things like explosions
• unbreakable()
  • Shortcut to set the resistance to MAX_VALUE and hardness to -1 (like bedrock)
• lightLevel(number)
  • Sets the block's light level.
  • Passing an integer (0-15) will set the block's light level to that value.
    
  • Passing a float (0.0-1.0) will multiply that number by 15, then set the block's light level to the nearest integer
• opaque(boolean)
  • Sets whether the block is opaque. Full, opaque blocks will not let light through.
• fullBlock(boolean)
  • Sets whether the block renders as a full block. Full blocks have certain optimizations applied to them, such as not rendering terrain behind them. If you're using .box() to make a custom hitbox, please set this to false.
• requiresTool(boolean)
  • If true, the block will use certain block tags to determine whether it should drop an item when mined. For example, a block tagged with #minecraft:mineable/axe, #minecraft:mineable/pickaxe, and #minecraft:needs_iron_tool would drop nothing unless it was mined with an axe or pickaxe that was at least iron level.
• renderType('solid'|'cutout'|'translucent')
  • Sets the render type.
    
    • cutout is required for blocks with texture like glass, where pixels are either transparent or not
      
    • translucent is required for blocks like stained glass, where pixels can be semitransparent
      
    • otherwise, use solid if all pixels in your block are opaque.
• color(tintindex, color)
  • Recolors a block to a certain color
• textureAll('texturepath')
  • Textures all 6 sides of the block to the same texture.
  • The path must look like kubejs:block/texture_name (which would be included under kubejs/assets/kubejs/textures/block/texture_name.png).
  • Defaults to kubejs:block/<block_name>
• texture('side', 'texturepath')
  
  • Texture one side by itself. Valid sides are up, down, north, south, east, and west.
• model('modelpath')
  • Specify a custom model. 
  • The path must look like kubejs:block/texture_name (which would be included under kubejs/assets/kubejs/models/block/texture_name.png).
  •  Defaults to kubejs:block/<block_name>.
• noItem()
  • Removes the associated item. Minecraft does this by default for a few blocks, like nether portal blocks. Use this if the player should never be able to hold or place the block.
• box(x0, y0, z0, x1, y1, z1, boolean)
  • Sets a custom hitbox for the block, affecting collision. You can use this multiple times to define a complex shape composed of multiple boxes.
    
  • Each box is a rectangular prism with corners at (x0,y0,z0) and (x1,y1,z1)
  • You will probably want to set up a custom block model that matches the shape you define here.
  • The final boolean determines the coordinate scale of the box. Passing in true will use the numbers 0-15, while passing in false will use coordinates ranging from 0.0 to 1.0
• noCollision()
  • Removes the default full-block hitbox, allowing you to fall through the block.
• notSolid()
  • Tells the renderer that the block isn't solid. 
• waterlogged()
  • Allows the block to be waterloggable.
• noDrops()
  • The block will not drop itself, even if mined with silk touch.
• slipperiness(float)
  • Sets the slipperiness of the block. Affects how much entities slide while moving on it. Almost every block in Vanilla has a slipperiness value of 0.6, except slime (0.8) and ice (0.98).
• speedFactor(float)
  • A modifier affecting how quickly players walk on the block.
• jumpFactor(float)
  • A modifier affecting how high players can jump off the block.
• randomTick(consumer<randomTickEvent>)
  • A function to run when the block recieves a random tick.
    
• item(consumer<itemBuilder>)
  • Modify certain properties of the block's item (see link)
• setLootTableJson(json)
  • Pass in a custom loot table JSON directly
• setBlockstateJson(json)
  • Pass in a custom blockstate JSON directly
• setModelJson(json)
  • Pass in a custom model JSON directly
• noValidSpawns(boolean)
  • If true, the block is not counted as a valid spawnpoint for entities
• suffocating(boolean)
  • Whether the block will suffocate entities that have their head inside it
• viewBlocking(boolean)
  • Whether the block counts as blocking a player's view.
• redstoneConductor(boolean)
  • Sets whether the block will conduct redstone. True by default.
• transparent(boolean)
  • Sets whether the block is transparent or not
• defaultCutout()
  • batches a bunch of methods to make blocks such as glass
• defaultTranslucent()
  • similar to defaultCutout() but using translucent layer instead