原版组件 (components)

components 字段直接映射 Minecraft 1.20.5+ 的 Data Components 系统。Baikiruto 会先规范化组件 key（忽略大小写、支持 -/_ 混用、会去掉 minecraft: 前缀），再把已识别的组件同步到兼容层；未识别的组件则按原始值透传给原版组件系统。

这意味着：

已在源码中专门解析的组件，兼容层更完整，低版本也更容易得到一致结果。
未专门解析的组件，1.20.5+ 可以尝试直接透传，但不享受 Bukkit API 兜底，也不保证低版本行为一致。

基础组件

custom_name / name - 自定义名称

components:
  custom_name: "&6Example Item"

也可以使用别名 name。源码还支持对象写法，用于传入更细的文本样式字段。

lore - 描述文本

components:
  lore:
    - "&7Line 1"
    - "&7Line 2"
    - "&7Line 3"

源码同时支持对象写法，可使用 lines、values、item_description、lore、value 这些字段名传入文本列表。

item_model - 物品模型

components:
  item_model: "baikiruto:items/model"

custom_model_data - 自定义模型数据

components:
  custom_model_data: 1211101

常见写法是直接传整数。源码也支持对象写法，例如 value、int、custom-model-data、floats。

rarity - 稀有度

components:
  rarity: "epic"  # common / uncommon / rare / epic

components:
  tooltip_style: "baikiruto:tooltip/default"

耐久度组件

damage - 当前损伤

components:
  damage: 3

max_damage - 最大耐久

components:
  max_damage: 240

unbreakable - 无法破坏

components:
  unbreakable:
    show_in_tooltip: false

也可以直接写成布尔值：

components:
  unbreakable: true

附魔组件

enchantments / enchantment - 附魔

components:
  enchantments:
    levels:
      sharpness: 5
      unbreaking: 3
      fire_aspect: 2
      looting: 3
    show_in_tooltip: false

也可以使用别名 enchantment。

常用附魔 ID：

武器：sharpness, smite, bane_of_arthropods, knockback, fire_aspect, looting, sweeping_edge
工具：efficiency, silk_touch, fortune, unbreaking, mending
护甲：protection, fire_protection, blast_protection, projectile_protection, thorns
弓箭：power, punch, flame, infinity
三叉戟：loyalty, impaling, riptide, channeling

属性修饰符

attribute_modifiers - 属性修饰符

components:
  attribute_modifiers:
    modifiers:
      - type: "attack_damage"
        amount: 6.0
        operation: "add_value"      # add_value / add_multiplied_base / add_multiplied_total
        slot: "mainhand"            # mainhand / offhand / head / chest / legs / feet / any

      - type: "attack_speed"
        amount: 0.1
        operation: "add_multiplied_total"
        slot: "mainhand"

      - attribute: "armor"
        amount: 4.0
        operation: "add_value"
        slot: "chest"

源码实际识别的字段是：

type 或 attribute
amount
operation
slot

operation 支持这些别名：

add_number -> add_value
add_scalar / multiply_base -> add_multiplied_base
multiply_scalar_1 / multiply_total -> add_multiplied_total

slot 支持这些别名：

main_hand / hand -> mainhand
off_hand -> offhand
helmet -> head
chestplate / body -> chest
leggings -> legs
boots -> feet

常用属性类型：

attack_damage - 攻击伤害
attack_speed - 攻击速度
armor - 护甲值
armor_toughness - 护甲韧性
knockback_resistance - 击退抗性
movement_speed - 移动速度
max_health - 最大生命值
luck - 幸运值

方块交互

can_break - 可破坏方块

components:
  can_break:
    blocks:
      - STONE
      - DEEPSLATE
      - GRANITE
      - DIORITE
      - ANDESITE

源码支持两种常见写法：

直接传方块列表
对象写法里传 blocks

兼容原版复杂写法时，也可以透传 predicates 结构。

can_place_on - 可放置方块

components:
  can_place_on:
    blocks:
      - DIRT
      - GRASS_BLOCK
      - STONE

同样支持列表写法、blocks 对象写法，以及原版 predicates 结构。

使用相关

use_cooldown - 使用冷却

components:
  use_cooldown:
    seconds: 4.0
    cooldown_group: "baikiruto:example_weapon"

