NightExpress's Plugins Wiki

Custom Actions Engine

Allows you to create custom effects and actions on item usage and in other cases.

Example Format:

actions:
  # Action Name, must be unique
  example:
  # Defines the targets for 'action-executors'
    target-selectors:
      # Target selector name. Used in 'action-executors' to define the action target.
      any:
      - '[RADIUS] ~distance: 20; ~allow-self: false; ~entity-type: pig;'
      self:
      - '[SELF]'
    # Defines custom conditions for 'action-executors'
    conditions:
      # Conditions list
      # For each condition you can provide 'message' parameter to send custom message for each condition in case of failure.
      list:
      - '[WORLD_TIME] ~amount: >12000;'
      # Here you can provide Action Name to switch to another actions list in case of conditions failure.
      actions-on-fail: fail
    # Executes the specified actions with custom parameters.
    action-executors:
    - '[COMMAND_CONSOLE] ~message: smite %target%; ~target: any;'
    - '[PROJECTILE] ~name: SHULKER_BULLET; ~target: any; ~speed: 3.5;'
    - '[PARTICLE_LINE] ~offset: 0.1,0,0.1; ~speed: 0; ~name: FLAME; ~target: any; ~amount: 50;'
    - '[POTION] ~name: JUMP; ~amount: 2; ~duration: 200; ~target: any;'
    - '[BURN] ~duration: 0; ~target: any;'
    - '[SOUND] ~name: ENTITY_WOLF_AMBIENT; ~target: any;'
  
  # These actions will be executed if conditions of actions above are failed,
  # because we put 'fail' name in 'actions-on-fail'.
  fail:
    target-selectors:
      self:
      - '[SELF]'
    # You can even provide more conditions here, but we don't need it now.
    conditions: {}
    action-executors:
    - '[MESSAGE] ~message: Conditions failed! Jumped to another actions.; ~target: self;'


Target Selectors

Defines the targets for action executors. You can define as many as you want.


Target Selector Format:

Every target parameter name MUST starts with '~' and ends with ':'

Parameter value MUST ends with ';'

target-selectors:
  # Custom target selector name. Used in action executor's target parameter.
  any:
  - '[RADIUS] ~distance: 20; ~allow-self: true; ~entity-type: pig;'
  self:
   - '[SELF]'


Available Target Selectors:

Name Prefix Description Parameters
RED = Required
Usage Example
From Sight [FROM_SIGHT] Selects the target from executor's sight.
  • Distance
  • Allow Self
  • Attackable
  • Entity Type
  • Entity Health
[FROM_SIGHT] ~distance: 25; ~attackable: true; ~allow-self: false; ~entity-type: zombie;
Radius [RADIUS] Selects the target within specified radius from executor.
  • Distance
  • Allow Self
  • Attackable
  • Entity Type
  • Entity Health
[RADIUS] ~distance: 5; ~attackable: true; ~allow-self: false;
Self [SELF] Selects the executor as a target.
  • Entity Health
[SELF] ~entity-health: >50%; ~party-member: false;

Condition Validators

Defines custom conditions before the action-executors will process.

Also: In some plugin configs you can use conditions out of the total actions, in this case condition target parameter is not needed.

Condition Format:

Every condition parameter name MUST starts with '~' and ends with ':'

Parameter value MUST ends with ';'

conditions:
  list:
  - '[WORLD_TIME] ~amount: >12000; ~message: It must be night!;'
  actions-on-fail: another


Available Conditions:

Name Prefix Description Parameters
RED = Required
Usage Example
Permission [PERMISSION] Requires the target to (not) have specified permission. You can provide negative permission to reverse this condition effect.
  • Target
  • Name
  • Message
[PERMISSION] ~name: -core.actions.test; ~message: You must have not permission!; ~target: self;
[PERMISSION] ~name: core.actions.test; ~message: You must have permission!; ~target: self;
Vault Balance [VAULT_BALANCE] Requires the target to have specified money amount on balance.
  • Target
  • Amount
  • Message
