Skip to main content
Version: 1.21.4

内置附魔效果组件（Built-In Enchantment Effect Components）

原版 Minecraft 提供了多种不同类型的附魔效果组件（enchantment effect components），可用于 附魔 的定义。本文将逐一解释这些组件的用途及其在代码中的定义方式。

数值效果组件（Value Effect Components）​

另见 数值效果组件（Value Effect Components）在 Minecraft Wiki 上的相关内容

数值效果组件用于修改游戏中某处的数值型属性，这类效果由 EnchantmentValueEffect 类实现。如果某个数值被多个数值效果组件同时修改（例如，装备了多个附魔），它们的效果会叠加生效。

数值效果组件可以对指定数值应用以下任意操作：

  • minecraft:set：覆盖原有的基于等级的数值。
  • minecraft:add：将指定的基于等级的数值加到原有数值上。
  • minecraft:multiply：将原有数值与指定的基于等级的因子相乘。
  • minecraft:remove_binomial：使用二项分布对指定（基于等级的）概率进行抽样。如果抽样成功，则从数值中减去 1。注意，许多数值实际上是标志位，1 表示完全激活，0 表示完全关闭。
  • minecraft:all_of：接受一个其他数值效果的列表，并按顺序依次应用这些效果。

锋利（Sharpness）附魔通过如下方式使用了 minecraft:damage 这一数值效果组件，从而实现其效果：

"effects": {
    // 此效果组件的类型为 "minecraft:damage"。
    // 这意味着该效果会修改武器伤害值。
    // 更多效果组件类型见下文列表。
    "minecraft:damage": [
        {
            // 这是一个需要应用的数值效果。
            // 由于这里只有一个效果，这个数值效果就被命名为 "effect"。
            "effect": {
                // 指定要使用的数值效果类型。本例为 "minecraft:add"，表示下面的数值会被加到武器伤害上。
                "type": "minecraft:add",

                // 数值块。在这里，数值类型是 LevelBasedValue，基础值为 1，每提升一级附魔增加 0.5。
                "value": {
                    "type": "minecraft:linear",
                    "base": 1.0,
                    "per_level_above_first": 0.5
                }
            }
        }
    ]
}

value 块中的对象是一个 基于等级的数值，它可以用于让某个数值效果组件（effect component）根据附魔等级动态改变其效果强度。

你可以使用 EnchantmentValueEffect#process 方法，根据传入的数值操作来调整效果值，示例如下：

// `valueEffect` 是一个 EnchantmentValueEffect 实例。
// `enchantLevel` 是一个整数，表示附魔的等级
float baseValue = 1.0;
float modifiedValue = valueEffect.process(enchantLevel, server.random, baseValue);

原版附魔数值效果组件类型（Vanilla Enchantment Value Effect Component Types）​

定义为 DataComponentType<EnchantmentValueEffect>​

  • minecraft:crossbow_charge_time：修改该弩的蓄力时间（秒）。由快速装填（Quick Charge）使用。
  • minecraft:trident_spin_attack_strength：修改三叉戟旋转攻击的“强度”（参见 TridentItem#releaseUsing）。由激流（Riptide）使用。

定义为 DataComponentType<List<ConditionalEffect<EnchantmentValueEffect>>>​

与护甲相关：

  • minecraft:armor_effectiveness：决定该武器对护甲的效果，取值范围为 0（无保护）到 1（正常保护）。由破甲（Breach）使用。
  • minecraft:damage_protection：每“点”伤害减免可使持有该物品时受到的伤害降低 4%，最高可减免 80%。由爆炸保护（Blast Protection）、摔落保护（Feather Falling）、火焰保护（Fire Protection）、保护（Protection）和弹射物保护（Projectile Protection）使用。

与攻击相关：

  • minecraft:damage：修改该武器的攻击伤害。由锋利（Sharpness）、穿刺（Impaling）、节肢杀手（Bane of Arthropods）、力量（Power）和亡灵杀手（Smite）使用。
  • minecraft:smash_damage_per_fallen_block：为狼牙棒每下落一格增加伤害。由密度（Density）使用。
  • minecraft:knockback：修改持有该武器时造成的击退量，以游戏单位计。由击退（Knockback）和冲击（Punch）使用。
  • minecraft:mob_experience：修改击杀生物获得的经验值。原版未使用。

