Skip to main content

🔧 Functions

cancel_event​

Cancel the original event.

type: cancel_event

run​

Run a list of functions in order. It's useful for functions that share the same conditions.

type: run
delay: 0 # optional; number; default: 0
functions: # required; maplist
  - type: command
  - type: message

command​

Run a command as a player, console or event.

type: command
command: "say hello <arg:player.name>" # required; stringlist/string
target: "self" # optional; enum[all, self]/player selector; default: self
# Execute the command as a player.
as_player: false # optional; boolean; default: false
# Run as OP (Not Recommended). This is a potential security risk. For safety, run the command from the console.
as_op: false # optional; boolean; default: false
# Some custom command plugins are event-based and may require this option to execute custom commands.
as_event: false # optional; boolean; default: false

message​

Send a message/system actionbar message

type: message
message: "Hello <papi:player_name>" # required; string list/string
target: "self" # optional; enum[all, self]/player selector
overlay: false # optional; default: false; false = chat box / true = actionbar

actionBar​

Send an actionbar

type: actionbar
actionbar: "This is an action bar"  # required; string
target: "self" # optional; enum[all, self]/player selector; default: self

Title​

Send a title

type: title
title: "<red>Title</red>"  # required; string
subtitle: "<Yellow>Subtitle</yellow>" # required; string
fade_in: 20 # optional; number; default: 10
stay: 10 # optional; number; default: 20
fade_out: 10 # optional; number; default: 5

open_window​

Open a gui window

type: open_window #
gui_type: anvil # required; enum[anvil, enchantment, grindstone, loom, smithing, crafting, cartography];
title: "Super Anvil"  # optional; string
target: "self" # optional; enum[all, self]/player selector; default: self

break_block​

Break a block

type: break_block
x: <arg:position.x> # 可选; 数字; éģ˜čŽ¤å€ŧ: <arg:position.x>
y: <arg:position.y> # 可选; 数字; éģ˜čŽ¤å€ŧ: <arg:position.y>
z: <arg:position.z> # 可选; 数字; éģ˜čŽ¤å€ŧ: <arg:position.z>

place_block​

Place a block

type: place_block
block_state: "default:chinese_lantern" # required; string
x: <arg:block.block_x> # optional; number; default: <arg:position.x>
y: <arg:block.block_y> # optional; number; default: <arg:position.y>
z: <arg:block.block_z> # optional; number; default: <arg:position.z>

update_block_property​

Update the properties of an existing block

type: update_block_property
properties: # required; key-value pair
  axis: x
  age: 7
x: <arg:block.block_x> # optional; number; default: <arg:position.x>
y: <arg:block.block_y> # optional; number; default: <arg:position.y>
z: <arg:block.block_z> # optional; number; default: <arg:position.z>

transform_block​

Transform the current block into another one, with properties preserved

type: transform_block 
block: default:palm_log # required
properties:             # optional; key-value pair
  property_a: b
x: <arg:block.block_x> # optional; number; default: <arg:position.x>
y: <arg:block.block_y> # optional; number; default: <arg:position.y>
z: <arg:block.block_z> # optional; number; default: <arg:position.z>

drop_loot​

Drop loots based on the give loot table

type: drop_loot
x: <arg:block.block_x> + 0.5 # optional; number; default: <arg:position.x>
y: <arg:block.block_y> + 0.5 # optional; number; default: <arg:position.y>
z: <arg:block.block_z> + 0.5 # optional; number; default: <arg:position.z>
to_inventory: false
loot:
  pools: ...

update_interaction_tick​

Update the tick when the last interaction ends

type: update_interaction_tick

set_count​

Set the count of the current item in this event

type: set_count
add: true # default: false
count: -1 # required; number
target: "self" # optional; enum[all, self]/player selector

set_food​

Set the food level (0~20) of the player

type: set_food
add: true # optional; boolean; default: false
food: 4 # required; number
target: "self" # optional; enum[all, self]/player selector

set_saturation​

Set the saturation(0~10) of the player

type: set_saturation
add: true # optional; boolean; default: false
saturation: 2.5 # required; number
target: "self" # optional; enum[all, self]/player selector

swing_hand​

Swing the hand involved in this event or the hand specified in config

type: swing_hand
hand: main_hand # optional; enum[main_hand, off_hand]; leave it empty to swing the hand in this context

particle​

Spawn a particle, For specific parameters, see ✨ Particle Effects

type: particle
particle: minecraft:end_rod # required; string
x: "<arg:position.x>" # optional; number; default: <arg:position.x>
y: "<arg:position.y>" # optional; number; default: <arg:position.y>
z: "<arg:position.z>" # optional; number; default: <arg:position.z>
count: 5 # optional; number; default: 1
offset_x: 0.3 # optional; number; default: 0
offset_y: 0.3 # optional; number; default: 0
offset_z: 0.3 # optional; number; default: 0
speed: 0 # optional; number; default: 0

potion_effect​

Add a potion effect

type: potion_effect
potion_effect: minecraft:blindness # required; string
duration: 20  # optional; number; default: 20
amplifier: 0   # optional; number; default: 0
ambient: false # optional; boolean; if the effect is given by beacon
particles: true  # optional; boolean
show_icon: true  # optional; boolean

