Functions (in progress..)

A function uses conditions and actions to execute custom logic in YAML format.

Simple

A simple function is used to execute one or more actions (do).

function:
  do: giveItem diamond

# Or with multiple actions
function:
  do:
    - giveItem diamond
    - chatMessage <Hello, have a diamond>

Conditional

A conditional function checks one or more conditions (if) and executes actions depending on whether they are met (do) or not (else).

function:
  if:
    - hasPermission best.out.of.ten
    - onlinePlayers 1-10

  do: 
    - chatMessage <Congrats you are the best player>

  else: 
    - chatMessage <Sorry you suck>

Negative Conditional

A negative conditional function checks one or more conditions (if-not) and executes actions depending on whether they are met (else) or not (do).

function:
  if-not: hasPermission best.player.ever

  do: 
    - chatMessage <Sorry you suck>

  else: 
    - chatMessage <You are the best player ever!>

Disjunctive Conditional

Check if any conditions are met using if-any.

function:
  if-any:
    - hasPermission best.player.ever
    - hasPermission worst.player.ever
  
  do: chatMessage <You are either the best or the worst player ever!>

Multiple

You can define a list of functions to be executed in sequence. The stop action can be used to prevent any remaining functions in the list from running.

on-break: 
  - if-not: hasPermission orestack.generator.harvest
    do:
      - chatMessage <&4You have no permission to mine this generator>
      - cancelEvent
      - stop

  - if-not: toolIsSimilar IRON_PICKAXE
    do:
      - chatMessage <&4You need an iron pickaxe to mine this generator>
      - cancelEvent
      - stop

  - chance: 0.5
    do: dropItemAtBlock dirt

Function Options

You can add these options to any function for additional behavior.

repetitions | loops: Run the function a specific number of times.
- Value: INTEGER
delay: Delay the execution of the function.
- Value: INTEGER (in ticks, 20 ticks = 1 second)
chance: Set a chance for the function to execute.
- Value: PERCENTAGE (0.0 - 1.0)

Conditions

Server Conditions

Chance

Is met based on probability, value must range from 0.0 (0%) to 1.0 (100%)

if: chance 0.1

Online Players

Check the number of players currently online. You can specify an exact number a range, or multi.

if: onlinePlayers: 10

if: onlinePlayers: 1-10

if: onlinePlayers: 1;3;5

Event Conditions

Click Type Equals

Checks the click type used by the player to interact with a block

if: clickTypeEquals left_click

if: clickTypeEquals right_click, physical

Player Conditions

Has Permission

Verifies if a player has a specific permission node.

if: hasPermission example.permission.node

Has Flag

Checks if a player has a particular flag assigned to them.

if: hasFlag example_flag

Has Exp

Checks a player's current experience points. You can use an exact value, range or multi.

if: hasExp 500

if: hasExp 0-500

if: hasExp 100;250;500

Has Exp Level

Checks a player's current experience level. This also supports an exact value, range or multi.

if: hasExpLevel 100

Has Item

Confirms if a player has a specific item in their inventory. You can define the item by its material or an item from the /items/ folder, and specify a quantity.

if: hasItem diamond:3

if: hasItem item_name:3

Has Played Before

A simple check to see if the player has previously joined the server.

if: hasPlayedBefore

hasFreeSlot

Check if the player has an empty slot in it's inventory

Is Flying

Detects if the player is currently flying.

if: isFlying

Is Sneaking

Detects if the player is currently sneaking.

if: isSneaking

Tool Equals (coming soon)

Checks if the player is holding a specific item. Matches item amount.

Must match: type, amount, name, lore, enchants, etc..

Tool Is Similar

Checks if the player is holding a specific item. Ignores item amount.

Must match: type, name, lore, enchants, etc..

if: toolIsSimilar iron_pickaxe

# Check for multiple items
if: toolIsSimilar iron_pickaxe, item_name

Tool Type Equals

Checks if the player is holding a specific item type. Ignores everything else.

if: toolTypeEquals diamond_axe

if: toolTypeEquals stone_axe, iron_axe, diamond_axe

Tool Name Equals

Checks if the player's held tool has a specific name. Ignores color codes.

# Use <> if value contains one or more spaces
if: toolNameEquals <Legendary Pickaxe>

Tool Lore Line Equals

Checks if the player's held tool has a lore line with a specific value. Ignores color codes.

if: toolLoreLineEquals <This is the first lore line> line=1

Tool Lore Equals

Checks if the player's held tool lore matches these values. Ignores color codes.

if: toolLoreEquals <This is the first line>, <This is the second line>, <This is the third line>

Tool Has Enchant

Checks if the player's held tool has a specific enchantment and level.

if: toolHasEnchant silk_touch level=1

Tool Has Custom Model

Checks if the player's held tool has a specific custom model data.

if: toolHasCustomModel 100007

