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 actions.success, actions, deny_actions, or result.success.actions, 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.

actions:
  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.
bossbarshow	required id, title; progress=1; color=purple; style=solid; flags=""	Yes	Shows or updates a boss bar. Reusing an id updates the existing bar.
bossbarhide	required id	Yes	Hides a boss bar. Pass all to hide every bar.

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 accepts auto, vault, or excellenteconomy. With auto, CoreLib prefers ExcellentEconomy when a currency is given and otherwise falls back to Vault. currency must be set explicitly when using ExcellentEconomy with multiple 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, Nexo, or Oraxen block source.
giveitem	source=""; amount=1	Yes	Gives an item source directly into the player inventory.
setitem	slot=mainhand; source=""; amount=1	Yes	Sets the item in a player inventory slot.
takeitem	source=""; amount=1	Yes	Removes matching items from the player inventory.
repairitem	slot=mainhand; amount=0	Yes	Repairs durability. amount <= 0 repairs fully.
damageitem	slot=mainhand; amount=1; delete_item=false	Yes	Adds durability damage, optionally removing the item when it breaks.
setblock	material=""; block=""; block_data=""; apply_physics=true; world=""; x/y/z	Only for relative coordinates or omitted world	Sets a block. block is an alias of material.
breakblock	drop_items=false; apply_physics=true; world=""; x/y/z	Only for relative coordinates or omitted world	Breaks the block at the given location.
spawnentity	required type; count=1; world=""; x/y/z	Only for relative coordinates or omitted world	Spawns entities at a location.
killentity	type=""; radius=1; limit=1; include_players=false; world=""; x/y/z	Only for relative coordinates or omitted world	Removes entities within a radius.
explosion	power=0; fire=false; break_blocks=false; world=""; x/y/z	Only for relative coordinates or omitted world	Creates an explosion.

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.
feed	amount=20; saturation=0	Yes	Restores food points and saturation.
ignite	duration=5s	Yes	Sets the player on fire.
extinguish	none	Yes	Extinguishes the player.

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.

Loop actions

These three actions are only registered when the loop feature is available (action.loop.enabled in config.yml). They repeatedly execute an action template, subject to the quotas under action.loop.*.

Action ID	Parameters	Requires player	Description
loopsync	required template, times, interval; initial_delay=0t; key=""; mode=replace; stop_if_offline=true; stop_if_dead=false; stop_if_condition=""; stop_on_failure=false	Depends on template	Starts a synchronous repeating action template.
loopasync	Same as loopsync	Depends on template	Starts an async-safe repeating action template.
cancelloop	required key; match=exact; silent=true	No	Cancels running loop tasks by key.

mode accepts replace, refresh, ignore, and allow_duplicate. match accepts exact or prefix.

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.

The script action ID is fixed to runjs. 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.

Listing and running registered actions from commands

Administrators can inspect the current action registry and run one registered action by ID from the server:

/corelib action list
/corelib action run <actionId> key=value ...

The same subcommand is available through /emakicorelib action, /emakicore action, and the plural alias actions. It reuses the emakicorelib.admin permission. Console execution has no player context, so actions that require a player fail through the normal Action validation path. There is intentionally no “run all actions” command to avoid accidental mass execution.

action list shows id, category, source, owner, execution mode, and parameter names. action run passes <actionId> key=value ... to the existing ActionExecutor as one action line, so parameters, quoting, @if, @chance, and @delay follow the same rules as YAML action lines.

Where to find sub-plugin CoreLib actions

CoreLib provides the shared registry and executor. Business plugins may append their own actions when enabled. To avoid turning this CoreLib page into a stale table of every plugin-specific action, this page only documents CoreLib built-in actions.

CoreLib actions registered by sub-plugins are now documented on their own plugin pages:

Source module	Documentation
EmakiAttribute	Attribute CoreLib Actions
EmakiForge	Forge CoreLib Actions
EmakiStrengthen	Strengthen CoreLib Actions
EmakiCooking	Cooking CoreLib Actions
EmakiGem	Gem CoreLib Actions
EmakiLevel	Level CoreLib Actions
EmakiSkills	Skills CoreLib Actions
EmakiItem	Item CoreLib Actions
EmakiCodex	Codex CoreLib Actions
JavaScript extensions	JavaScript

If an action is provided by a business plugin, its parameters, context variables, and execution timing are defined by that plugin’s documentation.

Registering actions from third-party plugins

Third-party developers can depend only on emaki-corelib-api and call EmakiCoreLibApi.registerAction(plugin, source, action) to add custom actions to CoreLib's shared action registry. Use a stable lowercase source id such as myplugin. On plugin disable, call the returned CoreActionRegistration.unregister() handle or use EmakiCoreLibApi.unregisterActions(plugin) to remove all actions owned by that plugin.

A custom action implements CoreAction and declares its id, category, description, parameters, and executionMode. CoreLib reuses the same action-line parser, parameter checks, @if / @chance / @delay control prefixes, debug output, and dispatch scheduler. Read-only discovery is available through EmakiCoreLibApi.actions(), action(id), actionsBySource(source), and actionsByOwner(plugin).

Minimal example:

CoreActionRegistration registration = EmakiCoreLibApi.registerAction(plugin, "myplugin", new CoreAction() {
    @Override
    public String id() {
        return "mycustomaction";
    }

    @Override
    public String category() {
        return "myplugin";
    }

    @Override
    public String description() {
        return "Runs my plugin's custom effect.";
    }

    @Override
    public List<CoreActionParameter> parameters() {
        return List.of(CoreActionParameter.required("value", CoreActionParameterType.STRING, "Custom value"));
    }

    @Override
    public CoreActionResult execute(CoreActionContext context, Map<String, String> arguments) {
        // Run your plugin logic here. Keep the default SYNC mode when using Bukkit main-thread APIs.
        return CoreActionResult.ok();
    }
});

// On plugin disable:
registration.unregister();
// Or: EmakiCoreLibApi.unregisterActions(plugin);

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.