Action System

The action system lets YAML configuration describe what should happen after a business event. It is one of the most frequently used CoreLib features across Forge, Strengthen, Gem, Cooking, Skills, Item, and Attribute.

Basic syntax

Different modules may use different field names, such as action.success, actions, deny_actions, or result.action, but the idea is the same: an action list is executed in order.

An action line consists of control prefixes, an action ID, and key=value arguments:

@chance=25% @delay=20t sendmessage text="<green>Triggered</green>"

Use quoted values whenever a value contains spaces, commands, MiniMessage tags, or YAML-sensitive characters.

action:
  success:
    - 'sendmessage text="<green>Forge success!</green>"'
    - 'playsound sound=minecraft:entity.player.levelup volume=1 pitch=1'
    - 'runcommandasconsole command="say %player_name% completed a forge"'

CoreLib resolves placeholders before executing the action. Built-in context placeholders include %player_name%, %player_uuid%, %player_world%, %player_x%, %player_y%, %player_z%, and %phase%. Business modules may inject additional placeholders.

Parser notes

• Blank lines and lines starting with # are ignored.
• Action IDs are normalized to lower case. Built-in IDs generally do not contain underscores.
• Arguments must be written as key=value; a token without = after the action ID is a syntax error.
• Duplicate arguments in one line are rejected.
• Single and double quotes are both supported. Quoted values support \n, \t, \\, \", and \' escaping.
• createitem, clearitem, dropitem, placeblock, runjs, and usetemplate accept dynamic arguments.

Control prefixes

Control prefixes must appear before the action ID:

Prefix	Meaning
@if=<expression>	Run only when the expression is true.
@chance=<number>	Run by chance. Supports decimals from 0 to 1 and percent values such as 25%.
@delay=<time>	Run after a delay. Supports ticks, t, s, and ms, such as 20, 20t, 1s, 500ms.
@ignore_failure	Continue the following actions even if this action fails.

actions:
  - '@chance=0.1 broadcastmessage text="<gold>%player_name% triggered a rare reward!</gold>"'
  - '@delay=1s sendmessage text="<gray>This message is delayed by one second"'
  - '@if=%player_world%=="world" sendmessage text="You are in the overworld"'
  - '@ignore_failure runcommandasconsole command="papi parse %player_name% %some_placeholder%"'

@if supports boolean literals, numeric truthiness, comparisons, &&, ||, !, and parentheses. String comparisons should be quoted.

Built-in action IDs and parameters

Messages and feedback

Action ID	Parameters	Requires player	Description
sendmessage	required text	Yes	Sends a MiniMessage chat message to the player.
sendtitle	required title; subtitle=""; fade_in=10t; stay=40t; fade_out=10t	Yes	Sends a title. Time values support t/s/ms.
sendactionbar	required text	Yes	Sends an action bar message.
broadcastmessage	required text	No	Broadcasts a MiniMessage message to the server.
playsound	required sound; volume=1; pitch=1	Yes	Plays a Bukkit sound at the player location.
spawnparticle	required particle; count=1; target=player; world; x/y/z; offset_x/y/z=0; extra=0	Only when target=player	Spawns particles at the player or at a configured location.

actions:
  - 'sendmessage text="<green>Reward: <yellow>100 coins</yellow></green>"'
  - 'sendtitle title="<gold>Success</gold>" subtitle="<gray>Level up</gray>" fade_in=5t stay=40t fade_out=10t'
  - 'playsound sound=minecraft:entity.experience_orb.pickup volume=0.8 pitch=1.2'
  - 'spawnparticle particle=happy_villager count=10 offset_x=0.3 offset_y=0.6 offset_z=0.3'

Economy

Action ID	Parameters	Requires player	Description
givemoney	required amount; provider=auto; currency=""	Yes	Adds money to the player.
takemoney	required amount; provider=auto; currency=""	Yes	Takes money from the player.
setmoney	required amount; provider=auto; currency=""	Yes	Sets the player balance.

provider is usually auto, vault, or excellent. currency only matters when the selected economy provider supports currencies.

Temporary items

createitem creates a temporary item in the current action context. senditem can then give it to the player.

Action ID	Parameters	Requires player	Description
createitem	required id; source=""; amount=1; dynamic aliases item, item_source	No	Creates a temporary item from an item source.
senditem	required id; keep=false	Yes	Sends a temporary item to the player. Leftovers are dropped nearby.
clearitem	required slot; source=""; dynamic aliases item, item_source	Yes	Clears a player inventory slot, optionally only when the item source matches.
dropitem	required x/y/z; world=current; source=""; amount=1; dynamic aliases item, item_source	Only for relative coordinates or omitted world	Drops an item source at an exact location.
placeblock	required x/y/z; world=current; source=""; dynamic aliases item, item_source	Only for relative coordinates or omitted world	Places a vanilla, CraftEngine, ItemsAdder, or Nexo block source.

