iPlugin | Event System

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 health

Conditional 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 consume

Teleport 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!'

Event System

On this page