Trang chủ/Menu/Icon

Icon

"Không icon, không menu." Icon là từng ô vật phẩm trong GUI: phần hiển thị (display), phần tương tác (actions) và các thuộc tính vận hành (update, refresh, sub-icon, page).

Cấu trúc một icon#2>

Icons:
  'close':                  # ID — trùng ký tự trong Layout (hoặc 'slots:' riêng)
    update: [ -1, 5, -1, -1 ]   # [material, name, lore, slots] chu kỳ update (ticks)
    refresh: 20               # Chu kỳ tính lại sub-icon (ticks); -1 = tắt
    display:                  # Phần HIỂN THỊ
      material: 'Red Stained Glass Pane'
      name: '&cClose'
      lore: [ '&7Click to close' ]
      amount: 1
      shiny: false
      flags: [ ]
      enchant: [ ]
      nbt: { }
      data: 0                 # durability (item damage)
      tooltip: ''             # 1.20.5+: tooltip_style
      model: ''               # 1.20.5+: item model
      hide_tooltip: false     # 1.20.5+
      unbreakable: false
    actions:                  # Phần TƯƠNG TÁC
      all: 'close'
      left: [ ]
      right: [ ]

update & refresh#2>

Key Ý nghĩa

`update` Chu kỳ vẽ lại từng phần hiển thị: mảng 4 số `[material, name, lore, slots]` hoặc 1 số áp dụng tất cả. `-1` = không update phần đó.

`refresh` Chu kỳ tính lại sub-icon (điều kiện + priority). Chỉ có ý nghĩa khi icon có sub-icons. Có thể gọi thủ công bằng action `refresh:`.

Plugin tự phát hiện phần nào cần update (có animation, có biến…) và tự gán chu kỳ hợp lý — phần lớn trường hợp bạn không cần khai báo `update:` thủ công. Chỉ cần đặt `update` khi muốn tắt/ép chu kỳ cụ thể.

`update` và `refresh` là thuộc tính của icon cha — sub-icon không tự khai báo được. Icon update không bao giờ đè lên slot Input đang có đồ buffer (tránh mất hiển thị đồ kéo vào).

Key	Ý nghĩa
`update`	Chu kỳ vẽ lại từng phần hiển thị: mảng 4 số `[material, name, lore, slots]` hoặc 1 số áp dụng tất cả. `-1` = không update phần đó.
`refresh`	Chu kỳ tính lại sub-icon (điều kiện + priority). Chỉ có ý nghĩa khi icon có sub-icons. Có thể gọi thủ công bằng action `refresh:`.

Display — hiển thị#2>

material (texture)#3>

material: 'Red Stained Glass Pane'    # tên XMaterial (không dấu, có thể cách)
material: 'Wool:3'                    # legacy data value
material: 'head:%player_name%'        # đầu người chơi (online từ NMS, offline tải async)
material: 'head:eyJ0ZXh0dXJlcyI6...'  # texture base64 / hash
material: '{"type":"DIAMOND_SWORD",...}'  # JSON từ /shinnui item toJson
material: 'source:ItemsAdder:itemId'  # item của plugin hook (source::)
material: 'coal{model-data=15}'       # custom model data
material: 'leather chestplate {dye=255,255,0}'  # nhuộm da
material: 'white banner {banner=RED MOJANG,WHITE}'  # banner pattern

Material viết dạng mảng sẽ thành animation quay vòng theo chu kỳ update của texture:

material: [ 'Red Stained Glass Pane', 'Orange Stained Glass Pane' ]

name & lore#3>

name: '&cClose'                       # static
name: [ '&cC&7lose', '&cCl&7ose', '&cClo&7se' ]  # animation (theo chu kỳ update name)

lore: [ 'Line 1', 'Line 2' ]
lore:
  - - '&7Frame A'                     # lore animation: mảng lồng nhau
  - - '&7Frame B'

Mỗi dòng lore có thể gắn điều kiện inline — dòng chỉ hiện khi điều kiện đúng (chạy lại mỗi lần update lore):

lore:
  - '&7Hello'
  - 'You are VIP {condition=perm *vip.user}'
  - '&7Bye'

Điều kiện lore được tính mỗi lần update — với icon update nhanh sẽ tốn tài nguyên. Hạn chế điều kiện phức tạp trong lore của icon update 1 tick.

Màu mặc định name/lore (khi bạn không viết mã màu) lấy từ Menu.Icon.Item.Default-Name-Color / Default-Lore-Color trong settings.yml. Pre-Color: true sẽ tô màu trước khi parse biến.

Các thuộc tính Meta#3>

Key Giá trị Mô tả

`amount` số hoặc biến Số lượng item hiển thị (1–64). Dạng `'${js: ...}'` để động.

`shiny` true/false/condition Hiệu ứng phát sáng (enchant ẩn + HIDE_ENCHANTS). Nhận cả điều kiện: `'perm *vip.user'`.

`flags` list ItemFlag: `HIDE_ENCHANTS, HIDE_ATTRIBUTES, HIDE_UNBREAKABLE, HIDE_POTION_EFFECTS, HIDE_DESTROYS, HIDE_PLACED_ON`.

`enchant` list Ví dụ `- 'sharpness:5'` hoặc `- 'unbreaking:3, true'` (tham số 2 = ignore level limit).

`nbt` map Ghi NBT qua TabooLib ItemTag — hỗ trợ biến. Ví dụ `nbt: { myKey: 'value' }`.

