Skip to main content

๐Ÿช‡ Events

Introductionโ€‹

The events section determines which item/furniture/block will execute predefined behaviors during specific events. Under the events section, you need to specify an event trigger, such as "right_click" for a right-click action. Below the event trigger, you must pass a list of actions with their corresponding types. For example, command executes a specific command.

# format 1
events:
  right_click:
    - type: command
      command: say 1
      conditions:
        - type: permission
          permission: "craftengine.admin"
    - type: command
      command: say 2
      conditions: []
# format 2
events:
  - on: right_click
    functions:
      - type: command
        command: say 1
        conditions:
          - type: permission
            permission: "craftengine.admin"
      - type: command
        command: say 2
        conditions: []

๐Ÿงจ Event Triggersโ€‹

itemsโ€‹

  • break
  • right_click
  • left_click
  • consume
  • pick_up

blocksโ€‹

  • break
  • place
  • right_click
  • left_click
  • step

Furnitureโ€‹

  • break
  • place
  • right_click
caution

Please note that the corresponding events should be placed in the appropriate configuration area. For example, if you want to execute a command when interacting with a piece of furniture, the correct approach is to place the events under the furniture section, not under your item section.

items:
  default:bench:
    events: # โŒ๏ธ
      right_click:
        - type: command
    behavior:
      type: furniture_item
      furniture:
        events: # โœ…๏ธ
          right_click:
            - type: command

๐Ÿ”ง 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>
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

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

# The following arguments are only effective
# when the particles are of a certain type.

# item
item: default:chinese_lantern

# block/falling_dust/dust_pillar/block_crumble/block_marker
block-state: default:plam_log[axis=y]

# charge
charge: 1.5

# shriek
shriek: 1

# dust
color: 255,255,255
scale: 1.0

# dust_color_transition
from: 255,255,255
to: 0,0,0
scale: 4.0

# vibration
target-x: 0
target-y: 1
target-z: 0
arrival-time: 10

# trail
target-x: 0
target-y: 1
target-z: 0
duration: 10

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 particle is spawned by beacon
particles: 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

mythic_mobs_skillโ€‹

Cast a mythic mobs skill

type: mythic_mobs_skill
skill: skill_id # required; string
power: 1.0 # optional; number; default: 1.0

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>
anchor-type: ground # optional; enum[ground,ceiling,wall]
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>
anchor-type: ground # optional; enum[ground,ceiling,wall]
drop-loot: true # default: true
play-sound: true # default: true

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

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
info

More functions are coming...