source uses the CoreLib item source shorthand. See Item Sources.

clearitem.slot supports mainhand, offhand, helmet, chestplate, leggings, boots, and inventory indexes 0 to 35 (slot_0, hotbar_0 are also accepted).

dropitem and placeblock coordinates support ~ relative notation when a player context exists. Without a player context, configure world and absolute coordinates.

actions:
  - 'createitem id=reward source=minecraft:diamond amount=3'
  - 'senditem id=reward'
  - 'clearitem slot=mainhand source=minecraft:stick'
  - 'placeblock source=minecraft-stone world=world x=100 y=64 z=-20'
  - 'placeblock source=ce-cutting_board x=~1 y=~ z=~'
  - 'dropitem source=nexo-reward_coin amount=3 x=~ y=~1 z=~'

Player state and teleport

Action ID	Parameters	Requires player	Description
teleport	required x, y, z; world=current; yaw=0; pitch=0	Yes	Teleports the player. Coordinates support ~ relative notation.
heal	required amount	Yes	Heals the player, capped by max health.
damage	required amount	Yes	Reduces player health, not below 0.
sethealth	required amount	Yes	Sets player health, clamped to 0..max health.

actions:
  - 'heal amount=4'
  - 'damage amount=2'
  - 'teleport world=world x=~ y=~1 z=~ yaw=0 pitch=0'

Experience and potion effects

Action ID	Parameters	Requires player	Description
giveexp	required amount; mode=points	Yes	Adds experience points or levels. Use mode=levels for levels.
takeexp	required amount; mode=points	Yes	Removes experience points or levels, not below 0.
setexp	required amount; mode=points	Yes	Sets total experience points or levels.
givepotioneffect	required type, level, duration; ambient=false; particles=true; icon=true	Yes	Adds a potion effect. level=1 maps to Bukkit amplifier 0.
removepotioneffect	required type	Yes	Removes one potion effect.
clearpotioneffects	none	Yes	Clears all active potion effects.

type can be written as speed or minecraft:speed. duration supports t/s/ms.

Commands

Action ID	Parameters	Requires player	Description
runcommandasplayer	required command	Yes	Dispatches a command as the player.
runcommandasop	required command	Yes	Temporarily grants OP, runs the command, then restores the original OP state.
runcommandasconsole	required command	No	Dispatches a command as the console.

A leading / is stripped automatically, but omitting it in config is recommended.

actions:
  - 'runcommandasplayer command="spawn"'
  - 'runcommandasop command="lp user %player_name% permission set example.use true"'
  - 'runcommandasconsole command="say %player_name% completed a task"'

Action templates

Define templates in the CoreLib main config:

action:
  templates:
    reward_common:
      - 'sendmessage text="<green>Reward claimed</green>"'
      - 'playsound sound=minecraft:entity.experience_orb.pickup volume=0.8 pitch=1.2'

Call them with usetemplate:

actions:
  - 'usetemplate name=reward_common'

Parameter	Description
name	Required template ID. Case-insensitive.
with.<key>	Dynamic value injected as %template_<key>% inside the template.

Template nesting is limited to 8 levels.

MythicMobs and JavaScript

Action ID	Parameters	Requires player	Description
castmythicskill	required skill	Yes	Uses the MythicMobs API to make the player cast a skill. Fails gracefully if MythicMobs is unavailable.
runjs	required script; function=main; timeout=default; silent=false; dynamic arg_*	No	Runs a JavaScript file from the CoreLib script repository.

runjs aliases come from config.yml; defaults are runscript and javascript. arg_foo=bar becomes script argument foo=bar.

actions:
  - 'castmythicskill skill=FireballSkill'
  - 'runjs script=examples/hello.js function=main timeout=1000 arg_source=forge arg_amount=3'

See JavaScript for the script API.

Actions registered by other modules

Module	Action IDs	Description
EmakiSkills	castskill	Casts an EmakiSkills skill.
EmakiAttribute	attributedamage, attribute_add, attribute_set, attribute_remove	Attribute damage and attribute mutation actions.
CoreLib script config	aliases of runjs	Defaults: runscript, javascript.

Troubleshooting

Action does not execute

Check whether:

1. The field is actually an action field for the module.
2. YAML indentation is correct.
3. The action ID is spelled correctly and does not contain underscores.
4. @if or @chance skipped the action.
5. The console contains action syntax errors.

Argument parsing fails

Common causes:

• Old space-style syntax such as sendmessage <green>Success; use sendmessage text="<green>Success" instead.
• command or text contains spaces but is not quoted.
• Duplicate argument keys.
• Unclosed quotes.

Economy actions do nothing

Check whether Vault / ExcellentEconomy is installed and detected, whether provider / currency is correct, and whether the player has enough balance for take operations.