`data` số Durability/damage value (legacy).

`tooltip` namespaced key 1.20.5+: `tooltip_style` của item.

`model` namespaced key 1.20.5+: `item_model` component.

`hide_tooltip` true/false/condition 1.20.5+: ẩn hoàn toàn tooltip.

`unbreakable` true/false/condition Item không hỏng.

Key	Giá trị	Mô tả
`amount`	số hoặc biến	Số lượng item hiển thị (1–64). Dạng `'${js: ...}'` để động.
`shiny`	true/false/condition	Hiệu ứng phát sáng (enchant ẩn + HIDE_ENCHANTS). Nhận cả điều kiện: `'perm *vip.user'`.
`flags`	list	ItemFlag: `HIDE_ENCHANTS, HIDE_ATTRIBUTES, HIDE_UNBREAKABLE, HIDE_POTION_EFFECTS, HIDE_DESTROYS, HIDE_PLACED_ON`.
`enchant`	list	Ví dụ `- 'sharpness:5'` hoặc `- 'unbreaking:3, true'` (tham số 2 = ignore level limit).
`nbt`	map	Ghi NBT qua TabooLib ItemTag — hỗ trợ biến. Ví dụ `nbt: { myKey: 'value' }`.
`data`	số	Durability/damage value (legacy).
`tooltip`	namespaced key	1.20.5+: `tooltip_style` của item.
`model`	namespaced key	1.20.5+: `item_model` component.
`hide_tooltip`	true/false/condition	1.20.5+: ẩn hoàn toàn tooltip.
`unbreakable`	true/false/condition	Item không hỏng.

Sub-icons — icon theo điều kiện#2>

Một icon có thể có nhiều "biến thể". Node icons: liệt kê sub-icon, mỗi sub-icon có condition + priority; icon hiển thị là sub-icon đầu tiên (priority tăng dần) thoả điều kiện, nếu không có sub-icon nào thoả thì dùng display của icon cha.

Icons:
  'A':
    display:
      material: grass_block
    icons:
      - condition: 'perm *op'
        priority: 5            # nhỏ = xét trước
        inherit: true          # kế thừa material (và name/lore nếu inherit)
        display:
          material: beacon
      - condition: 'perm *mvp.user'
        display:
          material: diamond block
      - condition: 'perm *vip.user'
        display:
          material: gold block

Nếu bạn không viết priority, plugin tự gán theo thứ tự xuất hiện trong file — sub-icon đầu tiên được xét trước.
inherit: true — sub-icon kế thừa material/name/lore của icon cha cho những phần nó không tự khai báo (mặc định theo Menu.Icon.Inherit trong settings.yml; material luôn được kế thừa).
Sub-icon có actions riêng — action theo icon đang hiển thị.
Đổi sub-icon tức thì: dùng action refresh: <ID> sau khi set-meta.

actions — tương tác click#2>

  '*':
    actions:
      all: 'sound: BLOCK_NOTE_BLOCK_PLING-1-2'
      left:
        - 'set-meta: icon_server_hide true'
        - 'refresh: *'
      number_key_6:
        - 'close'
        - 'title: `&b&lGET READY` 10 20 40'

Giá trị mỗi click type là một reaction (nhóm action). Danh sách click type đầy đủ (khớp không phân biệt hoa thường, dấu gạch):

Nhóm	Các type
Chuột	`ALL`, `LEFT`, `RIGHT`, `MIDDLE`, `DOUBLE_CLICK`
Shift	`SHIFT_LEFT`, `SHIFT_RIGHT`
Bàn phím	`NUMBER_KEY`, `NUMBER_KEY_1` … `NUMBER_KEY_9`, `OFFHAND` (phím F)
Drop	`DROP` (Q), `CONTROL_DROP` (Ctrl+Q)
Kéo ra ngoài GUI	`ABROAD_LEFT_EMPTY`, `ABROAD_RIGHT_EMPTY`, `ABROAD_LEFT_ITEM`, `ABROAD_RIGHT_ITEM`
Drag (kéo chuột)	`LEFT_MOUSE_DRAG_ADD`, `RIGHT_MOUSE_DRAG_ADD`, `MIDDLE_MOUSE_DRAG_ADD`

Chi tiết cách viết action xem trang Action.

page — gán icon theo trang (BOOK)#2>

Icons:
  'intro':
    page: 1                  # icon này chỉ xuất hiện ở trang sách 1
    display:
      text: '&7Chào %player_name%!'

Với Render-Type BOOK, page: quyết định icon nằm ở trang sách nào. Với CHEST, trang do layout nhiều phần tử quyết định.

slots — đặt slot thủ công#2>

  'Bee':
    slots:
      - 9
      - '10-13'          # range
      - '${js: varInt("%player_health%")}'  # động
    # hoặc dạng lồng theo trang:
    # slots: [ [9,10], [18,19] ]

Nên đặt vị trí qua Layout; slots dùng khi cần slot động hoặc icon không có trong layout. Cấu hình thủ công ghi đè layout.

Icon

Display — hiển thị#2>

page — gán icon theo trang (BOOK)#2> Icons: 'intro': page: 1 # icon này chỉ xuất hiện ở trang sách 1 display: text: '&7Chào %player_name%!' Với Render-Type BOOK, page: quyết định icon nằm ở trang sách nào. Với CHEST, trang do layout nhiều phần tử quyết định.