🔧 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 on the current execution context. Functions that run later with the same context can read it with <var:name>.

type: set_variable
name: my_variable # required; string
value_type: double # optional; enum[int, double, string]
value: 1.0 # required unless number/text is used; number for int/double, string for string

value_type controls the stored Java value:

Value type	Result	Accepted value
int	Integer; numeric results are floored	Number Format
double	Double	Number Format
string	String	Text; context tags such as <arg:...> and <var:...> are supported

number remains an alias for a numeric value, and text remains an alias for a string value. If value_type is omitted, configurations using number default to double; all other configurations default to string.

Variables belong to the current context. They are not global or persistent, and are available only to later conditions, functions, and text rendering that share that context.

type: run
functions:
  - type: set_variable
    name: reward
    value_type: int
    value: "<arg:player.level> / 5"
  - type: message
    message: "<green>You received <var:reward> coins."

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

discover_recipe

Unlock a recipe for the player. Supports vanilla recipes and custom recipes registered on the server.

type: discover_recipe
recipe: "mypack:custom_recipe" # required; string; recipe ID; alias: id
target: "self" # optional; enum[all, self]/player selector; defaults to the context player

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...