Custom Blocks

原文：Custom Blocks

提示 这是一个启动脚本，意味着每次想要更改它时，你都需要重启游戏。

你可以在 KubeJS 中注册多种类型的自定义方块。下面是最简单的方式：

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

就这样！启动游戏，假设你没有动过 KubeJS 自动生成的资源，那么在创造模式物品栏的 KubeJS（紫色染料）标签下就会出现一个带完整贴图的方块。KubeJS 还会为你生成「Example Block」这个名称。

要对这个方块进行修改，我们使用 event.create() 调用返回的方块构建器。方块构建器允许我们把多个修改串联在一起。让我们尝试一些更常见的修改：

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
})

备用方块构建器（方块类型）

除了最基础的普通方块，KubeJS 还提供了多种备用方块构建器，它们都继承了基础构建器的全部方法（displayName、textureAll、hardness、tagBlock 等都可以继续链式调用）。使用 event.create(name, key) 的第二个参数来指定类型：

Key	说明	原版参考
basic	普通方块（默认，不传即为此类型）	任意完整方块
slab	台阶	橡木台阶
stairs	楼梯	橡木楼梯
fence	栅栏（含碰撞箱/连接判定）	橡木栅栏
fence_gate	栅栏门	橡木栅栏门
pressure_plate	压力板	橡木压力板
wall	墙（含连接判定）	圆石墙
button	按钮	橡木按钮
falling	受重力下落的方块	沙子/砂砾
crop	作物（可生长）	小麦
cardinal	带水平朝向的方块	-
detector	侦测器方块（白天/夜晚切换）	-
carpet	地毯（可放在地面，无碰撞箱）	白色地毯

普通方块 basic

默认类型，即文档开头示例中的写法：

StartupEvents.registry('block', event => {
  event.create('example_block')
})

台阶 slab

自动生成上下半台阶两种状态，可堆叠：

StartupEvents.registry('block', event => {
  event.create('example_slab', 'slab')
    .displayName('示例台阶')
    .textureAll('minecraft:block/stone') // 直接复用原版石头贴图
})

楼梯 stairs

自动生成朝向/半格/形状（直梯、内角、外角）等状态：

StartupEvents.registry('block', event => {
  event.create('example_stairs', 'stairs')
    .displayName('示例楼梯')
    .textureAll('minecraft:block/stone_bricks')
    .tagBlock('minecraft:mineable/pickaxe')
})

栅栏 fence 与栅栏门 fence_gate

StartupEvents.registry('block', event => {
  event.create('example_fence', 'fence')
    .displayName('示例栅栏')
    .textureAll('minecraft:block/oak_planks')

  event.create('example_fence_gate', 'fence_gate')
    .displayName('示例栅栏门')
    .textureAll('minecraft:block/oak_planks')
})

压力板 pressure_plate

StartupEvents.registry('block', event => {
  event.create('example_pressure_plate', 'pressure_plate')
    .displayName('示例压力板')
    .textureAll('minecraft:block/stone')
})

墙 wall

自动生成与相邻方块连接的状态（低矮/高墙/连接方向）：

StartupEvents.registry('block', event => {
  event.create('example_wall', 'wall')
    .displayName('示例墙')
    .textureAll('minecraft:block/cobblestone')
})

按钮 button

StartupEvents.registry('block', event => {
  event.create('example_button', 'button')
    .displayName('示例按钮')
    .textureAll('minecraft:block/stone')
})

重力方块 falling

像沙子/砂砾一样会下落，落到实体上会生成掉落物：

StartupEvents.registry('block', event => {
  event.create('example_falling', 'falling')
    .displayName('示例重力方块')
    .textureAll('minecraft:block/sand')
})

作物 crop

可生长的作物，额外提供几个方法：

• survive(blockstate) — 设置作物能存活的方块状态（例如需要下方是耕地）
• crop(blockstate) — 设置成熟后产出的方块状态
• growTick(tick) — 设置生长所需的随机刻次数

item() 在这里指的是作物的种子物品：

StartupEvents.registry('block', event => {
  event.create('example_crop', 'crop')
    .displayName('示例作物')
    .textureAll('minecraft:block/wheat_stage7')
})

方向性方块 cardinal

