### Built-in Example Path

Source: https://www.iimc.cc/docs/kamenu/config/javascript-packages

The path for the default example file generated by KaMenu.

```text
plugins/KaMenu/js/example/message.js -> example/message
```

--------------------------------

### Complete Configuration Examples

Source: https://www.iimc.cc/docs/kaguilds/menu/actions

Practical examples demonstrating button definitions, input handling, and action sequences.

```yaml
buttons:
  X:
    display:
      material: DIAMOND_SWORD
      name: "&a执行命令"
    actions:
      left:
        - "command: kg info"
        - "sound: entity.experience_orb.pickup"
      right:
        - "open: main_menu"
```

```yaml
buttons:
  X:
    display:
      material: BOOK
      name: "&a提升职位"
    actions:
      left:
        - condition: "{role_node} >= 2"
          actions:
            - "command: kg promote {members_name}"
            - "tell: &a已提升 {members_name} 的职位"
          deny:
            - "tell: &c你没有权限提升成员职位！"
```

```yaml
buttons:
  X:
    display:
      material: GOLD_INGOT
      name: "&6存入金库"
    actions:
      left:
        - "catcher: bank_add"
        - "tell: &7请在聊天中输入金额"
        - "tell: &7输入 cancel 取消"
        - "close"
```

```yaml
buttons:
  X:
    display:
      material: PLAYER_HEAD
      name: "&e成员操作"
    actions:
      left:
        - "tell: &7查看成员信息"
      right:
        - "open: member_info_menu"
      shift_left:
        - "command: kg promote {members_name}"
        - "tell: &a已提升职位"
      drop:
        - "tell: &c你按了 Q 键"
```

```yaml
buttons:
  X:
    display:
      material: BOOK
      name: "&a延迟操作"
    actions:
      left:
        - "tell: &a操作开始..."
        - "wait: 40"
        - "tell: &b第一步完成..."
        - "wait: 40"
        - "tell: &e第二步完成..."
        - "wait: 40"
        - "tell: &c所有操作完成！"
```

--------------------------------

### Default Example Package Path

Source: https://www.iimc.cc/docs/kamenu/config/actions-packages

The path for the default example package generated by KaMenu.

```text
plugins/KaMenu/actions/example/welcome.yml -> example/welcome
```

--------------------------------

### Input Component Configuration Examples

Source: https://www.iimc.cc/docs/kamenu/menu/inputs

Examples of standard text input and multiline input configurations.

```yaml
Inputs:
  player_name:
    type: 'input'
    text: '&a请输入玩家名称'
    default: 'Steve'
    max_length: 16
    remove_chars: '&_'

  feedback:
    type: 'input'
    text: '&7留言内容'
    hide_text: true
    default: '请在此输入...'
    multiline:
      max_lines: 5
      height: 80
```

--------------------------------

### Global Action Package Examples

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Examples of global action package paths and content.

```yaml
plugins/KaMenu/actions/reward/daily.yml -> reward/daily
```

```yaml
plugins/KaMenu/actions/example/welcome.yml -> example/welcome
```

```yaml
actions:
  - 'toast: type=task;msg=领取成功;icon=emerald'
  - 'money: type=add;num={arg:0}'
```

```yaml
- 'actions: reward/daily,100'
```

--------------------------------

### Action Package Example Content

Source: https://www.iimc.cc/docs/kamenu/config/actions-packages

A complete example of an action package file using conditions.

```yaml
actions:
  - condition: 'hasPerm.reward.daily'
    allow:
      - 'toast: type=task;msg=领取成功;icon=emerald'
      - 'money: type=add;num={arg:0}'
      - 'sound: entity.experience_orb.pickup;volume=1.0;pitch=1.2'
    deny:
      - 'toast: type=challenge;msg=无权限;icon=barrier'
```

--------------------------------

### Global List Usage Examples

Source: https://www.iimc.cc/docs/kamenu/data/storage

Examples for writing and reading global string lists.

```yaml
actions:
  - 'glist: type=set;key=servers;var=`survival,skyblock,resource`;split=,'
  - 'glist: type=add;key=vip_players;var=`%player_name%`'
```

```yaml
condition: "inGlist.%player_name%;{glist:vip_players}"
text: "&7服务器数量: %kamenu_glist_size_servers%"
```

--------------------------------

### Global Data Usage Examples

Source: https://www.iimc.cc/docs/kamenu/data/storage

Examples demonstrating writing, reading, and conditional checks for global server data.

```yaml
# 写入
actions:
  - 'gdata: type=set;key=server_event;var=`active`'
  - 'gdata: type=set;key=event_winner;var=`%player_name%`'
  - 'gdata: type=add;key=event_join_count;var=`1`'

# 读取 - 在菜单文字中
text: '&7服务器活动状态: &a{gdata:server_event}'
text: '&7活动获胜者: &e{gdata:event_winner}'
text: '&7活动参与次数: &f{gdata:event_join_count}'

# 读取 - 在条件判断中
condition: '{gdata:server_event} == active'
```

--------------------------------

### Player Data Usage Examples

Source: https://www.iimc.cc/docs/kamenu/data/storage

