Skip to main content

Configuring an Effect Chain

Effect Chains​

What is an Effect Chain?​

Effect chains are groups of effects that can be executed together. This is very useful if you want to create a chance-based effect with several components: chance is calculated independently on each trigger, so without chains, particles and messages could send when the effects don't activate, and vice-versa.

Effects in chains run isolated, so applying a mutator to one effect in the chain will apply it only to that effect - however, you can specify a mutator to the parent effect which will be applied to all effects in the chain. The same works for delays, e.g. if an effect in a chain has a delay of 2, it won't hold up other effects down the chain.

Effect chains are also useful to re-use more complex logic, via custom arguments that you can specify. These work like regular placeholders, and you reference them in your chains with %<id>%, for example %size% if you had a size argument.

Reusable Chains​

One of the ways to create chains is in "chains.yml" in "/plugins/libreforge". This is great if you want to use chains more than once.

Chains created here are universally accessible. You can use them in Enchants, Skills, Jobs or any other effect holders.

You don't need to specify triggers in your chain, these are handled by the run_chain effect (see below).

The Basic Layout​

chains:
  - id: <chain id>
    effects:
      - <effect 1>
      - <effect 2>
      - <effect 3>

Chain Config Example​

  - id: mining_effect
    effects:
      - id: play_sound
        args:
          sound: BLOCK_AMETHYST_CLUSTER_BREAK
          pitch: 0.7
          volume: 10
      - id: spawn_particle
        args:
          particle: soul
          amount: 10
        mutators:
          - id: translate_location
            args:
              add_x: 0.5
              add_y: 0.5
              add_z: 0.5

You can add or remove as many chains as you want. Then, if you want to call a chain, use the run_chain effect, like this:

Calling Your Chain​

id: run_chain
args:
  chain: mining_effect # The ID of the chain
  chance: 50 * (%player_health% / 20) # Example to demonstrate placeholders in config
  cooldown: 2
triggers:
  - mine_block
filters:
  blocks:
    - diamond_ore
    - emerald_ore
    - ancient_debris

Custom arguments can be specified like this:

id: run_chain
args:
  chain: <chain id>
  chain_args:
    strength: %player_y% * 100 # You can put anything you want, doesn't only have to be numbers - you can use strings too!
    ... add whichever arguments you use in your chain

Inline Chains​

If you don't want to re-use chains, or if you prefer having them specified directly under the effect, you can specify effects inline instead.

The Basic Layout​

effects:
  - <effect 1>
  - <effect 2>
  - <effect 3>
triggers:
  - mine_block
args:
  every: 3 # You can use Optional Args here: https://plugins.auxilor.io/effects/configuring-an-effect#optional-arguments

Example Inline Chain​

effects:
  - triggers:
      - mine_block
    filters:
      blocks:
        - diamond_ore
        - emerald_ore
        - ancient_debris
    effects:
      - id: play_sound
        args:
          sound: BLOCK_AMETHYST_CLUSTER_BREAK
          pitch: 0.7
          volume: 10
      - id: spawn_particle
        args:
          particle: soul
          amount: 10
        mutators:
          - id: translate_location
            args:
              add_x: 0.5
              add_y: 0.5
              add_z: 0.5

Inline chains also support custom arguments, just like regular chains.

Run Types​

Effect chains also support several run types:

  • normal: All effects in the chain will be ran, sequentially, one after another
  • cycle: Only one effect will be ran, and it cycles through each effect each time the chain is triggered
  • random: Only one effect will be ran, chosen at random each time the chain is triggered

To specify the run type, add the run-type argument into config:

effects:
  - triggers:
      - alt_click
    effects:
      - <effect 1>
      - <effect 2>
      - <effect 3>
    args:
      run-type: random
      chance: 30
... filters, mutators, etc

This is an alternative way of configuring your effects; you don't specify a top-level effect ID, instead you specify a list of effects to be called. This can be thought of as being more trigger-centric; multiple triggers to multiple effects straight away, no worrying about the underlying chain.