Event System
Add Interactive Functions to Items
Overview
The event system enables your items to respond to player actions, such as right-clicking, attacking enemies, and more. With simple scripts, you can equip items with a variety of functions.
Basic Concepts
What is an Event
An event refers to an interaction between a player and an item, such as:
- Right-clicking an item
- Attacking an enemy with an item
- Consuming an item (e.g., food)
- Dropping an item
Event Scripts
When an event occurs, the system executes pre-written script commands you have defined.
Common Event Types
| Event Name | Trigger Timing | Example Usage |
|---|---|---|
on_right_click | When the item is right-clicked | Activate skills, open menus |
on_left_click | When the item is left-clicked | Quick attacks, switch modes |
on_attack | When an entity is attacked with the item | Extra damage, special effects |
on_consume | When the item is consumed | Restore health, gain buffs |
on_drop | When the item is dropped | Prevent dropping, special prompts |
Script Writing Syntax
Recommended Syntax: Multi-Line Strings
Use YAML's multi-line string syntax (|) to write event scripts for better readability:
magic_wand:
icon: stick
name:
item_name: '&6Magic Wand'
event:
on_right_click: |
tell 'You unleashed magic!'Complex Script Example
healing_potion:
event:
on_consume: |
tell color '&aYou feel refreshed!'
player health to player max healthConditional Judgment and Logic
Using Conditional Statements
premium_sword:
event:
on_right_click: |
if check player level >= 10 then {
tell color '&aUnleashed a powerful attack!'
} else {
tell color '&cInsufficient level! Level 10 required'
}Using Item Data
Reference item data using &variable_name:
fire_sword:
data:
fire_damage: 15
mana_cost: 10
event:
on_attack: |
set a to item data player-mana
set b to item data mana_cost
if check a >= b then {
item data player-mana to math - [ a b ]
item update
tell 'Dealt extra fire damage!'
}Practical Event Examples
Healing Potion
health_potion:
icon: potion
name:
item_name: '&cHealing Potion'
event:
on_consume: |
tell '&aRestored 20 health points!'
player health to math + [ player health 20 ]
item consumeTeleport Scroll
teleport_scroll:
icon: paper
name:
item_name: '&bTeleport Scroll'
event:
on_right_click: |
if check player level >= 5 then {
teleport world 10.0 64.0 10.0
tell '&aTeleport successful!'
item consume
} else {
tell '&cLevel 5 required to use this!'
}Defense Amulet
shield_amulet:
icon: shield
name:
item_name: '&9Defense Amulet'
event:
on_attack: |
if random 0.2 then {
tell color '&bThe amulet protected you!'
cancel
}Script Syntax Comparison
Traditional Array Format (Still Supported)
magic_sword:
event:
on_right_click:
- "tell color '&aUnleashed a magical attack!'"
- "tell color '&cInsufficient mana!'"Recommended Multi-Line String Format
magic_sword:
event:
on_right_click: |
tell color '&aUnleashed a magical attack!'
tell color '&cInsufficient mana!'