# 配置一个效果

## 示例效果配置

```yaml
id: spawn_particle
args:
  amount: 10
  chance: 25
  particle: soul
triggers:
  - mine_block
filters:
  blocks:
    - diamond_ore
    - ancient_debris
conditions: [ ]
mutators:
  - id: translate_location
    args:
      add_x: 0.5
      add_y: 0.5
      add_z: 0.5
```

此效果代表的是当你挖掘钻石矿或者下届残骸时有25%几率在挖掘的矿石中间生成一个灵魂粒子效果。

## 占位符

eco 系列插件中，所有只能读取数值的选项都可以解析占位符并进行数学计算。例如一个玩家高度越高，几率越低的示例：

* chance: 100 - `%player_y%`

\*其中 `%player_y%` 是 PlaceholderAPI 中 player 拓展提供的一个变量符。

永久效果会在激活时读取变量符的数值，触发效果会在触发时读取变量符的数值。请确保你确实在合适的时机读取了这些变量符，否则会导致奇怪的问题。

以下是插件提供的额外变量符可供使用：

* `%trigger_value%`，`%triggervalue%`，`%trigger%`，`%value%`，`%tv%`，`%v%` 和 `%t%`：触发器提供的值（例如攻击时造成的伤害值等）。
* `%player%`：玩家名称。
* `%player_uuid%`：玩家UUID。
* `%victim_health%`：目标的血量。
* `%victim_max_health%`：目标的最高血量。
* `%distance%`：玩家和目标的距离。
* `%victim_level%`：目标的等级，需要 LevelledMobs。
* 如果目标也是一名玩家，那么可以使用 `%victim_想要使用的变量符%` 来显示目标的对应变量符。例如 `%victim_player_y%` 显示目标的 Y 轴坐标。
* `%hits%`：玩家击打该目标的次数。
* `%text%`，`%string%` 和 `%message%`：触发器的文本，例如聊天时的消息内容。
* `%location_x%`，`%loc_x%` 和 `%x%`：效果作用位置的 X 轴。
* `%location_block_x%`，`%loc_b_x%`，`%block_x%` 和 `%bx%`：效果对应方块的位置的 X 轴。
* 将 x 替换为 y 或者 z 则分别代表 Y 轴和 Z 轴。
* `%location_world%`，`%loc_w%`和 `%world%`：效果作用世界。

## 配置部分

每个效果都是由如下的配置组成：

* id：该效果使用的效果ID，所有效果ID列表可在 这里 查看。
* args：该效果的参数。可用的参数可在各个效果介绍中查看。
* triggers：该效果的触发器。如果该效果是永久效果，则没有这个选项。
* filters：筛选何种情况能够触发触发器。例如 mine\_block 触发器可以使用 blocks 筛选出能够触发的方块，melee\_attack 触发器可用使用 entities 筛选出能够触发的实体。
* conditions：在满足何种条件下才会触发该效果。
* mutators：该效果的变化。例如将效果的位置变化成玩家的位置等。

## 可用参数

\*参数即是上文已经介绍的 args 选项。

**`chance`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#chance)

该效果执行的几率，默认为 100。

```yaml
args:
  chance: 50
```

**`cooldown`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#cooldown)

该效果执行的冷却时间，以，默认为 0。

另外提供其他的可选选项。

```yaml
args:
  cooldown: 10
  send_cooldown_message: true # 是否发送冷却消息提示
  cooldown_message: "还有 %seconds% 秒" # 冷却消息提示
  cooldown_effects: # 冷却期间将会触发的效果
    - id: send_message
      args:
        message: "正在冷却中，再等 &a%seconds%&r 秒."
```

**`cost`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#cost)

执行该效果消耗的经济。仅支持 Vault。默认为 0。

```yaml
args:
  cost: 200
```

**`every`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#every)

每多少次触发器触发后执行一次效果。默认为 1。

```yaml
args:
  every: 3
```

**`mana_cost`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#mana_cost)

执行该效果消耗的法力。仅支持 AureliumSkills。默认为 0。

```yaml
args:
  mana_cost: 10
```

**`<魔法>_cost`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#magic_cost)

同上，仅支持 EcoSkills。

```yaml
args:
  mana_cost: 10
```