seconds 为秒数，源码会同时计算对应的 tick 冷却值。

use_remainder - 使用后剩余物

components:
  use_remainder:
    id: "example:remainder"
    amount: 1

也可以直接写成字符串：

components:
  use_remainder: "GLASS_BOTTLE"

对象写法支持这些字段名：

id / item / type
count / amount

未填写数量时默认 1。

装备相关

equippable - 可装备

components:
  equippable:
    slot: "head"  # mainhand / offhand / head / chest / legs / feet / any
    equip_sound: "entity.player.levelup"
    model: "baikiruto:items/equipped_model"

源码专门解析的字段只有：

slot
equip_sound
model

其余原版字段如果直接写入，属于透传组件行为，不享受兼容层兜底。

联动提醒：

如果这件物品同时开启了 meta.unique.bind-player，装备动作也会先经过绑定校验
其他玩家通过 Shift 点击、直接点击装备槽，或右键空气 / 方块自动穿戴时，都会被绑定系统拦截
这类“谁先穿上就绑定给谁”的装备，建议和 Meta 扩展一起看

伤害与保护

damage_resistant - 伤害抗性

components:
  damage_resistant:
    enabled: true
    types:
      - "projectile"
      - "fire"
      - "explosion"
      - "fall"
      - "magic"

也可以使用 damage_types 作为字段名。源码会自动把常见简写规范化为原版伤害标签，例如：

fire -> #minecraft:is_fire
explosion -> #minecraft:is_explosion
fall -> #minecraft:is_fall
void / out_of_world -> #minecraft:is_out_of_world
magic -> #minecraft:is_magic
lightning -> #minecraft:is_lightning
freeze / freezing -> #minecraft:is_freezing

death_protection - 死亡保护

components:
  death_protection:
    enabled: true
    health: 4.0
    consume: false
    types:
      - "void"

源码支持的主要字段：

enabled - 是否启用
health / amount - 触发后保留的生命值
consume - 是否消耗物品
types / damage_types - 生效的伤害类型

药水相关

potion_contents - 药水内容

components:
  potion_contents:
    potion: "strong_swiftness"
    custom_color: "55AAFF"
    custom_effects:
      - id: "speed"
        duration: 300
        amplifier: 1
        ambient: false
        show_particles: true
        show_icon: true

      - id: "jump_boost"
        duration: 300
        amplifier: 0

custom_effects 中常用字段：

id / type
duration，默认 200
amplifier，默认 0
ambient，默认 false
show_particles / particles，默认 true
show_icon / icon，默认 true

常用药水类型：

speed, slowness, haste, mining_fatigue
strength, instant_health, instant_damage, jump_boost
nausea, regeneration, resistance, fire_resistance
water_breathing, invisibility, blindness, night_vision
hunger, weakness, poison, wither

自定义数据

custom_data - 自定义数据

components:
  custom_data:
    baikiruto:
      item_id: "example:sword"
      server: "26.1.1"
      channel: "itemstream"
    custom_namespace:
      any_data: "value"
      nested:
        key: "value"

用途：

存储插件自定义数据
ItemStream 元数据存储
跨插件数据传递

其他组件

glider - 滑翔

components:
  glider: true

透传组件

未专门解析的原版组件

Baikiruto 会把未命中专门解析分支的组件保留在原始 components 映射中，并在 1.20.5+ 尝试直接写入原版组件系统。

这意味着像下面这些原版组件 key 可以尝试直接写入：

stored_enchantments
food
trim
container
bundle_contents
fire_resistant
enchantment_glint_override
max_stack_size
hide_tooltip

但要注意：

这些 key 没有 Baikiruto 的专门解析逻辑。
它们不会生成兼容层 effects 数据。
低版本不保证能自动转换出一致结果。
如果你需要跨版本稳定行为，优先使用本页前面列出的已专门解析组件。

完整示例

全特性示例