可以水平朝向的方块（类似原版原木的放置朝向）：

StartupEvents.registry('block', event => {
  event.create('example_cardinal', 'cardinal')
    .displayName('示例方向方块')
    .textureAll('minecraft:block/oak_log')
})

侦测器方块 detector

类似阳光传感器，可以响应白天/夜晚：

StartupEvents.registry('block', event => {
  event.create('example_detector', 'detector')
    .displayName('示例侦测器')
    .textureAll('minecraft:block/daylight_detector_top')
})

导入其它方块模型 / 贴图

不需要自己画贴图、建模型时，可以直接复用原版或其它模组现成的模型和贴图，非常省事。

1. 直接引用其它模组的模型

.model('namespace:path') 中的命名空间可以是任意已加载的模组：

StartupEvents.registry('block', event => {
  // 使用原版「柱状」模型（原木/竖纹石英那种）
  event.create('custom_log', 'cardinal')
    .model('minecraft:block/cube_column')
    .texture('end', 'minecraft:block/oak_log_top')   // 顶/底面
    .texture('side', 'minecraft:block/oak_log')      // 侧面

  // 直接引用其它模组的方块模型（这里是 Create 的黄铜块）
  event.create('brass_like', 'basic')
    .model('create:block/brass_block')
})

提示：.model() 的路径对应 assets/<命名空间>/models/block/<路径>.json。引用原版模型时命名空间是 minecraft，例如 minecraft:block/cube_all、minecraft:block/cube_column、minecraft:block/cube_bottom_top。

2. 复用其它模组的贴图

.textureAll() / .texture() 同样支持任意命名空间：

StartupEvents.registry('block', event => {
  // 贴图全部复用原版下界合金块
  event.create('netherite_like', 'basic')
    .textureAll('minecraft:block/netherite_block')

  // 六面分别指定（上下/东西南北），素材来自其它模组
  event.create('mixed_texture', 'basic')
    .texture('up', 'minecraft:block/smithing_table_top')
    .texture('down', 'minecraft:block/smithing_table_bottom')
    .texture('north', 'minecraft:block/smithing_table_side')
    .texture('south', 'minecraft:block/smithing_table_side')
    .texture('east', 'minecraft:block/smithing_table_front')
    .texture('west', 'minecraft:block/smithing_table_front')
})

3. 直接传入模型 / 方块状态 JSON

高级用法：用 setModelJson()、setBlockstateJson() 直接写完整 JSON，甚至可以用 parent 继承任意模组的模型：

StartupEvents.registry('block', event => {
  event.create('json_block', 'basic')
    .setModelJson({
      parent: 'minecraft:block/cube_all',          // 继承原版 cube_all 模型
      textures: { all: 'minecraft:block/obsidian' }
    })
    .setBlockstateJson({
      variants: {
        '': { model: 'kubejs:block/json_block' }   // 指向生成的模型
      }
    })
})

提示：.setModelJson() 写的模型路径需与生成方块 ID 对应（kubejs:block/<方块id>），或与 setBlockstateJson 里 variants 引用的模型路径一致。

功能方块实例（按钮 / 箱子 / 床 / 门）

按钮进阶（红石行为）

button 类型除了基础方法，还有几个专属方法控制红石行为：

StartupEvents.registry('block', event => {
  event.create('example_button', 'button')
    .displayName('示例按钮')
    .textureAll('minecraft:block/stone')
    .behaviour('stone')            // 按钮材质行为：stone / wood（影响声音和箭射判定）
    .ticksToStayPressed(30)        // 按下后保持的红石刻数（默认 20）
    .arrowsCanPress(true)          // 允许被箭射中时按下（像木质按钮那样）
})

箱子（带存储的方块）

KubeJS 没有 chest 类型，但可以用 blockEntity + inventory 附件做出带物品栏的存储方块：

StartupEvents.registry('block', event => {
  event.create('example_crate', 'basic')
    .displayName('示例储物箱')
    .hardness(2.0)
    .blockEntity(entity => {
      entity.inventory(9, 3)       // 9×3 = 27 格物品栏（类似原版箱子）
    })
})

