Passive Abilities

Một passive là kỹ năng ẩn gắn vào item (vũ khí, giáp, tay phụ). Khi sự kiện game xảy ra — đánh trúng, tiêu diệt mob, nhận sát thương, phá block, hoặc chết — passive tự kiểm tra điều kiện, tung xúc xắc, rồi kích hoạt một hoặc nhiều action.

Mỗi passive nằm trong một file .yml riêng. Nhiều passive có thể cùng gắn trên một item.

Cách hoạt động

Cấu trúc file

Đặt mỗi passive vào file .yml riêng trong thư mục:

plugins/YourPlugin/Listener/Passives/
  execute_5pct.yml
  speed_on_hit.yml
  kill_drop_gold.yml
  ...

Tên file không quan trọng — plugin dùng key id bên trong file. Reload bằng lệnh /reload hoặc lệnh reload của plugin.

Các key cơ bản

Triggers

Key trigger xác định khi nào passive kích hoạt. Viết hoa toàn bộ.

Conditions (Điều kiện)

Tất cả điều kiện nằm trong mục condition:. Mọi điều kiện phải thỏa mãn — chỉ cần một fail là passive bị bỏ qua cho sự kiện đó.

target-type

Lọc loại thực thể bị tác động.

must-be-crit

Đặt true để chỉ kích hoạt khi đòn đánh là chí mạng.

condition:
  must-be-crit: true

target-hp-percent-below

Chỉ kích hoạt nếu HP hiện tại của victim thấp hơn ngưỡng này (% so với HP tối đa). Hỗ trợ biểu thức.

condition:
  target-hp-percent-below: "20"                   # dưới 20% HP
  target-hp-percent-below: "%player_level% * 0.5" # tăng theo cấp

expressions

Danh sách biểu thức so sánh tùy ý. Tất cả phải đúng.

condition:
  expressions:
    - "%player_level% >= 10"
    - "{damage} > 5.0"
    - "{victim_hp_percent} <= 30"
    - "{actor_hp} > 10"

Toán tử hỗ trợ: >=  <=  ==  !=  >  <

Biểu thức & PAPI

chance, duration-seconds, amount và hầu hết các key số đều chấp nhận biểu thức toán học thay vì số cố định.

chance: "50"                        # cố định 50%
chance: "%player_level% * 2"       # 2% mỗi cấp, tự giới hạn 0–100
chance: "{damage} * 3"             # sát thương càng cao xác suất càng lớn
amount: "%player_level% * 0.5"     # damage scale theo cấp
duration-seconds: "{damage} / 2" # duration tăng theo damage

Chance & Cooldown

Tổng quan Actions

Actions khai báo dưới key actions: dạng danh sách YAML. Mỗi action bắt buộc có type. Hầu hết có key target nhận giá trị SELF hoặc VICTIM.

actions:
  - type: EFFECT
    target: SELF
    effect: SPEED
    seconds: "3"
    level: "2"
  - type: SOUND
    target: SELF
    sound: ENTITY_PLAYER_LEVELUP

DAMAGE

Gây sát thương lên target.

- type: DAMAGE
  target: VICTIM
  amount: "%player_level% * 2"
  damage-type: TRUE

EFFECT

Áp dụng potion effect lên target. Dùng để buff/debuff bằng hệ thống potion vanilla của Minecraft.

- type: EFFECT
  target: SELF
  effect: SPEED
  seconds: "3"
  level: "2"
  particles: false

BUFF_STAT

Buff tạm thời một stat nội bộ của plugin — cộng vào CombatStats ngay lập tức, trừ ngược lại sau duration-seconds giây.

- type: BUFF_STAT
  target: SELF
  stat: critical_damage
  amount: "%player_level% * 0.5"
  duration-seconds: "5"

HEAL

Hồi máu cho target. Nếu percent > 0 thì ưu tiên hơn amount flat.

- type: HEAL
  target: SELF
  percent: "10"   # hồi 10% maxHP

FLAME

Đốt lửa target, gây damage mỗi giây trong suốt thời gian cháy.

- type: FLAME
  target: VICTIM
  damage-per-second: "%player_level% * 1.5"
  duration-seconds: "5"

LAUNCH