components:
  custom_name: "&6Example All Features"
  lore:
    - "&726.1.1 data component showcase"
    - "&8Includes script/meta/component pipeline"
  item_model: "baikiruto:items/all_features_12111"
  custom_model_data: 1211101
  enchantments:
    levels:
      sharpness: 5
      unbreaking: 3
    show_in_tooltip: false
  attribute_modifiers:
    modifiers:
      - type: "attack_damage"
        amount: 6.0
        operation: "add_value"
        slot: "mainhand"
      - type: "attack_speed"
        amount: 0.1
        operation: "add_multiplied_total"
        slot: "mainhand"
  unbreakable:
    show_in_tooltip: false
  damage: 3
  max_damage: 240
  can_break:
    blocks:
      - STONE
      - DEEPSLATE
  can_place_on:
    blocks:
      - DIRT
      - GRASS_BLOCK
  tooltip_style: "baikiruto:tooltip/default"
  rarity: "epic"
  glider: false
  use_cooldown:
    seconds: 4.0
    cooldown_group: "baikiruto:example_weapon"
  use_remainder:
    id: "example:remainder"
    amount: 1
  equippable:
    slot: "mainhand"
    equip_sound: "entity.player.levelup"
    model: "baikiruto:items/all_features_equipped"
  damage_resistant:
    enabled: true
    types:
      - "projectile"
  death_protection:
    enabled: true
    health: 4.0
    consume: false
    types:
      - "void"
  custom_data:
    baikiruto:
      item_id: "example:all_features"
      server: "26.1.1"
      channel: "itemstream"

守护图腾示例

components:
  equippable:
    slot: "offhand"
  damage_resistant:
    enabled: true
    types:
      - "fire"
      - "explosion"
  death_protection:
    enabled: true
    health: 10.0
    consume: true
    types:
      - "all"
  use_remainder:
    id: "example:remainder"
    amount: 1
  use_cooldown:
    seconds: 10.0
    cooldown_group: "baikiruto:guardian_totem"
  rarity: "rare"
  custom_data:
    baikiruto:
      item_id: "example:guardian_totem"

药水示例

components:
  potion_contents:
    potion: "strong_swiftness"
    custom_color: "55AAFF"
    custom_effects:
      - id: "speed"
        duration: 300
        amplifier: 1
        ambient: false
        show_particles: true
        show_icon: true
  use_remainder: "GLASS_BOTTLE"
  custom_data:
    baikiruto:
      item_id: "example:potion_suite"

与 effects 的关系

components 不是简单替代 effects，而是和兼容层并行工作：

已被源码专门解析的组件，会同时写入原始组件映射与兼容层 effects 数据。
兼容层负责把常用组件适配到 Bukkit API / 低版本行为。
原始组件映射则在 1.20.5+ 交给原版 Data Components 系统直接处理。

# 兼容层写法（适合常见场景）
effects:
  glow: true
  custom-model-data: 1001

# 原版组件写法（适合复杂场景）
components:
  enchantments:
    levels:
      sharpness: 5
  custom_model_data: 1001
  attribute_modifiers:
    modifiers:
      - type: "attack_damage"
        amount: 10.0
        operation: "add_value"
        slot: "mainhand"

版本兼容性

components 系统本身来自 Minecraft 1.20.5+。Baikiruto 对其中一部分常用组件做了专门解析，因此不同写法的兼容性并不完全相同。

版本	支持程度
1.12 - 1.20.4	已专门解析的组件会尽量回落到兼容层；透传组件不保证结果一致
1.20.5+	已专门解析组件 + 透传组件都可以使用

下一步

查看物品配置了解完整配置结构
查看视觉效果了解视觉效果配置

基础组件​

custom_name / name - 自定义名称​

lore - 描述文本​

item_model - 物品模型​

custom_model_data - 自定义模型数据​

rarity - 稀有度​

tooltip_style - 工具提示样式​

耐久度组件​

damage - 当前损伤​

max_damage - 最大耐久​

unbreakable - 无法破坏​

附魔组件​

enchantments / enchantment - 附魔​

属性修饰符​

attribute_modifiers - 属性修饰符​

方块交互​

can_break - 可破坏方块​

can_place_on - 可放置方块​

使用相关​

use_cooldown - 使用冷却​

use_remainder - 使用后剩余物​

装备相关​

equippable - 可装备​

伤害与保护​

damage_resistant - 伤害抗性​

death_protection - 死亡保护​

药水相关​

potion_contents - 药水内容​

自定义数据​

custom_data - 自定义数据​

其他组件​

glider - 滑翔​

透传组件​

未专门解析的原版组件​

完整示例​

全特性示例​

守护图腾示例​

药水示例​

与 effects 的关系​

版本兼容性​

下一步​