跳到主要内容

视觉效果 (effects)

effects 是 Baikiruto 的兼容层效果映射。它本身不会先解析成 components，而是在物品 RELEASE 阶段交给版本适配器处理，用来覆盖或补充最终的 ItemMeta / NBT 效果。

对日常配置可以这样理解：

  • effects 适合写兼容层常用项，例如 glow、item-flags、unbreakable、damage。
  • components 适合写现代原版 Data Components，尤其是复杂或 1.20.5+ 专属的配置。
  • item 级合并顺序里，components 会先进入运行时数据，随后 effects 和 meta 还能继续覆盖同名键。

基础配置​

effects:
  glow: true
  item-flags:
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES
  unbreakable: true
  damage: 3

如果你已经在用 components，推荐把现代原版组件继续写在 components: 下，把 effects: 留给兼容层常用字段。

稳定的兼容层效果​

glow - 发光效果​

为物品添加附魔光效。

effects:
  glow: true

源码里的真实行为是：

  • 给物品添加一个隐藏附魔来制造光效
  • 自动补上 HIDE_ENCHANTS

因此通常不需要再手写一次 HIDE_ENCHANTS。

item-flags - 隐藏信息​

隐藏物品的原版提示信息。

effects:
  item-flags:
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES
    - HIDE_UNBREAKABLE

兼容写法：

  • item-flags
  • itemflag

注意：

  • flag 名称大小写不敏感
  • - 和 _ 的差异会被宽松处理
  • 某些新版本 flag 在低版本不存在时会被静默忽略

unbreakable - 无法破坏​

effects:
  unbreakable: true

这是一条简单布尔开关。若你需要 show_in_tooltip 这类原版组件级细节，请改用 components.unbreakable。

damage - 当前损伤值​

effects:
  damage: 3

这会设置当前损伤值，用于控制原版耐久条显示。

注意：

  • effects.damage 是当前损伤值，不是自定义耐久系统的最大耐久
  • 自定义耐久系统主要看 data.durability 和 meta.durability

现代效果键​

item-model - 物品模型​

effects:
  item-model: "baikiruto:items/legendary_sword"

用于现代版本的物品模型键。格式应为 namespace:path。

custom-model-data - 自定义模型数据​

effects:
  custom-model-data: 1211101

这是兼容层里最常见的资源包模型字段之一。

建议：

  • 传统兼容写法可继续使用 effects.custom-model-data
  • 如果你的站点和服务器配置已经全面转向 1.20.5+ / 1.21+ 的原版组件方案，优先考虑 components.custom_model_data

tooltip-style - 工具提示样式​

effects:
  tooltip-style: "baikiruto:tooltip/default"

rarity - 稀有度​

effects:
  rarity: "epic"

常见值：

  • common
  • uncommon
  • rare
  • epic

glider - 滑翔效果​

effects:
  glider: true

这类现代效果键依赖服务器当前暴露的 API 能力。若你已经使用 components，也可以直接写对应的原版组件。

完整示例​

兼容层常用写法​

effects:
  glow: true
  item-flags:
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES
  unbreakable: true
  damage: 3

模型与资源包写法​

effects:
  item-model: "baikiruto:items/all_features_12111"
  custom-model-data: 1211101
  tooltip-style: "baikiruto:tooltip/default"

默认示例中的基础效果​

effects:
  glow: true
  item-flags:
    - HIDE_ENCHANTS
    - HIDE_ATTRIBUTES

与 components 的关系​

effects 和 components 是并行输入，不是简单的“前者会转换成后者”。

更接近源码真实情况的是：

  • components 会先被解析成两份数据：一份保留原始组件映射，一份投影成兼容层效果键
  • effects 再把自己的键直接写进运行时数据
  • meta 最后还能继续补充或覆盖兼容层键

因此在 item 级配置里，可以把顺序理解成：

components -> effects -> meta

几个容易混淆的点：

  • effects.glow 不等于 components.enchantment_glint_override
  • effects.unbreakable 只是布尔开关；components.unbreakable 才支持组件对象结构
  • effects.custom-model-data 与 components.custom_model_data 都可能生效，但适用场景不同

最佳实践​

1. 用 effects 处理兼容层常用项​

effects:
  glow: true
  item-flags:
    - HIDE_ENCHANTS
  unbreakable: true

适合：

  • 发光
  • 隐藏原版信息
  • 简单损伤值
  • 旧版本友好的基础视觉配置

2. 用 components 处理现代原版组件​

components:
  custom_name: "&6Example Item"
  enchantments:
    levels:
      sharpness: 5
  attribute_modifiers:
    modifiers:
      - type: "attack_damage"
        amount: 6.0
        operation: "add_value"
        slot: "mainhand"

适合：

  • 复杂原版组件
  • 1.20.5+ 组件透传
  • 需要对象结构的现代配置

3. 不要把 effects 当成 components 的别名层​

下面这种“等价”理解是不准确的：

# 不要把这两组写法当成完全等价

effects:
  glow: true

components:
  enchantment_glint_override: true

它们在源码里的实现路径和语义并不相同。

版本兼容性​

键建议理解
glow兼容层稳定字段，适合大多数版本
item-flags兼容层稳定字段，但具体 flag 受服务端枚举影响
unbreakable兼容层稳定字段
damage兼容层稳定字段
item-model现代版本字段，建议配合现代资源包使用
custom-model-data兼容层常用字段；现代组件场景可改用 components.custom_model_data
tooltip-style / rarity / glider现代 API / 现代组件语义更明显，建议谨慎跨版本使用

下一步​