**`delay`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#delay)

触发器触发后延迟多少秒执行动作。默认为 0。

```yaml
args:
  delay: 20
```

**`filters_before_mutation`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#filters_before_mutation)

默认情况下，效果在变化数据后再执行筛选。如果你想反着来，将其修改为 true。

```yaml
args:
  filters_before_mutation: true
```

**`disable_antigrief_check`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#disable_antigrief_check)

默认情况下，插件会检查效果是否作用于受到保护的领地等。如果你不想这样，将其修改为 true。

```yaml
args:
  disable_antigrief_check: true
```

**`point_cost`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#point_cost)

执行该效果消耗的点数，如下所示：

```yaml
args:
  point_cost:
    cost: 100 * %player_y%
    type: g_souls
```

**`price`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#price)

执行该效果消耗的价格，其中 type 选项填写 [价格](/auxilor-plugins/tong-yong-xin-xi/jia-ge.md) 一节所示的格式，如下所示：

```yaml
args:
  price:
    value: 100 * %player_y%
    type: crystals
      display: "&b%value% 水晶 ❖"
```

**`weight`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#weight)

效果的权重，在多个子效果中使用，设置该效果被执行的几率。

此效果执行的几率是 `<此元素的权重> / <所有效果的权重>`

```yaml
args:
  weight: 10
```

**`run_order`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#run_order)

效果的执行顺序，在多个子效果中使用，可设置为 `start`，`early`，`normal`，`late` 和 `end`。\*从左到右是依次从前到后。

各个效果之间默认有自己的执行顺序（使得这些效果能够以预期实现），但是这个选项可以覆盖默认值，例如让 `add_damage` 效果(其默认是 `late`) 在 `damage_multiplier` (其默认为 `normal`) 之前运行

```yaml
args:
  run-order: early
```

