How to Make a Custom Action
An action is a single YAML file that runs a set of effects when a trigger fires, optionally gated by conditions. This page takes you from an empty file to a working action and explains each section you can configure.
Quick start
Open the
/actions/folder in your plugin directory. Each.ymlfile here is one action.Copy
_example.ymlto a new file, e.g.coins_on_kill.yml. The file name is the action's ID, so use lowercase letters, numbers, and underscores only.Edit the
effectsandconditionssections to do what you want (see below).Run
/actions reloadin-game or from console.Trigger the action in-game. The chat message confirms the reload:
Reloaded in Xms! Loaded N actions.
Action structure
An action file has three top-level parts.
| Part | What it controls |
|---|---|
| enabled | Whether the action loads at all. |
| effects | What the action does, when it triggers, and what it filters on. |
| conditions | Requirements the player must meet for the effects to run. |
Here is the full _example.yml, which pays players for killing non-player entities at a rate of $0.25 per victim level:
# === enabled: load this action or skip it ===
enabled: true # Set to false to disable without deleting the file
# === effects: what happens, and when ===
effects:
- id: give_money # The effect to run; see the libreforge effects list
args:
amount: "0.25 * %victim_level%" # Effect arguments; placeholders are evaluated as expressions
triggers:
- kill # The event that fires this effect
filters:
not_entities:
- player # Only run for non-player victims
# === conditions: requirements to run at all ===
conditions: [ ] # Empty means no conditions; the action always runs when triggered
Effects
The effects section is the core of the action: it defines what runs, what triggers it, and what it filters or mutates.
effects:
- id: give_money # Effect ID from the libreforge effects list
args:
amount: "0.25 * %victim_level%" # Arguments for that effect
triggers:
- kill # One or more triggers that fire the effect
filters:
not_entities:
- player # Filters that narrow when the effect runs
Conditions
Conditions are requirements the player must meet for the action to run. An empty list means it always runs when triggered.
conditions:
- id: above_health # Condition ID from the libreforge conditions list
args:
health: 10 # This action only runs while the player is above 10 health
Conditions are also what the %actions_<id>_is_met% placeholder reads, so you can reuse an action's conditions in other plugins like EcoShop. See Configuring a Condition for the full option set.
Organising your actions
You can place action files anywhere inside /actions/, including subfolders, to keep large setups tidy. The folder layout has no effect on behaviour; only the file name (the ID) matters. The file _example.yml is never loaded.