Examples demonstrating writing, reading in text, and conditional checks for player data.

```yaml
# 写入
actions:
  - 'data: type=set;key=vip_level;var=`3`'
  - 'data: type=set;key=nickname;var=`$(input_nickname)`'
  - 'data: type=add;key=points;var=`10`'
  - 'data: type=take;key=points;var=`5`'

# 读取 - 在菜单文字中
text: '&7你的 VIP 等级: &6{data:vip_level}'
text: '&7你的昵称: &f{data:nickname}'
text: '&7你的积分: &e{data:points}'

# 读取 - 在条件判断中
condition: '{data:vip_level} >= 2'
```

--------------------------------

### Full Menu Examples

Source: https://www.iimc.cc/docs/kamenu/menu/conditions_item

Complete menu configurations demonstrating currency and item-based purchase logic.

```yaml
Title: '§6§l钻石商店'

Settings:
  need_placeholder:
    - 'math'
Body:
  diamond:
    type: 'item'
    text: '&a&l钻石'
    material: DIAMOND
    lore:
      - '&7价格: 100 金币 / 个'
    description: '请在下方拖动条选择购买数量。'

Inputs:
  amount:
    type: 'slider'
    text: '&a购买数量'
    min: 1
    max: 64
    default: 1
    format: '%s: %s个'

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ 确认购买 ]'
    actions:
      # 购买钻石（使用 hasMoney 判断是否有足够的货币）
      - condition: "isIntNum.$(amount)"
        deny:
          - 'tell: &c请输入一个有效的数值。'
          - 'return'
      - condition: "hasMoney.%math_0_100*$(amount)%"
        allow:
          - 'money: type=take;num=%math_0_100*$(amount)%'
          - 'item: type=give;mats=DIAMOND;amount=$(amount)'
          - 'tell: &a购买成功！消耗了金币 x%math_0_100*$(amount)%，获得 钻石 x$(amount)'
        deny:
          - 'tell: &c货币不足！需要 金币 x%math_0_100*$(amount)% '
          - 'sound: block.note_block.bass'
  deny:
    text: '&c[ 取消购买 ]'
    actions:
      - 'actionbar: &c取消购买'
      - 'sound: block.note_block.bass'
      - 'close'
```

```yaml
Title: '§6§l神奇钻石剑商店'

Settings:
  need_placeholder:
    - 'math'
Body:
  diamond_sword:
    type: 'item'
    text: '&a&l神奇钻石剑'
    material: DIAMOND_SWORD
    lore:
      - '&7价格: 10 个钻石'
    description: '请在下方拖动条选择兑换数量。'

Inputs:
  amount:
    type: 'slider'
    text: '&a购买数量'
    min: 1
    max: 64
    default: 1
    format: '%s: %s个'

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ 确认购买 ]'
    actions:
      # 购买钻石剑（使用 hasItem 判断普通物品）
      - condition: "hasItem.[mats=DIAMOND;amount=%math_0_10*$(amount)%]"
        allow:
          - 'item: type=take;mats=DIAMOND;amount=%math_0_10*$(amount)%'
          - 'stock-item: type=give;name=神奇钻石剑;amount={data:purchase_amount}'
          - 'tell: &a购买成功！消耗了钻石 x%math_0_10*$(amount)%，获得 神奇钻石剑 x$(amount)'
        deny:
          - 'tell: &c物品不足！需要 钻石 x%math_0_10*$(amount)% '
          - 'sound: block.note_block.bass'
  deny:
    text: '&c[ 取消购买 ]'
    actions:
      - 'actionbar: &c取消购买'
      - 'sound: block.note_block.bass'
      - 'close'
```

--------------------------------

### Dropdown Component Configuration

Source: https://www.iimc.cc/docs/kamenu/menu/inputs

Complete configuration examples for dropdown components.

```yaml
Inputs:
  color_select:
    type: 'dropdown'
    text: '&b选择颜色'
    hide_text: true
    options:
      - 'red => &c红色'
      - 'green => &a绿色'
      - 'blue => &b蓝色'
      - 'yellow => &e黄色'
    default_id: 'green'

  server_select:
    type: 'dropdown'
    text: '&7选择服务器'
    options:
      - 'lobby'
      - 'survival'
      - 'creative'
    default_id: 'lobby'
    width: 150
```

--------------------------------

### Menu Integration Example

Source: https://www.iimc.cc/docs/kamenu/config/actions-packages

Invoking an action package from a menu button.

```yaml
Bottom:
  type: multi
  buttons:
    daily:
      text: '&a[ 每日奖励 ]'
      actions:
        - 'actions: reward/daily,100'
        - 'reset'
```

--------------------------------

### Configure after_action Parameter

Source: https://www.iimc.cc/docs/kamenu/menu/setting

Basic configuration example showing the available options for the after_action parameter.

```yaml
Settings:
  after_action: CLOSE  # 默认值
  # after_action: NONE
  # after_action: WAIT_FOR_RESPONSE
```

--------------------------------

### Player List Collection Example

Source: https://www.iimc.cc/docs/kamenu/data/storage

A practical application for managing a list of favorite servers.