[VAULT_BALANCE] ~amount: =100; ~message: You must have $100!; ~target: self;
[VAULT_BALANCE] ~amount: <100; ~message: You must have < $100!; ~target: self;
[VAULT_BALANCE] ~amount: >100; ~message: You must have > $100!; ~target: self;
World Time [WORLD_TIME] Requires the target's world time to be in specified range.
  • Target
  • Amount
  • Message
[WORLD_TIME] ~amount: >12000; ~message: It must be night!;

Action Executors

Defines the action type and parameters.

Action Executor Format:

Every action parameter name MUST starts with '~' and ends with ':'

Parameter value MUST ends with ';'

action-executors:
- '[PREFIX] ~param1: value; ~param2: value text;'

action-executors:
- '[POTION] ~name: JUMP; ~amount: 2; ~duration: 200; ~target: any;' # Adds Jump II potion effect for 10 seconds.


Available Action Executors:

Name Prefix Description Parameters
RED = Required
Usage Example
Action Bar [ACTION_BAR] Sends message to target's action bar.
  • Delay
  • Target
  • Message
[ACTION_BAR] ~message: &aHello, %executor%!; ~target: self;
Broadcast [BROADCAST] Broadcasts the message.
  • Delay
  • Message
[BROADCAST] ~message: &aHello everyone!;
Burn [BURN] Burns the target.
  • Delay
  • Target
  • Duration
[BURN] ~duration: 100; ~target: pigs;
Command Player [COMMAND_PLAYER] Executes a command by action executor.
  • Delay
  • Target
  • Message
[COMMAND_PLAYER] ~message: smite %target%; ~target: players;
Command Console [COMMAND_CONSOLE] Executes a command by console.
  • Delay
  • Target
  • Message
[COMMAND_CONSOLE] ~message: smite %target%; ~target: players;
Command Op [COMMAND_OP] Executes a command by action executor as OP.
  • Delay
  • Target
  • Message
[COMMAND_OP] ~message: smite %target%; ~target: players;
Firework [FIREWORK] Launch firework at the target location.
  • Delay
  • Target
[FIREWORK] ~target: self; ~delay: 20;
Hook [HOOK] Hooks target to the executor.
  • Delay
  • Target
[HOOK] ~target: pigs;
Message [MESSAGE] Sends message to target.
  • Delay
  • Target
  • Message
[MESSAGE] ~message: &cYo, %target%; ~target: players;
Lightning [LIGHTNING] Summons lightning at the target location.
  • Delay
  • Target
[LIGHTNING] ~target: pigs;
Go To [GOTO] Jumps to another actions section.
  • Delay
  • Name
[GOTO] ~name: actions-name;
Particle Simple [PARTICLE_SIMPLE] Creates simple particle effect.
  • Delay
  • Target
  • Name
  • Offset
  • Speed
  • Amount
[PARTICLE_SIMPLE] ~name:REDSTONE; ~offset: 0.1,0.1,0.1; ~speed: 0.1; ~amount: 30; ~target: pigs;
Potion [POTION] Adds a potion effect to target.
  • Delay
  • Target
  • Name
  • Duration
  • Amount
Amount = Level
[POTION] ~name:JUMP; ~amount: 2; ~duration: 300; ~target: self;
Progress Bar [PROGRESS_BAR] Displays title progress bar.
  • Delay
  • Target
  • Title
  • SubTitle
  • Duration
  • Color Empty
  • Color Filled
SubTitle = Bar Symbol
[PROGRESS_BAR] ~title: &cBar; ~subtitle: •; ~color-empty: &7; ~color-fill: &c; ~duration: 200; ~target: self;
Projectile [PROJECTILE] Launch projectile to the target.
  • Delay
  • Target
  • Name
  • Speed
Name = EntityType

[PROJECTILE] ~name: ARROW; ~speed: 3.5; ~target: around;
Sound [SOUND] Plays sound to the target.
  • Delay
  • Target
  • Name
[SOUND] ~name: ENTITY_WOLF_AMBIENT; ~target: around;
Teleport [TELEPORT] Teleports target to the specified location.
  • Delay
  • Target
  • Locatinon