Placeholder Equals

Compares a placeholder's value to a specific string or amount (fixed, ranged, multi).

if: placeholderEquals joshua id=%player_name% ignoreCase=true

if: placeholderEquals 10 id=%player_health%

if: placeholderEquals 10-20 id=%player_health%

if: placeholderEquals 10;15;20 id=%player_health%

Has Money

Checks a player's current money balance. Requires vault. Supports amount (fixed, ranged, multi)

if: hasMoney 100

if: hasMoney 100-1000

if: hasMoney 100;1000;10000

Actions

Server Actions

Broadcast

Sends a chat message to all players on the server. Supports placeholders and color codes.

do: broadcast <This is a broadcast message>

Lightning

Strikes lightning at a specific coordinate in a given world.

Optional: world, doDamage

do: lightning world=world_name x=0 y=0 z=0 doDamage=true

Console Command

Runs a command from the server console.

do: consoleCommand <say Hello World!>

Drop Item

Drops a specific item at a given coordinate.

Optional: world

do: dropItem dirt world=world_name x=0 y=0 z=0

Drop Exp

Drops specific exp at the given coordinate. Supports amount (fixed, ranged, multi).

Optional: world, orbs

do: dropExp 100 orbs=100 world=world_name x=0 y=0 z=0

do: dropExp 10-100 x=0 y=0 z=0

do: dropExp 50;100 orbs=1-10 x=0 y=0 z=0

Spawn Particle

Spawns a particle effect at a specific coordinate.

Optional: world

do: spawnParticle particle_name world=world_name x=0 y=0 z=0

Play Sound

Plays a sound at a specific coordinate.

Optional: world

do: playSound sound_name world=world_name x=0 y=0 z=0

Function Actions

Stop

Ends function execution completely when called from anywhere.

function:
  do:
    - stop
    - chatMessage <This message will NOT be sent!>

Even when used inside a global function:

# Global Function
giveDiamondIfFirstJoin:
  if: hasPlayedBefore
  do:
    - chatMessage <This is the first time playing huh? Have a diamond!>
    - giveItem diamond 
    - stop

on-break:
  - giveDiamondIfFirstJoin
  - do: chatMessage <This message will NOT be sent!>

Return

Ends current function execution. It will only have effect on the function it is used in.

function:
  do:
    - return
    - chatMessage <This message will NOT be sent!>

When used inside a global function:

# Global Function
giveDiamondIfFirstJoin:
  if: hasPlayedBefore
  do:
    - chatMessage <This is the first time playing huh? Have a diamond!>
    - giveItem diamond 
    - return

on-break:
  - giveDiamondIfFirstJoin
  - do: chatMessage <This message will be sent!>

Goto

Go to a specific line in a multi function. It is kind of pointless and I discourage you from using it.

DANGEROUS: if used improperly it will cause a StackOverflowError and crash your server.

function:
  - if-not: hasPermission example.permission
    do: goto 5
  - if-not: hasMoney 1000
    do: goto 5
  - if-not: hasExpLevel 100
    do: goto 5
  - do: chatMessage <&aYou met all requirements.>
  - do: chatMessage <&4You are missing some requirements.>

Event Actions

Cancel Event

Stops the event that triggered the function from continuing. For example, it could prevent a block from breaking.

Set Cancelled

Manually sets whether the event is cancelled (true or false).

Block Actions

Strike Block

Creates a lightning effect on the block that was interacted with.

Drop Item at Block

Drops an item directly on the block.

Spawn Particle at Block

Spawns a particle effect on the block.

Play Sound at Block

Plays a sound directly on the block.

Generator Actions

Next Stage

Advances the generator to its next defined stage.

Previous Stage

Reverts the generator to its previous stage.

Set Stage

Sets the generator to a specific stage number.

Player Actions

Drop Item at Player

Drops an item at the player's location.

Spawn Particle at Player

Spawns a particle effect on the player.

Play Sound at Player

Plays a sound for the player.

Give Exp

Gives a specific amount of experience points to the player.

Give Flag

Assigns a flag to the player.

Give Item

Gives a specific item to the player.

Give Money

Gives a specific amount of money to the player.

Take Exp

Removes a specific amount of experience points from the player.

Take Flag

Removes a flag from the player.

Take Item

Removes a specific item from the player's inventory.

Take Money

Removes a specific amount of money from the player.

Set Exp

Sets the player's experience points to a specific value.

Heal

Restores a specific amount of health to the player.

Damage

Deals a specific amount of damage to the player.

Command

Runs a command as the player.

Chat Message

Sends a chat message to the player.

Message

Sends a predefined message to the player.

Strike Player

Creates a lightning effect on the player.

Set Flight

Enables or disables flight for the player.

Teleport

Teleports the player to a specific coordinate and rotation.

Open Ender Chest

Opens the player's ender chest.