与耐久相关：

  • minecraft:item_damage：修改物品受到的耐久损耗。小于 1 的值表示物品受到损耗的概率。由耐久（Unbreaking）使用。
  • minecraft:repair_with_xp：使物品在获得经验时自动修复，并决定修复效率。由经验修补（Mending）使用。

与投射物相关：

  • minecraft:ammo_use：修改使用弓或弩时消耗的弹药数量。该值会被限制为整数，因此小于 1 的值将导致消耗 0 个弹药。被无限（Infinity）使用。
  • minecraft:projectile_piercing：修改该武器发射的抛射物可穿透的实体数量。被穿透（Piercing）使用。
  • minecraft:projectile_count：修改射击该弓时生成的抛射物数量。被多重射击（Multishot）使用。
  • minecraft:projectile_spread：修改抛射物发射时最大扩散角度（以度为单位）。被多重射击（Multishot）使用。
  • minecraft:trident_return_acceleration：使三叉戟能够返回持有者，并修改三叉戟返回时的加速度。被忠诚（Loyalty）使用。

其他：

  • minecraft:block_experience：修改破坏方块时获得的经验值数量。被精准采集（Silk Touch）使用。
  • minecraft:fishing_time_reduction：减少使用该鱼竿钓鱼时浮漂下沉所需的时间（以秒为单位）。被饵钓（Lure）使用。
  • minecraft:fishing_luck_bonus：修改钓鱼战利品表中使用的 幸运 值。被海之眷顾（Luck of the Sea）使用。

定义为 DataComponentType<List<TargetedConditionalEffect<EnchantmentValueEffect>>>​

  • minecraft:equipment_drops：修改使用该武器击杀实体时掉落装备的概率。被抢夺（Looting）使用。

基于位置的效果组件（Location Based Effect Components）​

另见：基于位置的效果组件，请参阅 Minecraft Wiki

基于位置的效果组件是实现了 EnchantmentLocationBasedEffect 的组件。这些组件定义了需要知道附魔持有者在世界中位置时应执行的操作。它们主要通过两个方法运作：EnchantmentEntityEffect#onChangedBlock，当附魔物品被装备或持有者的 BlockPos 发生变化时调用；以及 onDeactivate，当附魔物品被移除时调用。

下面是一个示例，使用了 minecraft:attributes 基于位置的效果组件类型，用于改变持有者实体的缩放比例：

// 类型为 "minecraft:attributes"（下文有详细描述）。
// 简而言之，这会应用一个属性修饰符。
"minecraft:attributes": [
    {
        // 此 "amount" 块是一个 LevelBasedValue。
        "amount": {
            "type": "minecraft:linear",
            "base": 1,
            "per_level_above_first": 1
        },

        // 要修改的属性。本例中为 "minecraft:scale"
        "attribute": "minecraft:generic.scale",
        // 此属性修饰符的唯一标识符。应避免与其他修饰符重复，但无需注册。
        "id": "examplemod:enchantment.size_change",
        // 属性操作类型。可选值为 "add_value"、"add_multiplied_base" 或 "add_multiplied_total"。
        "operation": "add_value"
    }
],

原版（Vanilla）提供了以下基于位置的事件：

  • minecraft:all_of：依次运行一组实体效果。
  • minecraft:apply_mob_effect：对受影响的生物施加一个生物效果。
  • minecraft:attribute：对附魔持有者应用一个属性修饰符。
  • minecraft:change_item_damage：损坏该物品的耐久度。
  • minecraft:damage_entity：对受影响的实体造成伤害。如果是在攻击上下文中，这个效果会与攻击伤害叠加。
  • minecraft:explode：生成一次爆炸。
  • minecraft:ignite：点燃实体，使其着火。
  • minecraft:play_sound：播放指定的声音。
  • minecraft:replace_block：在给定偏移位置替换一个方块。
  • minecraft:replace_disk：替换一片区域内的方块。
  • minecraft:run_function：运行指定的数据包函数。
  • minecraft:set_block_properies：修改指定方块的方块状态属性。
  • minecraft:spawn_particles：生成粒子效果。
  • minecraft:summon_entity：召唤一个实体。

原版基于位置的效果组件类型（Vanilla Location Based Effect Component Types）​

定义为 DataComponentType<List<ConditionalEffect<EnchantmentLocationBasedEffect>>>​

  • minecraft:location_changed：当持有者的方块位置发生变化、且该物品被装备时，运行一个基于位置的效果。该效果被冰霜行者（Frost Walker）和灵魂疾行（Soul Speed）附魔使用。