```yaml
Bottom:
  type: multi
  buttons:
    add_survival:
      text: '&a[ 收藏生存服 ]'
      actions:
        - 'list: type=add;key=favorite_servers;var=`survival`'
        - 'toast: type=task;msg=已收藏;icon=emerald'
        - 'reset'

    favorites:
      type: repeat
      source: "{list:favorite_servers}"
      item:
        text: "&b{item.value}"
        actions:
          - "server: {item.value}"
```

--------------------------------

### Standard shop menu configuration

Source: https://www.iimc.cc/docs/kamenu/menu/setting

A multi-button menu example for a server shop with purchase and exit actions.

```yaml
Title: '&8» &6&l服务器商店 &8«'

Settings:
  can_escape: true        # 允许 ESC 退出
  after_action: NONE      # 由服务器控制
  pause: false

Bottom:
  type: 'multi'
  buttons:
    buy:
      text: '&a[ 购买 ]'
      actions:
        - 'console: give %player_name% diamond 1'
        - 'console: eco take %player_name% 100'
        - 'tell: &a购买成功！'
        - 'close'
    exit:
      text: '&c[ 退出 ]'
      actions:
        - 'tell: &c再见！'
        - 'close'
```

--------------------------------

### Package ID Mapping

Source: https://www.iimc.cc/docs/kamenu/config/javascript-packages

Examples of how file paths map to package IDs.

```text
plugins/KaMenu/js/reward/message.js -> reward/message
plugins/KaMenu/js/common/format_money.js -> common/format_money
```

--------------------------------

### Action Package ID Mapping

Source: https://www.iimc.cc/docs/kamenu/config/actions-packages

Examples of how file paths map to package IDs.

```text
plugins/KaMenu/actions/reward/daily.yml -> reward/daily
plugins/KaMenu/actions/common/close.yml -> common/close
```

--------------------------------

### Action Package Lookup

Source: https://www.iimc.cc/docs/kamenu/config/actions-packages

Example of calling an action package to trigger the lookup process.

```yaml
- 'actions: reward/daily'
```

--------------------------------

### Return Action Examples

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Shows how to use the return action to interrupt the execution of subsequent actions in a list.

```yaml
- 'tell: 你点击了这个按钮'
- 'return'            # 执行中断
- 'tell: 你永远无法看到这行消息。'  # 不会执行后续操作
```

```yaml
- 'tell: &a开始倒计时...'
- 'wait: 20'            # 等待 1 秒
- 'tell: &e3...'
- 'wait: 20'
- 'tell: &e2...'
- 'wait: 20'
- 'tell: &e1...'
- 'wait: 20'
- condition: '%player_is_online% == false'
  allow:
    - 'tell: &c检测到玩家离线，操作中断！'
    - 'return'   # 执行中断
- 'tell: &a你完成了操作。' # 若满足条件该动作不会被执行
```

--------------------------------

### Conditional Expression Examples

Source: https://www.iimc.cc/docs/kamenu/menu/conditions

Examples of single conditions, logical AND/OR operations, and grouping with parentheses.

```yaml
# 单个条件
- condition: "%player_level% >= 10"

# AND 条件
- condition: "%player_level% >= 10 && %player_level% < 20"

# OR 条件
- condition: "%player_is_op% == true || %player_level% >= 20"

# 使用括号
- condition: "(%player_level% >= 5 && %player_level% <= 10) || %player_is_op% == true"
```

--------------------------------

### Package Lookup Priority

Source: https://www.iimc.cc/docs/kamenu/config/javascript-packages

Example of a call that triggers the lookup sequence.

```yaml
- 'js: [reward/message],100,Steve'
```

--------------------------------

### Online Players List Variable Example

Source: https://www.iimc.cc/docs/kamenu/placeholderapi

Example of the JSON array format returned by the online players placeholder.

```json
["Steve","Alex","Notch"]
```

--------------------------------

### Switch Language Configuration

Source: https://www.iimc.cc/docs/kaproxy/configuration

Example of updating the core language setting to English.

```yaml
core:
  language: en_US
```

--------------------------------

### Checkbox Component Configuration and Usage

Source: https://www.iimc.cc/docs/kamenu/menu/inputs

Examples of checkbox inputs and how to reference their values in action commands.

```yaml
Inputs:
  enable_notify:
    type: 'checkbox'
    text: '&a开启公告通知'
    default: true

  pvp_mode:
    type: 'checkbox'
    text: '&c开启 PvP 模式'
    default: false
    on_true: 'enabled'    # 勾选时 $(pvp_mode) = "enabled"
    on_false: 'disabled'  # 未勾选时 $(pvp_mode) = "disabled"
```

```yaml
Bottom:
  confirm:
    actions:
      - 'console: pvp set %player_name% $(pvp_mode)'
      # 勾选时执行: pvp set Steve enabled
      # 未勾选时执行: pvp set Steve disabled
```

--------------------------------

### Basic repeat configuration

Source: https://www.iimc.cc/docs/kamenu/menu/bottom

A minimal example showing how to define a repeat button with a data source and item template.

