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

# 自定义状态效果

### 概述

该功能不需要开启实验性玩法。

开发者可以在addon的behavior_pack目录下新增netease_effects文件夹， 然后配置json文件来添加自定义状态效果。详情可以参考示例[CustomEffectsMod](../13-模组SDK编程/60-Demo示例.md#CustomEffectsMod)

### 自定义状态效果Json

首先在行为包behavior_pack目录下新增netease_effects文件夹，并在其中添加自定义状态的Json配置文件，文件名不做要求，其Json文件格式如下所示：

```json
{
  "format_version": "1.10",
  "minecraft:effect": {
    "description": {
      "identifier": "custom_effect:weightless"
    },
    "components": {
      "minecraft:particle_color": [255, 255, 255],
      "minecraft:icon": "weightless"
    }
  }
}
```

下面对部分节点进行说明：

- `"minecraft:effect"`：该节点为自定义状态配置表最外层节点
  - `"description"`：该节点为自定义状态描述信息
    - `"identifier"`：该节点为自定义状态的名称，分为命名空间及状态名，命名空间推荐与mod名称一致，identifier必须全局唯一。mod中其他地方都是用这个identifier与这个自定义状态对应上。注：identifier必须**全小写**，如果有大写字母，在添加到自定义食物中时会失效
  - `"components"`：该节点为自定义状态相关组件
    - `"minecraft:particle_color"`：该节点为添加状态后玩家身上粒子效果的颜色，采用RGB颜色模式，数据类型为[int, int, int]，每个int型取值范围为0-255
    - `"minecraft:icon"`：该节点为自定义状态图标名称，数据类型为string

接下来在资源包resource_pack/textures/ui下添加自定义状态的图标。以该Json配置文件为例,其`"minecraft:icon"`字段的值为`"weightless"`，因此其图标应该命名为`weightless_effect.png`。注意，此处**图标路径**及**命名**必须严格遵守，否则将不会生效。

最后，在本地化文件texts/zh_CN.lang中添加如下设置可以对自定义状态名称进行汉化：

```
minecraft:custom_effect=自定义状态
```



### 自定义食物中添加自定义状态

自定义状态可以通过接口（详情见ModSDK文档中effect组件）添加，也可以通过配置自定义食物的Json文件，食用该自定义食物的时候获取到对应的自定义状态，一个自定义食物的Json文件格式如下：

```Json
{
  "format_version": "1.10",
  "minecraft:item": {
    "description": {
      "identifier": "itemMod:testFood",
      "category":"Nature"
    },

    "components": {
      "minecraft:use_duration": 32,
      "minecraft:max_stack_size": 64,
      "minecraft:food": {
        "nutrition": 100,
        "saturation_modifier": "supernatural",
        "can_always_eat":true,
        "effects": [
          {
            "name": "custom_effect:weightless",
            "chance": 1.0,
            "duration": 30,
            "amplifier": 4
          }
        ]
      }
    }
  }
}
```

其中只需要在`"effects"`字段下添加对应的状态信息即可，每个字段含义如下：

- `"name"`：状态名称，如果是自定义状态的话，此处与自定义状态的`"identifier"`相对应
- `"chance"`：获得该状态的概率，取值0-1之间
- `"duration"`：状态效果持续时间，单位秒
- `"amplifier"`：状态放大倍数，该值加1即为状态效果等级

自定义食物的其他相关定义参见3-9自定义物品文档



### Demo解释

在6-1DemoMod中我们提供了一个自定义状态效果的DemoMod [CustomEffectsMod](../13-模组SDK编程/60-Demo示例.md#CustomEffectsMod)。该mod主要实现了以下功能：

- 定义了一个自定义状态——失重：
  - custom_effect:weightless
    - 自定义了该状态的图标（weightless_effect.png）及例子效果颜色（白色）
- 定义了一个自定义食物:
  - itemMod:testFood
    - 自定义了该食物的图标
    - 食用该食物可以获得自定义的失重状态
- 在customEffectServer.py中监听了添加状态和状态移除时的事件
  - 如果添加的状态为失重，设置玩家重力为-0.03
  - 如果移除的状态为失重，重新设置玩家重力为默认值

除了自定义食物可以添加自定义状态外，我们还提供了AddEffectToEntity接口给指定实体添加指定状态，以及RemoveEffectFromEntity接口移除指定实体的指定状态，详细接口用法可以参考<a href="../../../mcdocs/1-ModAPI/接口/实体/状态效果.html" rel="noopenner"> 状态效果接口 </a>。

在实体获得状态以及状态被移除（无论是调用RemoveEffectFromEntity接口主动还是持续时间结束被移除）均会触发对应的事件，开发者需要监听对应事件来为对应的自定义状态添加或移除效果逻辑。详情可参考：

- <a href="../../../mcdocs/1-ModAPI/事件/实体.html#addeffectserverevent" rel="noopenner"> 添加状态事件-AddEffectServerEvent </a>
- <a href="../../../mcdocs/1-ModAPI/事件/实体.html#removeeffectserverevent" rel="noopenner"> 删除状态事件-RemoveEffectServerEvent </a>
- <a href="../../../mcdocs/1-ModAPI/事件/实体.html#refresheffectserverevent" rel="noopenner"> 更新状态事件-RefreshEffectServerEvent </a>

注：自定义状态无法通过/effect指令获取