Hất văng entity theo vector tự do dựa theo hướng nhìn của reference.

- type: LAUNCH
  target: VICTIM
  forward: "-1.5"  # đẩy lùi
  up: "0.8"

EXPLODE

Tạo vụ nổ tại vị trí target, gây sát thương cho thực thể trong vùng và hiển thị hiệu ứng hạt nhân tùy chỉnh.

- type: EXPLODE
  target: VICTIM
  power: "3.0"
  radius: "5.0"
  amount: "%player_level% * 3"
  damage-type: TRUE
  break-blocks: false
  particle-scale: 2.0

DROP_ITEM

Thả item xuống đất tại vị trí target.

- type: DROP_ITEM
  target: VICTIM
  material: GOLD_NUGGET
  amount: "1-3"

COMMAND

Chạy một lệnh tùy ý — "van an toàn" cho mọi hành vi chưa có mechanic riêng (give item, economy, gọi plugin khác...).

Placeholder trong command: {player} → tên target, {actor} → tên người chơi chủ passive, {damage} → sát thương (1 chữ số thập phân).

- type: COMMAND
  target: SELF
  mode: OP
  command: "give {player} diamond 1"

MESSAGE

Gửi tin nhắn chat riêng cho player. Chỉ hoạt động nếu target là Player (mob không nhận tin nhắn).

Placeholder trong message: {actor_name}, {victim_name}, {damage}.

- type: MESSAGE
  target: SELF
  message: "&c[Tử Thần] &7Bạn vừa kết liễu &f{victim_name}&7!"

SOUND

Phát âm thanh tại vị trí target. Mọi người chơi trong phạm vi tự nhiên đều nghe thấy.

- type: SOUND
  target: SELF
  sound: ENTITY_PLAYER_LEVELUP
  pitch: 1.5

PARTICLE_ANIMATION

Hiệu ứng particle hình tròn hoặc hình cầu xoay quanh target trong một khoảng thời gian.

- type: PARTICLE_ANIMATION
  target: SELF
  particle: ENCHANT
  shape: SPHERE
  radius: "1.5"
  duration-seconds: "2"

PARTICLE_PROJECTILE

Phóng viên đạn hạt nhân về phía victim. Khi trúng mục tiêu, gây sát thương và có thể kích hoạt hiệu ứng va chạm hoặc vệt bay.

Điều khiển đạn bay

Hiệu ứng bay (Flight) & Sweep

Hiệu ứng va chạm (Impact)

BREAK_AREA

Đào thêm block xung quanh block vừa phá. Chỉ dùng với trigger ON_BLOCK_BREAK. Tôn trọng WorldGuard/claim. Rớt item theo enchant của tool.

- type: BREAK_AREA
  size: "3"
  depth: "1"
  use-tool-drops: true
  excluded-materials: "BEDROCK,BARRIER,END_PORTAL_FRAME"

DELAY

Chờ N giây rồi mới chạy danh sách children. Dùng để tạo hiệu ứng trễ.

- type: DELAY
  seconds: "2"
  children:
    - type: EXPLODE
      target: VICTIM
      power: "4.0"
      amount: "20"

HIT_COUNTER

Đếm số lần sự kiện xảy ra và chỉ kích hoạt children khi đạt đủ ngưỡng every lần.

- type: HIT_COUNTER
  every: "5"
  reset-after: "10"
  children:
    - type: DAMAGE
      amount: "%player_level% * 5"

REPEAT

Lặp lại toàn bộ danh sách children, cách nhau interval-seconds giây, tổng times lần.

- type: REPEAT
  times: "4"
  interval-seconds: "1"
  children:
    - type: EFFECT
      target: VICTIM
      effect: POISON
      seconds: "2"
      level: "1"

Impact Shapes

Cấu hình bằng impact-shape trong PARTICLE_PROJECTILE. Hình dạng chỉ ảnh hưởng đến hiệu ứng nhìn thấy — vùng sát thương luôn là hình cầu kiểm soát bởi impact-radius.

Danh sách Stats (BUFF_STAT)

Các giá trị hợp lệ cho key stat trong action BUFF_STAT:

Ví dụ đầy đủ

Tốc Chiến — buff Speed khi đánh, 80% cơ hội