```yaml
Bottom:
  type: multi
  buttons:
    列表ID:
      type: repeat
      source: "数据源"
      item:
        text: "&a{item.value}"
        actions:
          - "tell: 你点击了 {item.value}"
```

--------------------------------

### Player List Dynamic Button Example

Source: https://www.iimc.cc/docs/kamenu/data/storage

Using a player list as a source for a repeating button component.

```yaml
Bottom:
  type: multi
  buttons:
    friends:
      type: repeat
      source: "{list:friends}"
      item:
        text: "&a{item.value}"
        actions:
          - "tell: 你点击了 {item.value}"
```

--------------------------------

### Configure Basic and Conditional Items

Source: https://www.iimc.cc/docs/kamenu/menu/body

Examples of defining items with default or custom names, and using conditional logic for descriptions and widths.

```yaml
  # 使用物品默认名称
  diamond_sword:
    type: 'item'
    material: 'DIAMOND_SWORD'
    # 不设置 name，显示物品默认名称"钻石剑"
    width: 16
    height: 16

  # 自定义物品名称
  custom_sword:
    type: 'item'
    material: 'DIAMOND_SWORD'
    name: '&6&l传奇之剑'  # 覆盖默认名称
    width: 16
    height: 16

  # 使用 description_width 设置宽度
  wide_description_item:
    type: 'item'
    material: 'ENCHANTED_BOOK'
    name: '&6魔法书'
    description: '&7这是一本神奇的魔法书\n&7可以施放强大的法术'
    description_width: 300  # 设置 description 宽度为 300 像素
    width: 16
    height: 16

  # description 和 description_width 都支持条件判断
  conditional_description_item:
    type: 'item'
    material: 'DIAMOND'
    name: '&b钻石'
    description:
      - condition: '%player_level% >= 10'
        allow: '&a高级物品\n&7您已解锁购买权限'
        deny: '&7需要达到 &e10 &7级才能购买'
    description_width:
      - condition: '%player_level% >= 10'
        allow: 300
        deny: 200
    width: 16
    height: 16
```

--------------------------------

### Wait Action Example

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Demonstrates using the wait action to create a countdown effect in a menu action list.

```yaml
- 'tell: &a开始倒计时...'
- 'wait: 20'            # 等待 1 秒
- 'tell: &e3...'
- 'wait: 20'
- 'tell: &e2...'
- 'wait: 20'
- 'tell: &e1...'
- 'wait: 20'
- 'title: title=&c出发！;in=5;keep=30;out=10'
```

--------------------------------

### Action List Usage Example

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Defining action lists in Events.Click and invoking them from menu buttons.

```yaml
Events:
  Click:
    greet:
      - 'tell: &a你好，{arg:0}！欢迎来到 &e{arg:1}&a。'
      - 'sound: ENTITY_PLAYER_LEVELUP'

    vip_check:
      - condition: 'hasPerm.essentials.vip'
        allow:
          - 'tell: &aVIP 专属欢迎！'
          - 'sound: ENTITY_EXPERIENCE_ORB_PICKUP'
        deny:
          - 'tell: &c你需要 VIP 权限'

Bottom:
  type: 'multi'
  buttons:
    btn_greet:
      text: '问候'
      actions:
        - 'actions: greet,玩家,生存服务器'  # 执行 Events.Click.greet 并传入参数

    btn_vip:
      text: 'VIP 检查'
      actions:
        - 'actions: vip_check'  # 执行 Events.Click.vip_check
```

--------------------------------

### Complex Action Chain Example

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Demonstrates a sequence of multiple actions triggered by a single action list call.

```yaml
Events:
  Click:
    daily_login:
      - 'tell: &6每日签到成功！'
      - 'sound: ENTITY_PLAYER_LEVELUP'
      - 'set-data: coins +100'
      - 'tell: &e获得 100 金币'
      - 'sound: ENTITY_EXPERIENCE_ORB_PICKUP'

Bottom:
  type: 'multi'
  buttons:
    daily:
      text: '每日签到'
      actions:
        - 'actions: daily_login'
```

--------------------------------

### Data Initialization Logic

Source: https://www.iimc.cc/docs/kamenu/menu/events

Check for null data values to perform first-time setup or track visit counts for players.

```yaml
Events:
  Open:
    - condition: '{data:first_visit} == null'
      allow:
        - 'tell: &e欢迎首次访问！已初始化数据'
        - 'set-data: first_visit %timestamp%'
        - 'set-data: visit_count 1'
        - 'title: title=&6欢迎新人;subtitle=&f这是你第一次访问;in=10;keep=60;out=20'
      deny:
        - 'tell: &7欢迎回来！这是你第 {data:visit_count} 次访问'
        - 'set-data: visit_count {data:visit_count} + 1'
```

--------------------------------

### Reference Equipment Slots

Source: https://www.iimc.cc/docs/kamenu/menu/body

Examples of displaying items currently equipped in player slots.

```yaml
  # 显示当前玩家的头盔
  player_helmet:
    type: 'item'
    material: '[HEAD]'
    width: 16
    height: 16

  # 显示指定玩家的头盔
  admin_helmet:
    type: 'item'
    material: '[HEAD:AdminPlayer]'
    width: 16
    height: 16
```

