---
front:
hard: 入门
time: 分钟
---

# 自定义附魔

在原有游戏的基础上增加自定义附魔，自定义附魔效果需通过mod编写具体实现

## Demo 解释

1.[EnchantDemo](../13-模组SDK编程/60-Demo示例.md#EnchantDemo) 定义了4中魔咒类型：

- 疾行           -- 常驻类型附魔，移动速度变快，只可附在鞋子上
- 雷鸣四方       -- 循环类型附魔，每过一段时间在玩家周围落雷，只能附在头盔上
- 战利品         -- 触发类型附魔，攻击生物会在生物的位置产生一个苹果，只能附在镐上
- 沉重           -- 诅咒类型附魔，给玩家添加饥饿状态效果，只能附在剑上

2.修改了羊，马，牛，鸡的战利品表，分别对应下方文档中四种战利品表配置情况

3.添加了一个自定义稿子，可用于测试自定义附魔碰到自定义物品的情况

4.重写了图书管理员和武器匠的交易，可以卖附魔书和带有附魔的武器

## 1 功能

1. 注册新的附魔
2. 设置附魔可以附到哪些工具或装备
3. 设置附魔的最大等级，以及每级所消耗的经验值
4. 设置附魔稀有度
5. 设置附魔是否为宝藏型魔咒
6. 设置附魔是否可以通过图书管理员获得
7. 设置附魔是否为诅咒型魔咒
8. 设置冲突附魔
9. 可以从itemdict获取物品的附魔信息
10. 可以从附魔台对合适的工具或装备或书进行附魔
11. 带有自定义附魔的附魔书可以在铁砧上使用
12. 可以通过MC原生的附魔获取途径获取相应的附魔道具 [【附魔途径Wiki】](https://zh.minecraft.wiki/w/%E9%AD%94%E5%92%92)

## 2 注册自定义附魔

在mod**行为包和资源包**内添加`netease_enchants`文件夹，向其中添加自定义附魔json

### 2.1 自定义附魔json示例

```json
{
  "netease:enchant": {
    // 必填项
    "identifier": "demoenchant:customenchant1",  // 自定义附魔id，需全为小写字母
    "description": "enchantment.demoenchant.customenchant1",  // 自定义附魔名称，对应zh_CN.lang中的langStr
    "primary_slots": ["elytra"],  // 附魔槽位，被附魔物品只有槽位相同才能附魔成功
    "cost": [3,6,9,12,15],  // 附魔威力等级对应的经验消耗，会影响砂轮移除魔咒时返回的经验值以及在附魔台上被附魔到该魔咒的概率（cost越大附魔概率越小）;列表内元素数量需与max_level一致，否则注册失败

    // 选填项
	"frequency": "very_rare",  // 自定义附魔稀有度，影响铁砧结合附魔物品的经验消耗，默认为common
	"is_treasure_only": false,  // 设为true时为宝藏型魔咒，将影响附魔获取方式，默认为false
	"is_discoverable": true,  // 设为false时为宝藏型魔咒，将影响附魔获取方式，默认为true
	"is_lootable": true,  // 设为true时可以通过与图书管理员交易获得，默认为true
    "is_curse": false,  // 设为true时为诅咒附魔，不可通过砂轮移除，默认为false
	"max_level": 5,  // 附魔威力等级，设置后会自动在创造物品栏注册各等级的附魔书，默认为1
	"incompatible": ["unbreaking"]  // 冲突附魔名称
  }
}
```

### 2.2 primary_slots(附魔槽位)

自定义附魔可选槽位

| string         | 对应槽位                                                     |
| -------------- | ------------------------------------------------------------ |
| all            | 全部（以下全部槽位，非游戏中所有物品）                        |
| g_armor        | 全部盔甲                                                     |
| armor_head     | 头盔                                                         |
| armor_torso    | 胸甲                                                         |
| armor_legs     | 护腿                                                         |
| armor_feet     | 靴子                                                         |
| sword          | 剑                                                           |
| bow            | 弓                                                           |
| spear          | 三叉戟                                                       |
| crossbow       | 弩                                                           |
| g_tool         | 锄、剪刀、打火石、盾                                         |
| hoe            | 锄                                                           |
| shears         | 剪刀                                                         |
| flintsteel     | 打火石                                                       |
| shield         | 盾牌                                                         |
| g_digging      | 锄、斧、镐、锹                                               |
| axe            | 斧                                                           |
| pickaxe        | 镐                                                           |
| shovel         | 锹                                                           |
| fishing_rod    | 钓竿                                                         |
| carrot_stick   | 胡萝卜钓竿                                                   |
| elytra         | 鞘翅                                                         |
| cosmetic_head  | 骷髅模型/凋零骷髅模型/模型/僵尸模型/龙的模型/爬行者的模型/雕刻南瓜 |
| compass        | 指南针                                                       |
| mushroom_stick | 诡异菌钓竿                                                   |
| brush          | 刷子                                                         |

### 2.3 frequency(稀有度)

稀有度影响铁砧结合附魔物品时的经验消耗计算

默认：common

#### 2.3.1 各等级稀有度对应cost

| 稀有度    | cost |
| --------- | ---- |
| common    | 1    |
| uncommon  | 2    |
| rare      | 4    |
| very_rare | 8    |

#### 2.3.2 铁砧结合附魔物品消耗经验计算规则

1. 假定 物品1 拥有 附魔a、附魔b，它们稀有度对应的cost分别为cost_a和cost_b，威力等级分别为level_a和level_b，则物品的总cost计算规则如下：

​	total_cost = cost_a * level_a + cost_b * level_b

若物品为附魔书，则total_cost计算规则如下：

​	total_cost = max(1, cost_a / 2) * level_a + max(1, cost_b / 2) * level_b

若物品拥有更多数量的附魔，依上述公式类推

2. 计算铁砧上  物品1  的total_cost，此处设为initial_total_cost
3. 根据[铁砧结合物品规则](https://zh.minecraft.wiki/w/%E9%93%81%E7%A0%A7#.E7.94.A8.E9.80.94)，计算结合后预计产生的物品2的total_cost，此处设为combined_total_cost
4. final_cost = combined_total_cost - initial_total_cost
5. 若final_cost大于0，且物品1的数量大于1，则final_cost = 40 如下图：
6. 若铁砧结合的物品2不携带附魔，则final_cost = 0

**最终铁砧结合物品操作消耗经验还受其他因素影响，最终消耗等级可能大于final_cost**

![image-20210817155010961](./picture/custom_enchant.png)

#### 2.3.3 原生附魔id及frequency

| Type | 附魔名称   | identifier            | frequency |
| ---- | ---------- | --------------------- | --------- |
| 0    | 保护       | protection            | common    |
| 1    | 火焰保护   | fire_protection       | uncommon  |
| 2    | 摔落保护   | feather_falling       | uncommon  |
| 3    | 爆炸保护   | blast_protection      | rare      |
| 4    | 弹射物保护 | projectile_protection | uncommon  |
| 5    | 荆棘       | thorns                | very_rare |
| 6    | 水下呼吸   | respiration           | rare      |
| 7    | 深海探索者 | depth_strider         | rare      |
| 8    | 水下速掘   | aqua_affinity         | rare      |
| 9    | 锋利       | sharpness             | common    |
| 10   | 亡灵克星   | smite                 | uncommon  |
| 11   | 节肢克星   | bane_of_arthropods    | uncommon  |
| 12   | 击退       | knockback             | uncommon  |
| 13   | 火焰附加   | fire_aspect           | rare      |
| 14   | 抢夺       | looting               | rare      |
| 15   | 效率       | efficiency            | common    |
| 16   | 精准采集   | silk_touch            | very_rare |
| 17   | 耐久       | unbreaking            | uncommon  |
| 18   | 时运       | fortune               | rare      |
| 19   | 力量       | power                 | common    |
| 20   | 冲击       | punch                 | rare      |
| 21   | 火矢       | flame                 | rare      |
| 22   | 无限       | infinity              | very_rare |
| 23   | 海之眷顾   | luck_of_the_sea       | rare      |
| 24   | 饵钓       | lure                  | rare      |
| 25   | 冰霜行者   | frost_walker          | rare      |
| 26   | 经验修补   | mending               | rare      |
| 27   | 绑定诅咒   | binding               | very_rare |
| 28   | 消失诅咒   | vanishing             | very_rare |
| 29   | 穿刺       | impaling              | uncommon  |
| 30   | 激流       | riptide               | rare      |
| 31   | 忠诚       | loyalty               | common    |
| 32   | 引雷       | channeling            | very_rare |
| 33   | 多重箭     | multishot             | rare      |
| 34   | 穿透       | piercing              | common    |
| 35   | 快速装填   | quick_charge          | uncommon  |
| 36   | 灵魂疾行   | soul_speed            | very_rare |
| 37   | 迅捷潜行   | swift_sneak           | very_rare |

### 2.4 is_treasure_only(是否为宝藏型魔咒)

当is_treasure_only设为true时，该附魔仅能通过以下方式获取：

1. 通过配置[ ***指定附魔等级的附魔物品*** 的战利品表](#enchant_with_levels)，概率获取
2. 通过配置[ ***随机附魔物物品*** 的战利品表](#enchant_randomly)，概率获取
3. 通过配置[ ***指定附魔物品*** 的战利品表](#specific_enchants)，概率获取
4. 通过与图书管理员交易获取，且图书管理员会为宝藏型魔咒的附魔书提出双倍要价

默认：false

### 2.5 is_discoverable

当is_discoverable设为false时，该附魔仅能通过以下方式获取：

1. 当is_lootable为true时，通过与图书管理员交易获取
2. 通过配置[ ***指定附魔物品*** 的战利品表](#specific_enchants)，概率获取

默认：true

### 2.6 is_lootable(是否可通过图书管理员交易)

is_lootable只影响与图书管理员的交易，当设为true时图书管理员可能出售包含该附魔的附魔书

### 2.7 is_curse(是否为诅咒型附魔)

is_curse设为true时为诅咒附魔，不可通过砂轮移除

默认值:false

### 2.8 max_level(附魔威力等级)

max_level设置后会自动在创造栏注册各等级的附魔书(max_level必须和cost数组长度相等)

默认值：1

## 3 附魔指令/enchant

 成功注册的自定义附魔将出现在/enchant指令备选项中，仅支持以下格式：

**/enchant <*玩家：目标*> <*魔咒名：魔咒id(string)*> [*等级：整数*]**

关于/enchant指令详见[官方wiki](https://zh.minecraft.wiki/w/%E5%91%BD%E4%BB%A4/enchant)

## 4 战利品表配置自定义附魔

### 4.1 战利品表概念见[官方wiki](https://zh.minecraft.wiki/w/%E6%88%98%E5%88%A9%E5%93%81%E8%A1%A8)

### 4.2 获得附魔物品的战利品表配置举例：

#### 4.2.1 获得 ***指定附魔等级的附魔物品*** 的战利品表配置<span id="enchant_with_levels"></span>

```json
{
    "pools": [
        {
            "rolls": 1,  // 抽取次数
            "entries": [
                {
                    "type": "item",  // 掉落类型
                    "name": "minecraft:book",  // 物品名称
                    "weight": 15,  // 权重
                    "functions": [
                        {
                            // 指定附魔等级的附魔物品函数
                            "function": "enchant_with_levels",
                            // 附魔等级
                            "levels": 30,
                            // 物品是否能被附上宝藏型附魔("is_lootable")，默认为false
                            "treasure": true
                        }
                    ]
                }
            ]
        }
    ]
}
```

附魔函数：enchant_with_levels  指定附魔等级的附魔物品函数

附魔参数：levels         [附魔等级](https://zh.minecraft.wiki/w/%E9%99%84%E9%AD%94%EF%BC%88%E7%89%A9%E5%93%81%E4%BF%AE%E9%A5%B0%EF%BC%89#%E9%99%84%E9%AD%94%E7%AD%89%E7%BA%A7)

​          treasure    物品是否能附上宝藏型附魔

4.2.2  获得 ***随机附魔物品*** 的战利品表配置<span id="enchant_randomly"></span>

```json
{
    "pools": [
        {
            "rolls": 1,  // 抽取次数
            "entries": [
                {
                      "type": "item",  // 掉落类型
                      "name": "minecraft:golden_sword",  // 物品名称
                      "weight": 15,  // 权重
                      "functions": [
                          {
                              // 随机附魔函数，附魔等级为1-30内随机整数
                              "function": "enchant_randomly",
                              // 物品是否能被附上宝藏附魔("is_lootable")，默认为false
                              "treasure": true
                          }
                      ]
                }
            ]
        }
    ]
}
```

附魔函数：enchant_randomly  随机附魔函数，[附魔等级](https://zh.minecraft.wiki/w/%E9%99%84%E9%AD%94%EF%BC%88%E7%89%A9%E5%93%81%E4%BF%AE%E9%A5%B0%EF%BC%89#%E9%99%84%E9%AD%94%E7%AD%89%E7%BA%A7)为1-30内的随机数

附魔参数：treasure   物品是否能附上宝藏型附魔

#### 4.2.3 获得 ***指定附魔物品*** 的战利品表配置<span id="specific_enchants"></span>

```json
{
    "pools": [
        {
            "rolls": 1,  // 抽取次数
            "entries": [
                {
                    "type": "item",  // 掉落类型
                    "name": "minecraft:iron_boots",  // 物品名称
                    "weight": 5,  // 权重
                    "functions": [
                        {
                            // 获取指定附魔的附魔物品函数
                            "function": "specific_enchants",
                            "enchants": [
                                {
                                    // 指定的附魔id/自定义附魔identifier
                                    "id": "soul_speed",
                                    // 魔咒威力范围，默认为[1,1]，非附魔等级
                                    "level": [1, 3]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}
```

附魔函数：specific_enchants 指定附魔的附魔物品函数

附魔参数：enchants 指定附魔列表

4.2.4 获得 ***附魔装备*** 的战利品表配置

```json
{
    "pools": [
        {
            "rolls": 1,
            "entries": [
                {
                    "type": "item",
                    "name": "minecraft:golden_sword",
                    "weight": 1,
                    "functions": [
                        {
                            // 随机附魔装备/工具的函数
                            "function": "enchant_random_gear",
                            // 被附魔的概率
                            "chance": 0.25
                        }
                    ]
                }
            ]
        }
    ]
}
```

附魔函数：enchant_random_gear 随机附魔装备/工具的函数

附魔参数：chance   被附魔的概率

注：[附魔等级](https://zh.minecraft.wiki/w/%E9%99%84%E9%AD%94%EF%BC%88%E7%89%A9%E5%93%81%E4%BF%AE%E9%A5%B0%EF%BC%89#%E9%99%84%E9%AD%94%E7%AD%89%E7%BA%A7)非[魔咒威力](https://zh.minecraft.wiki/w/%E9%AD%94%E5%92%92)，具体可查看[【官方Wiki】](https://zh.minecraft.wiki/w/%E9%99%84%E9%AD%94%EF%BC%88%E7%89%A9%E5%93%81%E4%BF%AE%E9%A5%B0%EF%BC%89#%E9%99%84%E9%AD%94%E7%AD%89%E7%BA%A7)

## 5 村民交易

### 5.1 村民交易所需物品数量计算规则：

- 交易所需第一个物品数量(costA)遵循以下规则：
  1. 若quantity配置为`"quantity" : {"min": min, "max": max}`，则costA在min和max之间取随机整数
  2. 若quantity配置为`"quantity": num`，则costA = num
  3. 若costA大于所需消耗物品最大堆叠数，costA取该物品最大堆叠数
  4. 根据配置的函数修改costA，例如与图书管理员交易获取附魔书"enchant_book_for_trading"会修改costA，规则见[图书管理员交易](#librarain)
  5. 最终costA会根据玩家是否拥有[村庄英雄](https://zh.minecraft.wiki/w/%E6%9D%91%E5%BA%84%E8%8B%B1%E9%9B%84)状态，及"price_multiplier"配置（见[交易经济](https://zh.minecraft.wiki/w/%E6%B5%81%E6%B5%AA%E5%95%86%E4%BA%BA)），再进行增减
- 交易所需第二个物品数量（如有）(costB)遵循以下规则：
  1. 若quantity配置为`"quantity" : {"min": min, "max": max}`，则costB在min和max之间取随机整数
  2. 若quantity配置为`"quantity": num`，则costB = num
  3. 若costB大于所需消耗物品最大堆叠数，costB取该物品最大堆叠数
  4. 与第一个物品不同的是，第二个物品仅受quantity影响，不会因其他原因增减

### 5.2 图书管理员交易表<span id="librarain"></span>

图书管理员交易附魔书所需第一个物品数量计算规则：

1. 随机选取一个"is_lootable": true的附魔（灵魂疾行不包含在内）

2. 最终附魔威力等级在该附魔最小威力等级和最大威力等级间取随机整数

3. baseCostA = base_cost + random.int(base_random_cost + 附魔威力等级 * per_level_random_cost) + per_level_cost * 附魔威力等级

   *base_cost/base_random_cost/per_level_random_cost/per_level_cost见下文enchant_book_for_trading配置*

4. 若该附魔为宝藏附魔，则baseCostA = baseCostA * 2

5. 若baseCostA大于所需消耗物品最大堆叠数，baseCostA取该物品最大堆叠数

图书管理员交易表举例如下：

```json
{
  "tiers": [
    {
      "total_exp_required": 0,  // 解锁该组交易所需的村民经验
      "groups": [
        {
          "num_to_select": 1,  // 从下列交易中选取几项交易
          "trades": [
            {
              // 该交易需求的物品信息
              "wants": [
                // 第一个物品
                {
                  "item": "minecraft:paper", // 物品名称
                  "quantity": 24,  // 物品数量
                  "price_multiplier": 0.05  // 价格乘数（影响补货后的价格）
                },
                // 第二个物品(也可不设第二个物品)
                {
                  "item": "minecraft:book", // 物品名称
                  "quantity": 1  // 物品数量
                }
              ],
              // 该交易给予玩家的物品信息
              "gives": [
                {
                  "item": "minecraft:book",  // 物品名称
                  "quantity": 1,  // 物品数量
                  "functions": [
                    {
                      "function": "enchant_book_for_trading",  // 交易附魔书
                      "base_cost": 2,  // 默认为2
                      "base_random_cost": 5,  // 默认为5
                      "per_level_random_cost": 10,  // 默认为10
                      "per_level_cost": 3  // 默认为3
                    }
                  ]
                }
              ],
              // 单次交易完成后增加的村民经验值
              "trader_exp": 2,
              // 最大交易次数
              "max_uses": 16,
              // 交易完成后是否给予玩家经验，默认为true
              "reward_exp": true
            }
          ]
        }
      ]
    }
  ]
}
```

### 5.3 武器商交易表

武器商交易表举例如下：

```json
{
  "tiers": [
    {
      "total_exp_required": 0,  // 解锁该组交易所需的村民经验
      "groups": [
        {
          "num_to_select": 1,  // 从下列交易中选取几项交易
          "trades": [
            {
              // 该交易需求的物品信息
              "wants": [
                // 第一个物品
                {
                  "item": "minecraft:coal:0", // 物品名称
                  "quantity": 15,  // 物品数量
                  "price_multiplier": 0.05  // 价格乘数（影响补货后的价格）
                }
              ],
              // 该交易给予玩家的物品信息
              "gives": [
                {
                  "item": "minecraft:iron_sword", // 物品名称
                  "quantity": 1,  // 物品数量
                  "functions": [
                    {
                      "function": "enchant_with_levels",  // 为物品附上指定等级附魔
                      // 物品是否能被附上宝藏附魔("is_lootable")，默认为false
                      "treasure": false,
                      // 最终等级在最小等级和最大等级间取随机整数
                      "levels": {
                        "min": 5,  // 最小附魔等级
                        "max": 19  // 最大附魔等级
                      }
                    }
                  ]
                }
              ],
              // 单次交易完成后增加的村民经验值
              "trader_exp": 2,
              // 最大交易次数
              "max_uses": 16,
              // 交易完成后是否给予玩家经验，默认为true
              "reward_exp": true
            }
          ]
        }
      ]
    }
  ]
}
```

## 6 自定义附魔与自定义物品

### 6.1 自定义武器及工具

自定义武器及工具支持原生附魔和自定义附魔

自定义武器/工具的netease:weapon组件type值及对应自定义附魔槽位关系如下:

| type    | 对应自定义附魔槽位 |
| ------- | ------------------ |
| sword   | sword              |
| shovel  | shovel             |
| pickaxe | pickaxe            |
| hatchet | **axe**            |
| hoe     | hoe                |

### 6.2 自定义盔甲

自定义盔甲支持原生附魔及自定义附魔

自定义盔甲的netease:armor组件armor_slot值及对应的自定义附魔槽位关系如下:

| armor_slot | ArmorSlotType | 自定义附魔槽位 |
| ---------- | ------------- | -------------- |
| 0          | HEAD          | armor_head     |
| 1          | BODY          | armor_torso    |
| 2          | LEG           | armor_legs     |
| 3          | FOOT          | armor_feet     |

### 6.3 自定义远程武器

自定义远程武器无法附上原生魔咒，但可以附上primary_slots配置为**bow**或**crossbow**的自定义附魔



### 6.4 无法在附魔台上进行自定义附魔的物品

由于原版特性，下列物品**无法在附魔台上进行自定义附魔，但可以在铁砧上进行自定义附魔**：

- 剪刀（对应槽位shears）
- 打火石（对应槽位flintsteel）
- 盾（对应槽位shield）
- 鞘翅（对应槽位elytra）
- 骷髅模型/凋零骷髅模型/模型/僵尸模型/龙的模型/爬行者的模型/雕刻南瓜（对应槽位cosmetic_head）
- 指南针（对应槽位compass）

## 7 自定义附魔相关API

### 7.1 AddModEnchantToInvItem

给物品栏中物品添加自定义附魔信息

### 7.2 RemoveModEnchantToInvItem

给物品栏中物品移除自定义附魔信息

### 7.3 GetInvItemModEnchantData

获取物品栏的物品自定义附魔信息

### 7.4 GetEquItemModEnchant

获取装备槽位中盔甲的自定义附魔

## 8 自定义附魔相关事件

### 8.1 OnItemPutInEnchantingModelServerEvent

触发时机：玩家将可附魔物品放到附魔台上时，可修改附魔台选项

## 9 参考资料

[官方wiki-附魔机制](https://zh.minecraft.wiki/w/%E9%99%84%E9%AD%94%EF%BC%88%E7%89%A9%E5%93%81%E4%BF%AE%E9%A5%B0%EF%BC%89)

[官方wiki-附魔](https://zh.minecraft.wiki/w/%E9%AD%94%E5%92%92)

[官方wiki-附魔指令/enchant](https://zh.minecraft.wiki/w/%E5%91%BD%E4%BB%A4/enchant)

[官方wiki-交易](https://zh.minecraft.wiki/w/%E4%BA%A4%E6%98%93)