⚠️ 说明：inventory(width, height) 附件给方块提供真实的物品存储能力（NBT 持久化）。但打开容器界面的 GUI 需要额外插件（如 BEJS）或自定义 Screen，KubeJS 原生 blockEntity 主要做数据与逻辑。

床（原生不支持）

KubeJS 1.20.1 没有 bed 类型——床是双格特殊方块（可睡觉），原生脚本无法直接注册。替代方案：

• 装饰性床：用 cardinal 方向方块 + Blockbench 床模型，右键时弹提示（不能真正睡觉）：

StartupEvents.registry('block', event => {
  event.create('example_bed', 'cardinal')
    .displayName('装饰床')
    .model('kubejs:block/example_bed')      // Blockbench 建模的床
    .box(0, 0, 0, 16, 8, 16, true)
    .fullBlock(false)
})

BlockEvents.rightClicked('kubejs:example_bed', event => {
  event.player.tell('这是一张装饰床，去别处睡吧~')
  event.cancel()
})

• 真能睡的床：需要 Java.extend 自定义 BedBlock（Java 知识），或用 BEJS 插件扩展。

门（原生不支持）

KubeJS 同样没有 door 类型。需要门的话：

• 简单方案：用 blockEntity + 右键事件手动切换方块状态（模拟开关），模型用 Blockbench 做。
• 完整方案：Java.extend 继承原版 DoorBlock，或用 BEJS。

Blockbench 建模指南（自定义方块模型）

想让方块有任意形状（床、机器、雕塑……），用 Blockbench（免费开源的 3D 建模软件）做模型，KubeJS 直接加载。

1. 新建模型

1. 下载安装 Blockbench。
2. File → New → 选择 Block（Minecraft Java Edition），版本选 1.20.1。
3. 界面里有一个 16×16×16 的网格立方体，这就是一格方块的空间。

2. 建模步骤

1. 添加元素：点 Add Box（添加盒子），拖拽或用右侧面板调 Position（位置）/ Size（尺寸），做出方块的各个部件。
2. 多个元素：一个方块可以由多个盒子组成（比如床 = 床架 + 床垫 + 枕头），每个元素单独调。
3. UV 贴图：选中元素，在 UV 面板调整展开方向；点击 Create UV（创建 UV）自动展开六面。
4. 画贴图：在 Textures 面板新建纹理（默认 16×16），用内置画笔直接画，或 Import 导入现成 PNG。
5. 预览：右侧 Preview 可以旋转看效果。

3. 导出文件

1. 模型：File → Export → Export Block Model，保存为 example_block.json。
2. 贴图：在 Textures 面板右键纹理 → Export，保存为 example_block.png。

4. 放进 KubeJS 资源目录

把两个文件放到 KubeJS 的资源目录（kubejs/assets/kubejs/ 下）：

kubejs/
└── assets/kubejs/
    ├── models/block/example_block.json   ← Blockbench 导出的模型
    └── textures/block/example_block.png  ← 导出的贴图

5. 脚本里引用模型

StartupEvents.registry('block', event => {
  event.create('example_block', 'basic')
    .displayName('自定义形状方块')
    .model('kubejs:block/example_block')   // 引用 Blockbench 模型
    .box(2, 0, 2, 14, 12, 14, true)        // 碰撞箱匹配模型形状（0-16 坐标）
    .fullBlock(false)                      // 非完整方块，关闭背面剔除优化
    .notSolid()                            // 告诉渲染器不是实心方块
})

6. 注意事项

• Blockbench 的坐标是 0-16 网格，和 .box() 默认的 scale16=true 一致，照着填即可。
• 贴图带透明像素时，记得加 .renderType('cutout')（玻璃/镂空）或 .renderType('translucent')（半透明）。
• 复杂形状务必加 .fullBlock(false) + .notSolid()，否则相邻方块会渲染异常。
• 需要朝向的模型（床、机器正面），用 cardinal 类型注册（模型朝北为默认方向）。
• 物品栏图标默认自动使用方块模型，无需额外做 item 模型；想要专属物品图标可在 models/item/ 放同名 JSON。

所有方块构建器方法

如果上面没有提到，这里是构建方块时可以使用的每个方法的列表。

• displayName('name')

  • 设置物品的显示名称。

• material('material') （1.20+ 不再支持，请参阅下面的 mapColor 和 soundType！）

  • 将物品的材质设置为材质列表（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