```yaml
  # 使用 Meta 变量（配合 player-click 监听器）
  target_helmet:
    type: 'item'
    material: '[HEAD:{meta:player}]'
    width: 16
    height: 16

  # 使用数据存储变量
  saved_player_helmet:
    type: 'item'
    material: '[CHEST:{data:target_player}]'
    width: 16
    height: 16

  # 使用 PAPI 变量
  random_player_sword:
    type: 'item'
    material: '[MAINHAND:%random_online_player%]'
    width: 16
    height: 16
```

```yaml
  # 头部为空时显示玩家头颅
  helmet_display:
    type: 'item'
    material: '[HEAD:{meta:player}]'
    width: 16
    height: 16

  # 其他槽位为空时显示浅灰色玻璃板
  chestplate_display:
    type: 'item'
    material: '[CHEST:{meta:player}]'
    width: 16
    height: 16
```

--------------------------------

### JavaScript Execution Examples

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Covers direct JavaScript execution, calling local packages, and passing arguments to JavaScript packages.

```yaml
actions:
  - 'js: player.sendMessage("Hello from JavaScript!");'
  - 'js: var random = Math.floor(Math.random() * 100);'
  - 'js: player.sendMessage("随机数: " + random);'
```

```yaml
JavaScript:
  show_health: |
    var health = player.getHealth();
    var maxHealth = player.getMaxHealth();
    player.sendMessage("§e生命值: §f" + health + "/" + maxHealth);

Bottom:
  type: 'notice'
  confirm:
    text: '&a查看生命值'
    actions:
      - 'js: [show_health]'
```

```yaml
JavaScript:
  process_data: |
    var playerName = args[0];
    var playerLevel = args[1];
    var money = args[2];

    player.sendMessage("§a玩家: §f" + playerName);
    player.sendMessage("§a等级: §f" + playerLevel);
    player.sendMessage("§a金币: §f" + money);

Bottom:
  type: 'notice'
  confirm:
    text: '&e处理数据'
    actions:
      - 'js: [process_data],%player_name%,$(level),{data:money}'
```

```yaml
actions:
  - 'js: [reward/message],100,Steve'
```

--------------------------------

### Action List Argument Formatting

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Examples of passing arguments with spaces or commas using quotes.

```yaml
- 'actions: hello 玩家 生存服务器'
```

```yaml
- 'actions: hello,"玩家 名称",`生存,服务器`'
```

--------------------------------

### Configure External Plugin Items

Source: https://www.iimc.cc/docs/kamenu/menu/body

Examples of referencing items from external plugins like ItemsAdder, Oraxen, and CraftEngine.

```yaml
  ia_item:
    type: item
    material: 'itemsadder:my_pack:magic_sword'
  oraxen_item:
    type: item
    material: 'oraxen:magic_sword'
  ce_item:
    type: item
    material: 'craftengine:my_pack:magic_sword'
```

--------------------------------

### Global Data Activity Registration Example

Source: https://www.iimc.cc/docs/kamenu/data/storage

A practical application of global data to track event participation counts.

```yaml
Bottom:
  type: notice
  confirm:
    text: '&b[ 报名活动 ]'
    actions:
      - 'gdata: type=add;key=event_join_count;var=`1`'
      - 'toast: type=task;msg=报名成功;icon=emerald'
      - 'reset'

Body:
  event_info:
    type: message
    text:
      - '&a当前活动状态: &f{gdata:server_event}'
      - '&e报名人数: &f{gdata:event_join_count}'
```

--------------------------------

### Action Configuration Structure

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Example of defining a sequence of actions within a menu button configuration, including confirmation text and sequential execution of messages, sounds, and menu closing.

```yaml
Bottom:
  type: 'notice'
  confirm:
    text: '&a确认'
    actions:
      - 'tell: &a操作成功！'
      - 'sound: entity.experience_orb.pickup'
      - 'close'
```

--------------------------------

### Conditional Logic Examples

Source: https://www.iimc.cc/docs/kaguilds/menu/actions

Various implementations of conditional logic using comparison and logical operators to control menu flow.

```yaml
# 单个条件
actions:
  left:
    - condition: "%player_level% >= 10"
      actions:
        - "tell: &a你的等级大于或等于10级！"
      deny:
        - "tell: &c你的等级不足！"
```

```yaml
# 多个条件 (AND)
actions:
  left:
    - condition: "%player_level% >= 10 && %player_level% < 20"
      actions:
        - "tell: &a你是等级10~20级之间的中级玩家！"
      deny:
        - "tell: &c你不是中级玩家！"
```

```yaml
# 多个条件 (OR)
actions:
  left:
    - condition: "%player_level% < 10 || %player_level% > 20"
      actions:
        - "tell: &a你是小于10级的新手或大于20级的高级玩家！"
```

```yaml
# 使用括号
actions:
  left:
    - condition: "(%player_level% >= 10 && %player_level% < 20) || %player_has_permission% == true"
      actions:
        - "tell: &a你的等级处于10~20之间，或你有权限！"
```

--------------------------------

### Upgrade Level Configuration

Source: https://www.iimc.cc/docs/kafurnace/config/upgrades

