Configuring an Effect

The Basics

First, you need to know of the different types of Effects: Triggered and Permanent. These are configured similarly but there are a few differences. The main difference is that all Triggered effects require a trigger to activate, Permanent effects are always active if all conditions (optional) are met.

Example Effect Config

effects:
  - id: spawn_particle
    args:
      amount: 10
      particle: soul
      chance: 25
    triggers:
      - mine_block
    filters:
      blocks:
        - diamond_ore
        - deepslate_diamond_ore
    mutators:
      - id: translate_location
        args:
          add_x: 0.5
          add_y: 0.5
          add_z: 0.5
    conditions:
      - id: below_y
        args:
          y: 10

The example effect: 25% chance to spawn 10 soul particles in the centre of a diamond ore when its mined and the player is below Y level 10.

Understanding The Sections

id: The ID of the effect. You can find all the effects under "All Effects" on the sidebar.

args: The args for the effect (from the effect page). There are additional optional args that you can put here (see below).

triggers: The list of triggers that activate this effect. (This does not apply on permanent effects).

filters: The list of filters to be applied on the trigger. (e.g. blocks filter on mine_block trigger, or entities filter on melee_attack trigger.)

conditions: As well as each effect holder (e.g. Talisman, Reforge, Enchant) having its own conditions, you can specify a list of effect-specific conditions that work in exactly the same way

mutators: Mutate the data sent to the effect: you can change parameters such as the victim, the location, etc. A mutator, like an effect or condition, consists of an ID and arguments.

Optional Arguments

chance

The chance of this effect activating, as a percentage. (defaults to 100)

args:
  chance: 50

cooldown

The cooldown between effect activations, in seconds. (defaults to 0)

args:
  cooldown: 10
  cooldown_group: magic_abilities # (Optional) The cooldown group, if not specified the cooldown will be for this effect only
  send_cooldown_message: true # (Optional) If the cooldown message should be sent
  cooldown_message: "Custom cooldown message with %seconds% left" # (Optional) a custom cooldown message
  cooldown_effects: # (Optional) Effects to run if on cooldown
    - id: send_message
      args:
        message: "You are on cooldown! Try again in &a%seconds%&r seconds."

cost

The cost required to use or activate this effect. Requires Vault. (defaults to 0)

args:
  cost: 200

every

Specify the effect to activate every x times. (defaults to always)

args:
  every: 3

require

Require an expression to be true for the effect to run.

args:
  require: '%ecobits_crystals% > 4'

mana_cost

The mana cost required to use or activate this effect. Requires Aurelium Skills. (defaults to 0)

args:
  mana_cost: 10

<magic>_cost

The magic cost (e.g. mana) required to use or activate this effect. Requires EcoSkills. (defaults to 0)

args:
  mana_cost: 10

delay

The amount of ticks to wait before executing the effect. (defaults to 0)

args:
  delay: 20

repeat

Specify the effect to activate repeatedly. If the effect has a delay, it will delay between each repeat. If the effect has any mutators, they will run again for each repeat.

This provides new placeholders: %repeat_times%, %repeat_start%, %repeat_increment%, and %repeat_count%.

  args:
    repeat:
      times: 5 # How many times the effect should be repeated
      start: -10 # The initial value of the %repeat_count% placeholder
      increment: 10 # How much the count should be increased (or decreased) by on each repeat

filters_before_mutation

By default, filters are ran after mutation - set this to true if filters should be ran on the un-mutated data. (defaults to false)

args:
  filters_before_mutation: true

disable_antigrief_check

By default, the antigrief plugins on your server are checked. Set this to true to disable that. (defaults to false)

args:
  disable_antigrief_check: true

price

The price required to use or activate this effect.

This supports all known prices: supports money, items, points, second currencies, etc. Read more about the system here: Prices

Looks like this in config:

args:
  price:
    value: 100 * %player_y%
    type: crystals
    display: "&b%value% Crystals ❖"

weight

The weight (chance) of this effect firing if the chain is ran randomly.

Chance is calculated as <weight of element> / <sum of all weights>

args:
  weight: 10

run_order

The order the effect should run in. This can be start, early, normal, late, or end.

Effects have default run orders (used to make effects work together properly), but this option allows for overriding them, for example to make add_damage (defaults to late) run before damage_multiplier (defaults to normal).

args:
  run-order: early

custom_<id>

Use a custom effect argument.

args:
  custom_<id>:
    <arg 1>: <value>
    <arg 2>: <value>
    ... etc

Placeholders

Any numeric value (integer, decimal) can be a mathematical expression involving placeholders!

For example, you can specify the chance to be dependent on your y level: as in chance: 100 - %player_y% - permanent effects will evaluate the expression on activation, and triggered effects will evaluate it on each trigger. Make sure you only use placeholders with numeric values, as you will get weird behaviour otherwise.

If the victim is a player, you can supply any placeholder prefixed with victim_ (e.g. %victim_player_y%) as well.

There are also extra placeholders passed in that you can use:

Placeholder	Value	Aliases
%trigger_value%	The value passed by the trigger (e.g. the amount of damage dealt; see here).	%triggervalue%, %trigger%, %value%, %tv%, %v%, %t%
%player%	The player's name
%player_uuid%	The player's UUID
%victim_health%	The victim's health
%victim_max_health%	The victim's max health
%distance%	The distance between the player and the victim
%victim_level%	The victim's level (Requires LevelledMobs)
%hits%	The amount of times the player has hit the victim
%text%	The message text from the trigger, for example a chat message	%string%, %message%
%location_x%	The X coordinate of the location	%loc_x%, %x%
%location_y%	The Y coordinate of the location	%loc_y%, %y%
%location_z%	The Z coordinate of the location	%loc_z%, %z%
%location_block_x%	The X coordinate of the block location	%loc_b_x%, %block_x%, %bx%
%location_block_y%	The Y coordinate of the block location	%loc_b_y%, %block_y%, %by%
%location_block_z%	The Z coordinate of the block location	%loc_b_z%, %block_z%, %bz%
%location_world%	The world name of the location	%loc_w%, %world%

Load Weight

All configs are loaded alphabetically by default. However, if you have a config that depends on another one, for example an EcoItems item that's crafted with another EcoItems item, you can add load-weight: <weight>. All configs have a default load weight of 100, and it's loaded in ascending order, so a config with a load weight of 10 is loaded before a load weight of 20.