**`custom_<id>`**[**​**](https://plugins.auxilor.io/effects/configuring-an-effect#custom_id)

这代表使用 [自定义参数](/auxilor-plugins/zi-ding-yi-xiao-guo/zi-ding-yi-can-shu.md)。

```yaml
args:
  custom_<id>:
    <参数 1>: <值>
    <参数 2>: <值>
```

## \*永久效果与触发效果

所有的效果分为 **永久效果** 和 **触发效果** 两种。但是在这里，我们需要知道：

* 永久效果效果不需要触发器，也就是在 `effects` 选项中，不需要 `triggers` 选项，你就是设置了也没用。玩家一旦激活了技能，在没有变化情况下该技能不会失效。出现变化指的是，例如你不再手持这个物品了，你不再激活这个宠物了，加倍器过期了等等。
* 触发技能需要触发器，不填写 `triggers` 选项将会导致该技能失效。该技能只会在触发器被触发的瞬间生效。

根据常识，我们也很好判断该技能到底是永久技能还是触发技能，我们以一个镐子为例，我需要设置玩家手持这把镐子时一直拥有力量药水效果，那么很明显这是永久技能，如果我需要设置玩家使用这本镐子挖矿时，每次挖矿都会掉落金币，那么这很明显是触发技能，因为玩家只有在使用这把镐子挖掘方块情况下才会获得金币，并且我也不可能设置玩家手持这把镐子一直无限制获取金币。

## \*触发器内包含的属性

触发器触发后会有如下属性：

* 触发对象：是什么触发了触发器，可以是玩家、方块、其他实体等。这个属性是每个触发器都有的。
* 目标：而触发器作用的“对象”就是目标，这里好像是一句废话，因为我们得需要举一些例子才能帮助你知道何为目标。
  * 一个击杀怪物有几率使其流血的效果，它的目标就是被攻击的怪物。
  * 一个钓鱼有几率获得经验值的效果，它的目标就是被钓起的鱼。
  * `take_damage` 触发器有些不同，玩家为目标（因为受伤的是玩家），目标为触发对象（因为是怪物等对玩家造成伤害的）。
* 位置：大部分情况下，触发器触发的位置就是位置。而拥有玩家或者目标的效果，则有可能是玩家或者目标的位置。（本文在部分语境下也称作坐标）
* 方块：触发器执行作用的方块，例如 `mine_block` 即是挖掘的方块。
* 事件：触发器监听的事件，开发者会使用较多。
* 弹射物：触发器触发的弹射物，一般仅在弹射物类型的触发器有效。（本文部分地方也称作抛掷物）
* 向量：触发器触发的向量，一般在弹射物类型的触发器中是弹射物的向量，其他情况下则是玩家或者目标的向量。
* 物品：触发器触发的物品，一般是玩家手上的物品，如果是合成、熔炼等类型的触发器，则是结果物品。也有可能是目标手上的物品。
* 文本：触发器触发的文本，一般只在聊天和指令触发器有效。
* 值：见所有触发器页面。

## 连锁效果

连锁效果是将多个效果同时执行的一种功能。它可以用于执行效果的几率（chance 参数），如果你将多个效果分别设置几率，那么它们是基于各自的触发器独自拥有自己的几率值，这会导致某个效果没有执行却向玩家发送了执行成功的消息（分别是 2 个效果）的情况，而使用连锁效果就可以解决这个问题。

你可以在 `plugins/libreforge/chains.yml` 文件中找到连锁效果的配置文件：

```yaml
chains:
  - id: <连锁ID>
    effects:
      - <效果1>
      - <效果2>
      - <效果3>
```

**连锁效果内的子效果不需要设置触发器（triggers选项），因为它们都是由 run\_chain 效果触发激活的。**

你可以在这个文件以此格式添加无数多的连锁效果，然后使用 `run_chain` 效果使用它们，就像这样：

```yaml
id: run_chain
args:
  chance: 50 * (%player_health% / 20) # 使用变量符和数学公式的示例
  cooldown: 2
  chain: <连锁ID>
triggers:
  - melee_attack
  - bow_attack
  - trident_attack
filters:
  entities:
    - zombie
    - creeper charged
    - skeleton
```

在连锁效果中可以使用自己定义新的变量符，以在多个效果之间互相传递某个数值，例如：

```yaml
id: run_chain
args:
  chain: <连锁ID>
  chain_args:
    strength: %player_y% * 100 # 可以在这里设置数字或者字符串
```

在连锁效果中，我们可以使用 `%变量符id%` 的格式使用它们，例如这里即为 `%strength%`。[​](https://plugins.auxilor.io/effects/configuring-an-effect#inline-chains)

## 内部连锁

内部连锁是另外一种连锁效果，内部连锁可以直接在 effects 选项中设置，对于不需要重复使用的连锁效果，可以考虑使用这种格式：

```yaml
effects:
  - <效果1>
  - <效果2>
  - <效果3>
triggers:
  - mine_block
args:
  every: 3
```

内部连锁也支持定义新的变量符，如连锁效果一样。

连锁中的效果是互相独立运行的，这意味着如果你给其中的某个子效果增加了变化，但是对于其他子效果来说这个变化是不存在的，像几率、延迟等参数也是如此，如果你要让这些效果通用一个配置，请将它们添加到母效果中（即 `run_chain` 效果）中去。

连锁效果类型以下几种类型：

* **normal**: 每次母效果执行时，所有的子效果依次执行。
* **cycle**: 每次母效果执行时，所有的子效果只执行其中一个，按顺序依次循环执行。
* **random**: 每次母效果执行时，从所有的子效果中随机执行其中一个。

要选择连锁效果类型，需要在配置中添加 `run-type` 参数：

```yaml
effects:
  - triggers:
      - alt_click
    effects:
      - <效果1>
      - <效果2>
      - <效果3>
    args:
      run-type: random
      chance: 30
```

这也是另外一种内部连锁的格式，我们无需设置母效果的 ID 等。

## 加载权重

所有的配置在读取时按照字母顺序排列，但是这有时候会出现一些问题。例如在某个 EcoItems 的物品中需要使用其他物品作为合成配方，这时就需要保证被作为合成材料的物品需要在这个物品之前加载。你可以在配置中添加 `load-weight: <权重值>` 来自定义权重值。默认情况下，所有的效果的权重值都是 100，你可以设置成其他数字，例如 10 比 20 更早读取。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.superiormc.cn/auxilor-plugins/zi-ding-yi-xiao-guo/pei-zhi-yi-ge-xiao-guo.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.