Example configuration for defining smelting speed upgrades for levels 2 through 6.

```yaml
upgrades:
  smelting_speed:
    levels:
      2:
        speed_multiplier: 1.2
        provider: "vault"
        price: 1500.0
```

--------------------------------

### Create Shop Menu with Welcome System

Source: https://www.iimc.cc/docs/kamenu/menu/events

Demonstrates first-visit detection using data storage and role-based welcome messages.

```yaml
Title: '&8» &6&l服务器商店 &8«'

Settings:
  after_action: CLOSE

Events:
  Open:
    # 首次访问检测
    - condition: '{data:shop_first_visit} == null'
      allow:
        - 'tell: &a欢迎来到服务器商店！这是你的第一次访问'
        - 'set-data: shop_first_visit true'
        - 'title: title=&6欢迎;subtitle=&f初次访问奖励已发放;in=5;keep=60;out=20'
      deny:
        - 'tell: &7欢迎回来！继续选购吧'
    
    # VIP 玩家欢迎
    - condition: 'hasPerm.vip.gold'
      allow:
        - 'tell: &6尊贵的金卡会员，欢迎光临！'
    
    # 显示余额
    - 'tell: &f当前余额: &e%player_balance%'

Body:
  welcome:
    type: 'message'
    text: '&7请选择你需要的商品'

Bottom:
  type: 'notice'
  confirm:
    text: '&a[ 浏览商品 ]'
    actions:
      - 'tell: &a正在浏览商品...'
```

--------------------------------

### Periodic Task Example

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Defining and controlling a periodic task.

```yaml
Events:
  Tasks:
    countdown:
      mode: manual
      interval: 20
      run_immediately: true
      actions:
        - 'tell: &e倒计时运行中'
      on_end:
        - 'tell: &a倒计时结束'

Bottom:
  type: multi
  buttons:
    start:
      text: '&a[ 开始 ]'
      actions:
        - 'run-task: countdown 10'
    stop:
      text: '&c[ 停止 ]'
      actions:
        - 'stop-task: countdown'
    stop_all:
      text: '&4[ 停止全部 ]'
      actions:
        - 'stop-task: *'
```

--------------------------------

### Recursive Call Prevention

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Examples of invalid recursive action calls.

```yaml
# Events.Click.test 内不要写：
- 'actions: test'

# actions/test.yml 内也不要写：
- 'actions: test'
```

--------------------------------

### Task Control Syntax

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Commands for starting and stopping periodic tasks.

```yaml
- 'run-task: <任务ID>'
- 'run-task: <任务ID> <次数>'
- 'run-task: *'
- 'run-task: * <次数>'
- 'stop-task: <任务ID>'
- 'stop-task: *'
- 'stop-current-task'
```

--------------------------------

### Basic menu with PlaceholderAPI dependencies

Source: https://www.iimc.cc/docs/kamenu/menu/setting

A menu configuration requiring specific extensions to display player information correctly.

```yaml
Title: '&8» &6&l玩家信息 &8«'

Settings:
  need_placeholder:
    - 'player'
    - 'vault'

Body:
  message:
    type: 'message'
    text: |
      &a玩家名称: %player_name%
      &a玩家余额: %vault_eco_balance%
      &a在线时间: %player_time_played%

Bottom:
  type: 'notice'
  confirm:
    text: '&a[ 确定 ]'
    actions:
      - 'close'
```

--------------------------------

### JavaScript Package Content

Source: https://www.iimc.cc/docs/kamenu/config/javascript-packages

Example of a simple JS package that returns a formatted string.

```javascript
var amount = args[0] || "0";
var target = args[1] || name;
"恭喜 " + target + " 获得 " + amount + " 金币";
```

--------------------------------

### Testing PlaceholderAPI Variables

Source: https://www.iimc.cc/docs/kaguilds/placeholderapi

Command to verify that the KaGuilds extension is correctly loaded and parsing variables for a player.

```bash
/papi parse player %kaguilds_name%
```

--------------------------------

### Parameter Formatting

Source: https://www.iimc.cc/docs/kamenu/config/javascript-packages

Different ways to pass arguments to a package.

```yaml
- 'js: [reward/message],100,Steve'
- 'js: [reward/message] 100 Steve'
```

```yaml
- 'js: [reward/message],"100 coins",`Steve,Alex`'
```

--------------------------------

### 定位条款配置文件

Source: https://www.iimc.cc/docs/kalogin/features/welcome

条款内容存储在插件目录下的 welcome.yml 文件中。

```text
plugins/KaLogin/ui/welcome.yml
```

--------------------------------

### 打开内存 YAML 菜单

Source: https://www.iimc.cc/docs/kamenu/api

通过 openYaml 解析内存中的 YAML 字符串并直接打开，无需写入文件系统。

```kotlin
val yaml = """
Title: "&a游戏中心"
Body:
  welcome:
    type: message
    text: "&7欢迎你，%player_name%！"
Bottom:
  type: notice
  confirm:
    text: "&a加入"
    actions:
      - "kgc:join lobby"
""".trimIndent()

KaMenuAPI.openYaml(player, yaml, "kagamecenter:main")
```