• mapColor(MapColor) （仅 1.20.1+）
  • 设置方块的地图颜色，你可以在这里找到完整列表，使用小写的 ID，例如 'color_light_green'。
• soundType(SoundType) （仅 1.20.1+）
  • 设置方块的声音类型：

声音类型列表

除了使用 soundType(SoundType)，你也可以使用以下快捷方法之一：

• noSoundType()
• woodSoundType()
• stoneSoundType()
• gravelSoundType()
• grassSoundType()
• sandSoundType()
• cropSoundType()
• glassSoundType()

wood
gravel
grass
lily_pad
stone
metal
glass
wool
sand
snow
powder_snow
ladder
anvil
slime_block
honey_block
wet_grass
coral_block
bamboo
bamboo_sapling
scaffolding
sweet_berry_bush
crop
hard_crop
vine
nether_wart
lantern
stem
nylium
fungus
roots
shroomlight
weeping_vines
twisting_vines
soul_sand
soul_soil
basalt
wart_block
netherrack
nether_bricks
nether_sprouts
nether_ore
bone_block
netherite_block
ancient_debris
lodestone
chain
nether_gold_ore
gilded_blackstone
candle
amethyst
amethyst_cluster
small_amethyst_bud
medium_amethyst_bud
large_amethyst_bud
tuff
calcite
dripstone_block
pointed_dripstone
copper
cave_vines
spore_blossom
azalea
flowering_azalea
moss_carpet
pink_petals
moss
big_dripleaf
small_dripleaf
rooted_dirt
hanging_roots
azalea_leaves
sculk_sensor
sculk_catalyst
sculk
sculk_vein
sculk_shrieker
glow_lichen
deepslate
deepslate_bricks
deepslate_tiles
polished_deepslate
froglight
frogspawn
mangrove_roots
muddy_mangrove_roots
mud
mud_bricks
packed_mud
hanging_sign
nether_wood_hanging_sign
bamboo_wood_hanging_sign
bamboo_wood
nether_wood
cherry_wood
cherry_sapling
cherry_leaves
cherry_wood_hanging_sign
chiseled_bookshelf
suspicious_sand
suspicious_gravel
decorated_pot
decorated_pot_cracked

你可以使用 new SoundType(volume, pitch, breakSound, stepSound, placeSound, hitSound, fallSound) 构造自己的声音类型，其中 volume 和 pitch 是 0.0 - 1.0 的浮点数（通常保持为 1.0），所有声音都是 SoundEvents。

• property(BlockProperty)
  • • 为方块添加更多方块状态，比如含水或朝向某个方向。属性的完整列表见属性列表（Properties List）：

属性列表

用法：.property(BlockProperties.PICKLES)

布尔属性（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

整数属性：

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

方向属性：

facing,
facing_hopper,
horizontal_facing,
vertical_direction

其他（enum）属性：

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')

  • 为方块添加标签

• tagItem('namespace:tag_name')

  • 为方块的物品添加标签（如果它有物品的话）

• tagBoth('namespace:tag_name')

  • 如果可能，同时添加方块标签和物品标签