定义为 DataComponentType<List<EnchantmentAttributeEffect>>​

  • minecraft:attributes：对持有者应用一个属性修饰符，并在附魔物品不再装备时移除该修饰符。

实体效果组件（Entity Effect Components）​

另请参阅 实体效果组件（Entity Effect Components）在 Minecraft Wiki 上的相关内容。

实体效果组件是实现了 EnchantmentEntityEffect 接口的组件，该接口是 EnchantmentLocationBasedEffect 的一个子类型。这些组件会重写 EnchantmentLocationBasedEffect#onChangedBlock 方法，以运行 EnchantmentEntityEffect#apply 方法；此外，根据组件的具体类型，apply 方法也可能在代码库中的其他位置被直接调用。这使得效果可以在无需等待持有者方块位置变化的情况下生效。

所有类型的基于位置的效果组件，同样也可以作为实体效果组件的有效类型，除了 minecraft:attribute，它仅作为基于位置的效果组件注册。

下面是火焰附加（Fire Aspect）附魔的某个组件的 JSON 定义示例：

// 这个组件的类型是 "minecraft:post_attack"（见下文）。
"minecraft:post_attack": [
    {
        // 决定攻击的“受害者”（victim）、“攻击者”（attacker）或“造成伤害的实体”（如果有投射物就是投射物，否则为攻击者）谁会受到效果影响。
        "affected": "victim",
        
        // 决定要应用哪种附魔实体效果（enchantment entity effect）。
        "effect": {
            // 这个效果的类型是 "minecraft:ignite"。
            "type": "minecraft:ignite",
            // "minecraft:ignite" 需要一个 LevelBasedValue 作为点燃实体持续时间的参数。
            "duration": {
                "type": "minecraft:linear",
                "base": 4.0,
                "per_level_above_first": 4.0
            }
        },

        // 决定谁（"victim"、"attacker" 或 "damaging entity"）必须拥有该附魔，效果才会生效。
        "enchanted": "attacker",

        // 可选的谓词（predicate），用于控制效果是否应用。
        "requirements": {
            "condition": "minecraft:damage_source_properties",
            "predicate": {
                "is_direct": true
            }
        }
    }
]

这里，实体效果组件是 minecraft:post_attack。它的效果是 minecraft:ignite，由 Ignite 记录类型实现。该记录类型对 EnchantmentEntityEffect#apply 的实现会让目标实体着火。

原版附魔实体效果组件类型（Vanilla Enchantment Entity Effect Component Types）​

定义为 DataComponentType<List<ConditionalEffect<EnchantmentEntityEffect>>>​

  • minecraft:hit_block：当实体（例如抛射物）击中方块时运行实体效果。该组件被 Channeling 使用。
  • minecraft:tick：每个 tick 运行一次实体效果。该组件被 Soul Speed 使用。
  • minecraft:projectile_spawned：当弓或弩发射的抛射物实体生成后运行实体效果。该组件被 Flame 使用。

定义为 DataComponentType<List<TargetedConditionalEffect<EnchantmentEntityEffect>>>​

  • minecraft:post_attack：在攻击造成实体伤害后运行实体效果。该组件被 Bane of Arthropods、Channeling、Fire Aspect、Thorns 和 Wind Burst 使用。

有关每个组件的详细信息，请参阅 相关的 Minecraft Wiki 页面。

其他原版附魔组件类型（Other Vanilla Enchantment Component Types）​

定义为 DataComponentType<List<ConditionalEffect<DamageImmunity>>>​

  • minecraft:damage_immunity：为指定的伤害类型提供免疫效果。该组件被 Frost Walker 使用。

定义为 DataComponentType<Unit>​

  • minecraft:prevent_equipment_drop：防止该物品在玩家死亡时掉落。该组件被 Curse of Vanishing 使用。
  • minecraft:prevent_armor_change：防止该物品从护甲栏卸下。该组件被 Curse of Binding 使用。

定义为 DataComponentType<List<CrossbowItem.ChargingSounds>>​

  • minecraft:crossbow_charge_sounds：决定弩充能时播放的音效事件。每个条目代表附魔的一个等级。

定义为 DataComponentType<List<Holder<SoundEvent>>>​

  • minecraft:trident_sound：决定使用三叉戟时播放的音效事件。每个条目代表附魔的一个等级。