--------------------------------

### Configure Player Heads

Source: https://www.iimc.cc/docs/kamenu/menu/body

Examples of displaying player heads using owner names or Base64 textures.

```yaml
  self_head:
    type: 'item'
    material: 'PLAYER_HEAD'
    skull_owner: '%player_name%'
    name: '&a我的头像'
    description: '&7当前玩家的皮肤头颅'
    width: 24
    height: 24

  target_head:
    type: 'item'
    material: 'PLAYER_HEAD'
    skull_owner: '{meta:player}'
    name: '&e目标玩家'
    description: '&7显示被检查玩家的头像'

  custom_head:
    type: 'item'
    material: 'PLAYER_HEAD'
    skull_texture: 'eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA...'
    name: '&6自定义头颅'
    description: '&7使用 Base64 纹理值显示固定外观'
```

--------------------------------

### Use Player Metadata in Scoreboard

Source: https://www.iimc.cc/docs/kamenu/placeholderapi

Example configuration for using temporary memory-based player metadata in a scoreboard.

```yaml
# 记分板配置示例（显示临时数据）
scoreboard:
  - '&6上次访问: &f%kamenu_meta_time%'
  - '&7临时状态: &f%kamenu_meta_temp_status%'
```

--------------------------------

### open / force-open

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Opens a menu for the player.

```APIDOC
## open / force-open

### Description
Opens a menu. 'open' triggers the menu's Open event, while 'force-open' skips it.

### Format
`open: <menu_id>`
`force-open: <menu_id>`
```

--------------------------------

### Use List Variables for Conditionals

Source: https://www.iimc.cc/docs/kamenu/placeholderapi

Example of using list size placeholders to define conditional logic.

```yaml
condition: "%kamenu_list_size_friends% > 0"
condition: "%kamenu_glist_size_servers% >= 3"
```

--------------------------------

### Slider Component Configuration

Source: https://www.iimc.cc/docs/kamenu/menu/inputs

Examples of numeric slider inputs with defined ranges, steps, and display formats.

```yaml
Inputs:
  volume:
    type: 'slider'
    text: '&e音量'
    min: 0
    max: 100
    step: 5
    default: 50
    format: '&e音量: &f%s%%'

  purchase_amount:
    type: 'slider'
    text: '&6购买数量'
    min: 1
    max: 64
    step: 1
    default: 1
    format: '数量: %s'
```

--------------------------------

### 配置多行文本与变量

Source: https://www.iimc.cc/docs/kamenu/menu/body

使用列表格式定义多行消息，支持颜色代码和 PlaceholderAPI 变量。

```yaml
Body:
  player_info:
    type: 'message'
    text:
      - '&a玩家名称: &f{player_name}'
      - '&a玩家余额: &e%vault_eco_balance% &7金币'
      - '&a在线时间: &e%player_time_played%'
      - '&a服务器名称: &f{gdata:server_name}'
```

--------------------------------

### Smelting Progress Display

Source: https://www.iimc.cc/docs/kafurnace/placeholderapi

Example usage of progress bars and time remaining variables in a display context.

```text
进度: %kafurnace_1_cook_progress_bar% %kafurnace_1_cook_progress%%
本轮剩余: %kafurnace_1_cook_remaining_seconds% 秒
全部剩余: %kafurnace_1_estimated_remaining_seconds% 秒
```

--------------------------------

### 自定义条款内容示例

Source: https://www.iimc.cc/docs/kalogin/features/welcome

通过编辑 welcome.yml 修改欢迎信息和服务器规则文本，支持颜色代码和渐变效果。

```yaml
Body:
  welcome:
    type: 'message'
    text: |
      <gradient:gold:yellow>欢迎来到服务器！<reset>
      在继续游戏前，请先阅读以下说明与服务器条款。

  rules:
    type: 'message'
    text: |
      &7- 请遵守服务器规则
      &7- 禁止作弊、恶意破坏与骚扰他人
      &7- 如继续游戏，则视为你已阅读并同意服务器条款
```

--------------------------------

### Complete Menu Action Configuration

Source: https://www.iimc.cc/docs/kamenu/menu/actions

Defines a multi-column menu with purchase logic and informational tooltips.

```yaml
Bottom:
  type: 'multi'
  columns: 2
  buttons:
    purchase:
      text: '&6[ 购买 ]'
      actions:
        - condition: "%player_balance% >= 500"
          allow:
            - 'console: eco take %player_name% 500'
            - 'console: give %player_name% diamond_sword 1'
            - 'tell: &a购买成功！消费 500 金币'
            - 'sound: entity.player.levelup'
            - 'close'
          deny:
            - 'tell: &c余额不足！需要 500 金币，当前: %player_balance%'
            - 'sound: block.note_block.bass'

    info:
      text: '&7[ 查看说明 ]'
      actions:
        - 'tell: &6=== 神圣之剑说明 ==='
        - 'tell: &f- 攻击力 +20'
        - 'tell: &f- 可用于高级副本'
        - 'hovertext: &7了解更多 <text=&b[点击查看官网];hover=&7打开浏览器;url=https://example.com>'
```