• hardness(float)

  • 设置方块的硬度值。用于计算破坏方块所需的时间。

  • resistance(float)

  • 设置方块对爆炸等事物的抗性

  • unbreakable()
  • 将抗性设置为 MAX_VALUE、硬度设置为 -1 的快捷方式（像基岩一样）
  • lightLevel(number)
  • 设置方块的光照等级。

  • 传入整数（0-15）会将方块的光照等级设置为该值。

  • 传入浮点数（0.0-1.0）会将该数字乘以 15，然后将方块的光照等级设置为最接近的整数

  • opaque(boolean)
  • 设置方块是否不透明。完整的不透明方块不会让光线透过。
  • fullBlock(boolean)
  • 设置方块是否渲染为完整方块。完整方块会应用某些优化，例如不渲染其背后的地形。如果你使用 .box() 制作自定义碰撞箱，请将其设置为 false。
  • requiresTool(boolean)
  • 如果为 true，方块将使用某些方块标签来决定被挖掘时是否掉落物品。例如，一个带有 #minecraft:mineable/axe、#minecraft:mineable/pickaxe 和 #minecraft:needs_iron_tool 标签的方块，除非用至少铁级别的斧或镐挖掘，否则什么都不会掉落。
  • renderType('solid'|'cutout'|'translucent')

  • 设置渲染类型。

  • 对于像玻璃这样像素要么透明要么不透明的贴图方块，需要 cutout

  • 对于像染色玻璃这样像素可以半透明的方块，需要 translucent

  • 否则，如果方块中的所有像素都不透明，请使用 solid。

  • color(tintindex, color)
  • 将方块重新着色为某种颜色
  • textureAll('texturepath')
  • 将方块的所有 6 个面都贴上相同的贴图。
  • 路径可以是任意命名空间，形如 kubejs:block/texture_name（对应文件位于 kubejs/assets/kubejs/textures/block/texture_name.png），也可以直接复用原版/其它模组贴图，如 minecraft:block/stone、create:block/brass_block（详见上方「导入其它方块模型 / 贴图」）。
  • 默认为 kubejs:block/<block_name>

  • texture('side', 'texturepath')

  • 单独给一个面贴上贴图。有效的面为 up、down、north、south、east 和 west。同样支持任意命名空间。

  • model('modelpath')
  • 指定自定义模型。
  • 路径可以是任意命名空间，形如 kubejs:block/texture_name（对应文件位于 kubejs/assets/kubejs/models/block/texture_name.png），也可以引用原版/其它模组现成模型，如 minecraft:block/cube_all、minecraft:block/cube_column、create:block/brass_block（详见上方「导入其它方块模型 / 贴图」）。
  • 默认为 kubejs:block/<block_name>。
  • noItem()
  • 移除关联的物品。Minecraft 默认对少数方块这样做，比如下界传送门方块。如果玩家永远不应该能够持有或放置该方块，请使用此方法。
  • box(x0, y0, z0, x1, y1, z1, boolean)
  • box(x0, y0, z0, x1, y1, z1) // 默认为 true

  • 为方块设置自定义碰撞箱，影响碰撞。你可以多次使用此方法来定义由多个盒子组成的复杂形状。

  • 每个盒子都是一个矩形棱柱，角位于 (x0,y0,z0) 和 (x1,y1,z1)

  • 你可能需要设置一个与你在这里定义的形状匹配的自定义方块模型。
  • 最后一个布尔值决定盒子的坐标比例。传入 true 将使用 0-16 的数字，而传入 false 将使用 0.0 到 1.0 的坐标
  • noCollision()
  • 移除默认的完整方块碰撞箱，允许你从方块中掉下去。
  • notSolid()
  • 告诉渲染器该方块不是实心的。
  • waterlogged()
  • 允许方块被水淹没（可含水）。
  • noDrops()
  • 方块不会掉落自身，即使使用精准采集挖掘。
  • slipperiness(float)
  • 设置方块的滑动度。影响实体在其上移动时的滑动程度。原版中几乎所有方块的滑动度都是 0.6，除了黏液块（0.8）和冰（0.98）。
  • speedFactor(float)
  • 影响玩家在方块上行走速度的修正系数。
  • jumpFactor(float)
  • 影响玩家从方块上跳起高度的修正系数。
  • randomTick(consumer<randomTickEvent>)
  • 当方块接收到随机刻时运行的函数。

• item(consumer<itemBuilder>)

  • 修改方块物品的某些属性（见链接）
• setLootTableJson(json)
  • 直接传入自定义战利品表 JSON
• setBlockstateJson(json)
  • 直接传入自定义方块状态 JSON
• setModelJson(json)
  • 直接传入自定义模型 JSON
• noValidSpawns(boolean)
  • 如果为 true，该方块不会被计为实体的有效生成点
• suffocating(boolean)
  • 设置方块是否会使头部在其中的实体窒息
• viewBlocking(boolean)
  • 设置方块是否算作阻挡玩家的视线。
• redstoneConductor(boolean)
  • 设置方块是否传导红石。默认情况下为 true。
• transparent(boolean)
  • 设置方块是否透明
• defaultCutout()
  • 批量应用一系列方法以制作诸如玻璃之类的方块
• defaultTranslucent()
  • 与 defaultCutout() 类似，但使用半透明渲染层