remove_potion_effect​

Remove a potion effect

type: remove_potion_effect
potion_effect: minecraft:blindness # optional if 'all' is true; boolean
all: false  # optional; boolean; default: false

leveler_exp​

Add skill/job experience

type: leveler_exp
plugin: AuraSkills  # required; string
leveler: fishing  # required; string; the job/skill id
count: 10  # required; number

set_cooldown​

Set cooldown for player

type: set_cooldown
time: 1m30s
id: my_cooldown_id # required; string
add: false # optional; boolean; default: false (Whether to accumulate cooldown time)

remove_cooldown​

Remove cooldown for player

type: remove_cooldown
id: my_cooldown_id  # optional if 'all' is true; string
all: false  # optional; boolean; default: false

play_sound​

Play a sound

type: play_sound
sound: minecraft:xxxx.xxx
x: <arg:position.x> # optional if 'target' is specified; number
y: <arg:position.y> # optional if 'target' is specified; number
z: <arg:position.z> # optional if 'target' is specified; number
target: "self" # optional; enum[all, self]/player selector
pitch: 1 # optional; number; default: 1
volume: 1 # optional; number; default: 1
source: master # optional; enum[music, master, record, weather, block, hostile, neutral, player, ambient, voice, ui]; default: master

cast_mythic_skill​

Cast a mythic mobs skill

type: cast_mythic_skill
skill: skill_id # required; string
power: 1.0 # optional; number; default: 1.0
parameters: # optional; MythicMobs skill parameters, available as <skill.parameter_name>
  damage: 10
  element: "<arg:element>"
variables: # optional; skill-scoped MythicMobs variables, available as <skill.var.variable_name>
  damage: 10 # scalar values infer INTEGER, FLOAT, DOUBLE, or STRING
  element: "<arg:element>"
  multiplier: # use the expanded form to specify a type
    type: double
    value: "<arg:multiplier>"

spawn_furniture​

Spawn a furniture

type: spawn_furniture
furniture_id: "default:bench" # required; string
x: <arg:position.x> # optional; number; default: <arg:position.x>
y: <arg:position.y> # optional; number; default: <arg:position.y>
z: <arg:position.z> # optional; number; default: <arg:position.z>
pitch: <arg:position.pitch> # optional; number; default: <arg:position.pitch>
yaw: <arg:position.yaw> # optional; number; default: <arg:position.yaw>
variant: ground # optional;
play_sound: true # optional; boolean; default: true

remove_furniture​

Remove a furniture

type: remove_furniture
drop_loot: true # optional; boolean; default: true
play_sound: true # optional; boolean; default: true

replace_furniture​

Replace a furniture

type: replace_furniture
furniture_id: "default:bench"
x: <arg:furniture.x> # required; number; default: <arg:furniture.x>
y: <arg:furniture.y> # required; number; default: <arg:furniture.y>
z: <arg:furniture.z> # required; number; default: <arg:furniture.z>
pitch: <arg:furniture.pitch> # required; number; default: <arg:furniture.pitch>
yaw: <arg:furniture.yaw> # required; number; default: <arg:furniture.yaw>
variant: ground # optional; string
drop_loot: true # default: true
play_sound: true # default: true

rotate_furniture​

Rotate a furniture. Sometimes furniture cannot be rotated due to collision shape, at which point the on_failure event will be triggered.

type: rotate_furniture
degree: 90
on_success: [] # functions
on_failure: [] # functions

teleport​

Teleport to a certain location

type: teleport
x: <arg:position.x> # required; number
y: 100 # required; number
z: <arg:position.z> + 5 # required; number
pitch: <arg:player.pitch> # optional; default: 0
yaw: <arg:player.yaw> # optional; default: 0
world: world # optional; string

toast​

Send a toast

type: toast
toast: This is a toast # required; string
advancement_type: goal # optional; enum[goal,task,challenge]; default: goal
icon: minecraft:stone # required; string

damage​

Damage the target

type: damage
target: self # optional; enum[all, self]/player selector; default: self
amount: 1.0 # optional; number; default: 1.0
damage_type: generic # optional; string; default: generic

set_variable​

Set a variable, use <arg:var_[name]> to access it (replacing [name] with the actual variable name)

type: set_variable
name: my_variable # required; string
number: 1.0 # optional; number
as_int: false # optional; boolean; default: false
text: "hello" # optional; string

merchant_trade​

Create a custom villager trading shop

type: merchant_trade
title: "Custom Merchant"
offers:
  - cost_1:
      item: iron_pickaxe
      # optional custom component predicates
      components:  
        minecraft:enchantments:
          minecraft:unbreaking: 1
    # cost_2 is optional
    cost_2:
      item: cobblestone
      # optional count
      count: 8
    result: 
      item: default:topaz
      count: 4
  # add more trade offers
  - cost_1: stone
    result: default:topaz
    # optional
    experience: 3

remove_entity​

Remove the entity in this context

type: remove_entity

if_else​

Run the first function that meets the specified conditions.