--------------------------------

### 菜单导航 (open/close/force-open/force-close/reset)

Source: https://www.iimc.cc/docs/kamenu/menu/actions

用于打开、关闭、强制操作或重置菜单状态的动作。

```yaml
- 'open: main_menu'
- 'open: shop/weapons'
- 'open: admin/tools'
```

```yaml
- 'tell: &c再见！'
- 'close'
```

```yaml
# 普通打开（会执行目标菜单的 Open 事件）
- 'open: shop'

# 强制打开（跳过 Open 事件）
- 'force-open: shop'
```

```yaml
- 'force-close'
```

```yaml
# 刷新当前菜单
- 'reset'
```

--------------------------------

### 配置后端服务器 KaGuilds

Source: https://www.iimc.cc/docs/kaguilds/home/velocity

在后端服务器的 config.yml 中启用代理模式并配置共享数据库，确保每台服务器拥有唯一的 server-id。

```yaml
proxy: true
server-id: survival

database:
  type: "MySQL"
  host: "127.0.0.1"
  port: 3306
  db: "kaguilds"
  user: "kaguilds"
  password: "replace_with_a_strong_password"
```

--------------------------------

### Common JavaScript execution errors

Source: https://www.iimc.cc/docs/kamenu/menu/javascript

Examples of console error messages encountered when JavaScript syntax or references are invalid.

```text
JavaScript execution error: ReferenceError: "undefinedVar" is not defined
JavaScript execution error: SyntaxError: Unexpected token
```

--------------------------------

### Use Online Players List in Conditionals

Source: https://www.iimc.cc/docs/kamenu/placeholderapi

Example of using the online players list within a conditional check.

```yaml
condition: "inGlist.$(target);%kamenu_online_players%"
```

--------------------------------

### Use CLOSE after_action

Source: https://www.iimc.cc/docs/kamenu/menu/setting

Example of the default CLOSE behavior where the menu closes immediately upon clicking a button.

```yaml
Settings:
  after_action: CLOSE

Bottom:
  type: 'notice'
  confirm:
    text: '&a[ 关闭 ]'
    actions:
      - 'close'
```

--------------------------------

### openConfig(Player player, YamlConfiguration config, String contextId)

Source: https://www.iimc.cc/docs/kamenu/api

打开内存中的 YamlConfiguration。

```APIDOC
## openConfig(Player player, YamlConfiguration config, String contextId)

### Description
打开内存中的 YamlConfiguration。该配置不要求来自 MenuManager。

### Parameters
- **player** (Player) - 目标玩家
- **config** (YamlConfiguration) - 完整的 KaMenu 菜单配置
- **contextId** (String) - 外部上下文标识，用于日志定位来源

### Returns
- **boolean** - 是否成功提交打开请求
```

--------------------------------

### Default Menu Configuration

Source: https://www.iimc.cc/docs/kamenu/menu/setting

Recommended configuration for standard menus where explicit action paths are required.

```yaml
Settings:
  can_escape: true
  after_action: NONE
```

--------------------------------

### Player Data Gift Claiming Example

Source: https://www.iimc.cc/docs/kamenu/data/storage

A practical application of player data to track whether a gift has been claimed.

```yaml
Bottom:
  type: notice
  confirm:
    text: '&a[ 领取礼包 ]'
    actions:
      - condition: "{data:first_gift} == true"
        allow:
          - 'toast: type=error;msg=已经领过;icon=barrier'
          - 'return'
        deny:
          - 'data: type=set;key=first_gift;var=`true`'
          - 'item: type=give;mats=APPLE;amount=5'
          - 'toast: type=task;msg=领取成功;icon=apple'
```

--------------------------------

### Check Item Attribute Usage Examples

Source: https://www.iimc.cc/docs/kamenu/placeholderapi

Various ways to use the checkitem variable within menu configuration files.

```yaml
# 输出玩家主手物品的有效显示名称；未指定 fmt，因此返回纯文本
text: '&f主手：{checkitem:[hand;name]}'

# 输出玩家主手物品的剩余耐久百分比；变量本身不包含百分号
text: '&7耐久：{checkitem:[hand;dura_pct]}%'

# 判断玩家主手物品的锋利附魔是否达到 5 级
condition: '{checkitem:[hand;ench:sharpness]} >= 5'

# 读取保存物品“神奇之剑”的全部附魔 JSON，可直接作为 repeat 数据源
source: '{checkitem:[stock:神奇之剑;enchants]}'

# 读取保存物品“神奇之剑”的第 1 行 Lore，并转换为 MiniMessage 格式
text: '{checkitem:[stock:神奇之剑;lore:1;fmt:mini]}'

# 同时输出主手物品的 ItemModel NamespacedKey 和整数 CustomModelData
text: '模型：{checkitem:[hand;item_model]} / ID：{checkitem:[hand;custom_model_id]}'

# 读取 ItemsAdder 模板名称，并检查玩家主手中的外部物品身份
text: '{checkitem:[itemsadder:my_pack:magic_sword;name;fmt:mini]}'
condition: '{checkitem:[hand;custom_id]} == itemsadder:my_pack:magic_sword'
```