id: speed_on_hit
display-name: "&b[Tốc Chiến]"
trigger: ON_HIT
condition:
  target-type: BOTH
chance: "80"
cooldown: 3
actions:
  - type: EFFECT
    target: SELF
    effect: SPEED
    seconds: "3"
    level: "2"
    particles: false

Tử Thần — kết liễu tức thì khi HP dưới 5%

id: execute_5pct
display-name: "&c[Tử Thần]"
trigger: ON_HIT
condition:
  target-hp-percent-below: "5"
  target-type: BOTH
chance: "100"
cooldown: 0
actions:
  - type: DAMAGE
    target: VICTIM
    amount: 99999
    damage-type: TRUE
  - type: MESSAGE
    target: SELF
    message: "&c[Tử Thần] &7Kết liễu &f{victim_name}&7!"
  - type: SOUND
    target: SELF
    sound: ENTITY_PLAYER_LEVELUP
    pitch: 2.0

Cầu Lửa — chỉ khi crit, đạn + hiệu ứng hình cầu

id: fire_orb
display-name: "&6[Cầu Lửa]"
trigger: ON_HIT
condition:
  must-be-crit: true
  target-type: BOTH
chance: "30"
cooldown: 3
actions:
  - type: PARTICLE_PROJECTILE
    particle: FLAME
    particle-per-step: "3"
    speed: "1.5"
    amount: "8"
    damage-type: TRUE
    hit-radius: "1.2"
    impact-shape: SPHERE
    impact-particle: LAVA
    impact-radius: "4.0"
    impact-duration-ticks: "20"
    impact-damage: "3"
    impact-damage-type: TRUE

Trả Thù — đánh lại kẻ giết khi chết

id: revenge_on_death
display-name: "&4[Trả Thù]"
trigger: ON_DEATH
condition:
  target-type: PLAYER   # chỉ khi bị player giết
chance: "100"
cooldown: 0
actions:
  - type: DAMAGE
    target: VICTIM   # victim = kẻ đã giết
    amount: "%player_level% * 3"
    damage-type: TRUE
  - type: MESSAGE
    target: VICTIM
    message: "&4[Trả Thù] &7{actor_name} đã trả thù từ cõi chết!"

Nổ Chậm — nổ sau 2 giây khi giết

id: delayed_explode
display-name: "&e[Nổ Chậm]"
trigger: ON_KILL
chance: "100"
cooldown: 5
actions:
  - type: MESSAGE
    target: SELF
    message: "&e[Nổ Chậm] &7Đang tích năng lượng..."
  - type: DELAY
    seconds: "2"
    children:
      - type: EXPLODE
        target: SELF
        power: "3.0"
        radius: "5.0"
        amount: "%player_level% * 2"
        damage-type: TRUE
        include-self: false
      - type: SOUND
        target: SELF
        sound: ENTITY_GENERIC_EXPLODE

Cuốc TNT — đào 3×3 khi phá block

id: tnt_pickaxe
display-name: "&6[Cuốc TNT]"
trigger: ON_BLOCK_BREAK
chance: "100"
cooldown: 0
actions:
  - type: BREAK_AREA
    size: "3"
    depth: "1"
    use-tool-drops: true
    excluded-materials: "BEDROCK,BARRIER"

Độc Lặp — áp độc 4 lần, mỗi lần cách 1 giây

id: repeat_poison
display-name: "&2[Độc Lặp]"
trigger: ON_HIT
condition:
  target-type: BOTH
  expressions:
    - "%player_level% >= 20"
chance: "25"
cooldown: 10
actions:
  - type: REPEAT
    times: "4"
    interval-seconds: "1"
    children:
      - type: EFFECT
        target: VICTIM
        effect: POISON
        seconds: "2"
        level: "2"
      - type: PARTICLE_ANIMATION
        target: VICTIM
        particle: WITCH
        shape: CIRCLE
        radius: "0.8"
        duration-seconds: "1"

Rơi vàng — 25% khi giết mob

id: kill_drop_gold
trigger: ON_KILL
condition:
  target-type: MOB
chance: "25"
cooldown: 0
actions:
  - type: DROP_ITEM
    target: VICTIM
    material: GOLD_NUGGET
    amount: "1-3"