type: if_else
rules:
  - conditions:
      - type: permission
        permission: group.admin
    functions:
      - type: command
        command: say hello admin
  - conditions:
      - type: permission
        permission: group.vip
    functions:
      - type: command
        command: say hello vip
  - functions:
      - type: command
        command: say hello player

when​

Evaluate a source value and executes the functions of the first matching case. It's similar to a switch-case statement in programming languages.

type: when
source: <papi:player_world>
cases:
  - when: "world"
    functions: 
      - type: message
        message: "You are in the overworld."
  - when: 
      - "world_nether"
      - "world_the_end"
    functions: 
      - type: message
        message: "You are in a dangerous dimension!"
# optional
fallback:
  - type: message
    message: "You are in an unknown world."

damage_item​

Consume the durability of the item currently held by the player in the current context.

type: damage_item
amount: 1 # optional; number; default: 1
slot: mainhand # optional; enum[mainhand, offhand, feet, legs, chest, head]

cycle_block_property​

Cycle the value of a block property

type: cycle_block_property
property: axis # required; string
inverse: <arg:player.is_sneaking> # optional; number; default: <arg:player.is_sneaking>
x: <arg:block.block_x> # optional; number; default: <arg:position.x>
y: <arg:block.block_y> # optional; number; default: <arg:position.y>
z: <arg:block.block_z> # optional; number; default: <arg:position.z>

You can also define a custom cycle sequence with specific rules.

type: cycle_block_property
property: facing # required; string
x: <arg:block.block_x> # optional; number; default: <arg:position.x>
y: <arg:block.block_y> # optional; number; default: <arg:position.y>
z: <arg:block.block_z> # optional; number; default: <arg:position.z>
rules:
  north: east
  east: south
  south: west
  west: north

set_exp​

Set the experience point of the player

type: set_exp
count: 1 # required; number
add: true # optional; boolean; default: false
target: "self" # optional; enum[all, self]/player selector; default: self

set_level​

Set the experience level of the player

type: set_level
count: 1 # required; number
add: true # optional; boolean; default: false
target: "self" # optional; enum[all, self]/player selector; default: self

play_totem_animation​

Play the totem animation

type: play_totem_animation
item: "default:topaz" # required; string
sound: minecraft:entity.player.levelup # optional; string
pitch: 1 # optional; number; default: 1
volume: 1 # optional; number; default: 1
silent: false # optional; boolean; default: false
target: "self" # optional; enum[all, self]/player selector; default: self

close_inventory​

Close the current inventory

type: close_inventory
target: "self" # optional; enum[all, self]/player selector; default: self

clear_item​

Clear items from the player's inventory

type: clear_item
id: "default:topaz" # required; string
count: 1 # optional; number; default: 1

heal​

Heal the player

type: heal
amount: 1.0 # optional; number; default: 1.0
target: "self" # optional; enum[all, self]/player selector; default: self

take_money​

Take money from the player (requires Vault and an economy plugin). Nothing happens if the player's balance is insufficient.

type: take_money
amount: 100 # required; number/expression
target: "self" # optional; enum[all, self]/player selector; default: self

give_money​

Give money to the player (requires Vault and an economy plugin)

type: give_money
amount: 100 # required; number/expression
target: "self" # optional; enum[all, self]/player selector; default: self

spawn_mythic_mob​

Spawn a mythic mob

type: spawn_mythic_mob
mob: "test_mob" # required; string
level: 1.0 # optional; number; default: 1.0
world: "world" # optional; string
x: "<arg:position.x>" # optional; number; default: <arg:position.x>
y: "<arg:position.y>" # optional; number; default: <arg:position.y>
z: "<arg:position.z>" # optional; number; default: <arg:position.z>
pitch: "<arg:position.pitch>" # optional; number; default: <arg:position.pitch>
yaw: "<arg:position.yaw>" # optional; number; default: <arg:position.yaw>

set_furniture_variant​

Sets the variant of a furniture

type: set_furniture_variant
variant: a_variant # required; string

set_item_cooldown (1.21.2+)​

Sets the cooldown for a specific item for the player

type: set_item_cooldown
id: "minecraft:ender_pearl" # required; string; cooldown group
time: "5s"                  # required; string; supports unit combinations: t(tick), s(second), m(minute), h(hour), d(day), w(week)
add: false                  # optional; boolean; default: false

transfer​

Transfer a player to another server. Supports both proxy plugin messaging (BungeeCord / Velocity) and Minecraft native transfer.

# Proxy plugin message — by server name (BungeeCord / Velocity)
type: transfer
server: "lobby" # required if host not set; string
# Direct transfer — by host + port
type: transfer
host: "lobby.example.com" # required if server not set; string
port: 25566               # optional; number; default: 25565

js​

Invokes a JavaScript function. See 📜 Scripting for the full scripting guide.

type: js
script: "mypack:combo"      # required; string; script id (<namespace>:<path without .js>)
function: "onRightClick"   # required; string; the function to invoke
# args - optional; list or map
# List form: injected as the `args` binding
# args: [ "a", "b" ]
# Map form: each entry is injected as a binding of the same name
args:
  combo: "combo_a"
  times: 3
info

More functions are coming...