[TELEPORT] ~location: world,25,10,25; ~target: self;
[TELEPORT] ~location: %executor.world%,%executor.x%,%executor.y%,%executor.z%; ~target: around;
Throw [THROW] Throws target away from the executor.
  • Delay
  • Target
[THROW] ~target: around; ~delay: 10;
Titles [TITLES] Sends titles to the target.
  • Delay
  • Target
  • Title
  • SubTitle
  • Fade In
  • Stay
  • Fade Out
[TITLES] ~title: &cTitle Text!; ~subtitle: &6SubTitle Text!; ~fadeIn: 10; ~stay: 50; ~fadeOut: 10; ~target: self;
Vault Add [VAULT_ADD] Adds or takes money from target's vault balance.
  • Delay
  • Target
  • Amount
[VAULT_ADD] ~amount: 100; ~target: self;
[VAULT_ADD] ~amount: -100; ~target: self;

Action Parameters


Available Parameters:

Name Flag Destination Description Usage Example
Allow Self allow-self Target Selector Allows/Disallows to select the executor in target selector as a target. False by default. ~allow-self: false; | ~allow-self: true;
Amount amount All Defines the object amount for specified action. Negative values are allowed. ~amount: 10; | ~amount: -5;
Attackable attackable Target Selector Defines if target should be available to receive damage from the executor. This parameter only checks the WorldGuard and Residence flags and if target is a Citizens NPC. If this parameter is not provided, any entity will be selected. ~attackable: false; | ~attackable: true;
Delay delay Action Executor Delay in ticks (20 ticks = 1 second), before the action will be executed. ~delay: 100;
Distance distance All Defines the distance (in blocks) from the executor to target OR distance for specified action. ~distance: 30;
Duration duration Action Executor Defines the action duration in ticks (20 ticks = 1 second). ~duration: 250;
Entity Health entity-health Target Selector, Conditions You can use '>', '<' or '='. You can add '%' to check the current health of max. health. You can use decimal numbers. ~entity-health: 100%;
~entity-health: <25%;
~entity-health >0;
Entity Type entity-type Target Selector, Conditions Defines the entity type for target selector. If no type provided, target selector will select any entity type. You can provide multiple types. ~entity-type: pig;
~entity-type: player,zombie,villager;
Location location Action Executor Defines the location for action.
Placeholders:
  • %executor.world%, %executor.x%, %executor.y%, %executor.z%
  • %target.world%, %target.x%, %target.y%, %target.z%
Target placeholders replaces for the first target in a list.
~location:world,10,20,30;
Message message Action Executor, Conditions Defines the message text.
Placeholders:
  • %executor% - Executor name
  • %target% - Target name.
~message: &aHello there!;
Name name All Defines the object name for specified action. ~name: CLOUD;
Offset offset Action Executor Defines the object offset for specified action. Format: X,Y,Z. ~offset: 0.1,0.1,0.1;
~offset: 0,0,0;
Speed speed Action Executor Defines the object speed for specified action. ~speed: 0.5;
Target target Action Executor, Conditions Defines the target selector for action. You can provide multiple targets. Use target selector names ~target: selector-1;
~target: pigs,cows;
Title title Action Executor Defines the title text.
Placeholders:
  • %executor% - Executor name
  • %target% - Target name.
~title: &lHello, &f%executor%&e!;
SubTitle subtitle Action Executor Defines the subtitle text.
Placeholders:
  • %executor% - Executor name
  • %target% - Target name.
~subtitle: &lHello, &f%executor%&e!;
Fade In fadeIn Action Executor Defines the fade in time (in ticks) for titles. ~fadeIn: 10;
Stay stay Action Executor Defines the stay time (in ticks) for titles. ~stay: 40;
Fade Out fadeOut Action Executor Defines the fade out time (in ticks) for titles. ~fadeOut: 10;
Color Empty color-empty Action Executor Defines the color for unfilled elements of progress bar. ~color-empty: &7;
Color Filled color-fill Action Executor Defines the color for filled elements of progress bar. ~color-fill: &a;
Navigation