> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GUI 配置

<span id="gui-配置" />

ArcPass 提供高度可定制的 GUI 系统，支持自定义布局、物品和交互。

<h2 id="文件位置">
  文件位置
</h2>

```
plugins/ArcPass/gui/
├── main-menu.yml   # 主菜单
├── quests.yml      # 任务界面
├── rewards.yml     # 奖励界面
├── admin.yml       # 管理界面
└── shop.yml        # 商店界面
```

<h2 id="基本结构">
  基本结构
</h2>

```yaml theme={null}
# GUI 标题
title: "&6&lArcPass 通行证"

# GUI 大小（槽位数，54 = 6行）
size: 54

# 边框填充
border:
  enabled: true
  material: GRAY_STAINED_GLASS_PANE
  name: " "

# 静态物品（固定位置）
items:
  # 玩家信息 - 顶部中央
  player-info:
    slot: 4
    material: PLAYER_HEAD
    name: "&6%player_name% 的通行证"
    lore:
      - "&7当前等级: &e%level%"
      - "&7总经验: &e%total_exp%"
      - "&7当前进度: &e%current_exp%&7/&e%next_level_exp%"
      - ""
      - "&7已解锁档位: &e%unlocked_tiers%"
    skull-owner: "%player_name%"
```

<h2 id="十六进制-rgb-色彩">
  十六进制 RGB 色彩 v1.9.2
</h2>

GUI 标题、物品名称、Lore、插件消息和称号文本支持十六进制 RGB 色彩。可以使用以下两种写法，并继续混用传统颜色代码：

```yaml theme={null}
title: "#12ABEFArcPass 通行证"
name: "&#FF8800赛季奖励"
lore:
  - "&7传统颜色与 #55FFAA十六进制色彩&7 可以混用"
```

<h2 id="槽位编号">
  槽位编号
</h2>

GUI 槽位从 0 开始，按行排列：

```
行 1:  0  1  2  3  4  5  6  7  8
行 2:  9 10 11 12 13 14 15 16 17
行 3: 18 19 20 21 22 23 24 25 26
行 4: 27 28 29 30 31 32 33 34 35
行 5: 36 37 38 39 40 41 42 43 44
行 6: 45 46 47 48 49 50 51 52 53
```

也可以使用多个槽位：

```yaml theme={null}
items:
  border:
    slots: [0, 1, 2, 3, 4, 5, 6, 7, 8, 45, 46, 47, 48, 49, 50, 51, 52, 53]
    material: BLACK_STAINED_GLASS_PANE
    name: " "
```

<h2 id="点击动作">
  点击动作
</h2>

动作配置使用 `action` 字段，支持以下类型：

| 类型 | 说明 | 示例 |
| - | - | - |
| `CLOSE` | 关闭 GUI | `type: CLOSE` |
| `OPEN_GUI` | 打开另一个 GUI | `type: OPEN_GUI` + `gui: quests` |
| `COMMAND` | 执行命令 | `type: COMMAND` + `command: "arcpass help"` |
| `INPUT` | 请求玩家输入 | `type: INPUT` + `prompt:` + `command:` |

```yaml theme={null}
items:
  # 任务按钮
  quests:
    slot: 29
    material: BOOK
    name: "&e任务列表"
    lore:
      - "&7查看并完成任务获取经验"
      - ""
      - "&7日常任务: &e%daily_quests_count%"
      - "&7周常任务: &e%weekly_quests_count%"
      - ""
      - "&a点击查看"
    action:
      type: OPEN_GUI
      gui: quests

  # 关闭按钮
  close:
    slot: 45
    material: BARRIER
    name: "&c关闭"
    lore:
      - "&7点击关闭菜单"
    action:
      type: CLOSE
```

<h2 id="变量占位符">
  变量占位符
</h2>

GUI 支持以下内置变量：

| 变量 | 说明 |
| - | - |
| `%player_name%` | 玩家名称 |
| `%level%` | 当前等级 |
| `%exp%` | 当前经验 |
| `%required_exp%` | 升级所需经验 |
| `%total_exp%` | 总经验 |
| `%progress%` | 进度百分比 |
| `%progress_bar%` | 进度条 |
| `%season_name%` | 赛季名称 |
| `%tiers%` | 已拥有档位 |

如果安装了 PlaceholderAPI，可以使用任意 PAPI 变量。

<h2 id="截图展示">
  截图展示
</h2>

<Columns cols={2}>
  <Frame caption="主菜单">
    <img src="https://mintcdn.com/kitemc/dVZyPCaRRbVaalqm/images/arcpass/screenshot-main-menu.png?fit=max&auto=format&n=dVZyPCaRRbVaalqm&q=85&s=a78feaa2bcd90543371afa340aae4310" alt="主菜单" width="2560" height="1440" data-path="images/arcpass/screenshot-main-menu.png" />
  </Frame>

  <Frame caption="任务列表">
    <img src="https://mintcdn.com/kitemc/dVZyPCaRRbVaalqm/images/arcpass/screenshot-quest-list.png?fit=max&auto=format&n=dVZyPCaRRbVaalqm&q=85&s=dea0057c44a638681ee60c98d7ebd7a4" alt="任务列表" width="2560" height="1440" data-path="images/arcpass/screenshot-quest-list.png" />
  </Frame>

  <Frame caption="奖励轨道">
    <img src="https://mintcdn.com/kitemc/dVZyPCaRRbVaalqm/images/arcpass/screenshot-reward-track.png?fit=max&auto=format&n=dVZyPCaRRbVaalqm&q=85&s=361321a0d953d3267ba29316682592e7" alt="奖励轨道" width="2560" height="1440" data-path="images/arcpass/screenshot-reward-track.png" />
  </Frame>

  <Frame caption="管理面板">
    <img src="https://mintcdn.com/kitemc/dVZyPCaRRbVaalqm/images/arcpass/screenshot-admin-panel.png?fit=max&auto=format&n=dVZyPCaRRbVaalqm&q=85&s=12285f8d831a7d7736b862d83cd28b86" alt="管理面板" width="2560" height="1440" data-path="images/arcpass/screenshot-admin-panel.png" />
  </Frame>
</Columns>

<h2 id="主菜单配置示例">
  主菜单配置示例
</h2>

```yaml theme={null}
# gui/main-menu.yml

title: "&6&lArcPass 通行证"
size: 54  # 6 行

# 边框填充
border:
  enabled: true
  material: GRAY_STAINED_GLASS_PANE
  name: " "

# 静态物品（固定位置）
items:
  # 玩家信息 - 顶部中央
  player-info:
    slot: 4
    material: PLAYER_HEAD
    name: "&6%player_name% 的通行证"
    lore:
      - "&7当前等级: &e%level%"
      - "&7总经验: &e%total_exp%"
      - "&7当前进度: &e%current_exp%&7/&e%next_level_exp%"
      - ""
      - "&7已解锁档位: &e%unlocked_tiers%"
    skull-owner: "%player_name%"

  # 任务按钮
  quests:
    slot: 29
    material: BOOK
    name: "&e任务列表"
    lore:
      - "&7查看并完成任务获取经验"
      - ""
      - "&7日常任务: &e%daily_quests_count%"
      - "&7周常任务: &e%weekly_quests_count%"
      - ""
      - "&a点击查看"
    action:
      type: OPEN_GUI
      gui: quests

  # 奖励按钮
  rewards:
    slot: 31
    material: CHEST
    name: "&6奖励轨道"
    lore:
      - "&7查看并领取等级奖励"
      - ""
      - "&7可领取奖励: &e%claimable_rewards%"
      - ""
      - "&a点击查看"
    action:
      type: OPEN_GUI
      gui: rewards

  # 商店/升级按钮
  shop:
    slot: 33
    material: GOLD_INGOT
    name: "&e购买通行证"
    lore:
      - "&7升级你的通行证等级"
      - ""
      - "&7当前档位: &e%current_tier%"
      - ""
      - "&a点击购买"
    action:
      type: OPEN_GUI
      gui: shop

  # 赛季信息
  season-info:
    slot: 49
    material: CLOCK
    name: "&b%season_name%"
    lore:
      - "&7状态: %season_status%"
      - "&7剩余时间: &e%season_time_remaining%"
    condition:
      type: SEASON_ACTIVE
      true-material: CLOCK
      false-material: BARRIER
      false-name: "&7暂无赛季"
      false-lore:
        - "&c当前没有活跃的赛季"

  # 关闭按钮
  close:
    slot: 45
    material: BARRIER
    name: "&c关闭"
    lore:
      - "&7点击关闭菜单"
    action:
      type: CLOSE

# 进度条配置
progress-bar:
  enabled: true
  start-slot: 19
  end-slot: 25
  filled:
    material: LIME_STAINED_GLASS_PANE
    name: "&a进度"
  empty:
    material: WHITE_STAINED_GLASS_PANE
    name: "&7进度"
  lore:
    - "&7等级 %level% 进度"
    - "&e%current_exp% &7/ &e%next_level_exp% &7经验"
    - "&7(%progress_percent%%)"
```

<h2 id="任务界面配置">
  任务界面配置
</h2>

```yaml theme={null}
# gui/quests.yml

title: "&6&l任务列表"
size: 54  # 6 行

# 边框填充
border:
  enabled: true
  material: GRAY_STAINED_GLASS_PANE
  name: " "

# 分类筛选按钮（顶部行）
categories:
  all:
    slot: 2
    material: NETHER_STAR
    name: "&f全部任务"
    lore:
      - "&7显示所有可用任务"
      - ""
      - "&7总数: &e%total_quests%"
    filter: ALL
    selected-glow: true

  daily:
    slot: 3
    material: SUNFLOWER
    name: "&e日常任务"
    lore:
      - "&7每日重置的任务"
      - ""
      - "&7可用: &e%daily_available%"
      - "&7已完成: &a%daily_completed%"
      - ""
      - "&7重置时间: &e%daily_reset_time%"
    filter: DAILY
    selected-glow: true

  weekly:
    slot: 4
    material: EMERALD
    name: "&a周常任务"
    lore:
      - "&7每周重置的任务"
      - ""
      - "&7可用: &e%weekly_available%"
      - "&7已完成: &a%weekly_completed%"
      - ""
      - "&7重置时间: &e%weekly_reset_time%"
    filter: WEEKLY
    selected-glow: true

  seasonal:
    slot: 5
    material: DIAMOND
    name: "&b赛季任务"
    lore:
      - "&7整个赛季的任务"
      - ""
      - "&7可用: &e%seasonal_available%"
      - "&7已完成: &a%seasonal_completed%"
    filter: SEASONAL
    selected-glow: true

  challenge:
    slot: 6
    material: BLAZE_POWDER
    name: "&c挑战任务"
    lore:
      - "&7高难度挑战任务"
      - ""
      - "&7可用: &e%challenge_available%"
      - "&7已完成: &a%challenge_completed%"
    filter: CHALLENGE
    selected-glow: true

# 任务显示区域（第2-5行，第1-7列）
quest-area:
  start-slot: 19
  end-slot: 44
  exclude-borders: true  # 跳过边框槽位

# 任务物品显示
quest-display:
  # 类型标签
  type-tags:
    DAILY: "&e[日常]"
    WEEKLY: "&a[周常]"
    SEASONAL: "&b[赛季]"
    CHALLENGE: "&c[挑战]"
    STORY: "&d[剧情]"

  # 任务名称格式
  name-format: "%type_tag% %quest_name%"

  # 状态指示器
  status:
    available:
      glow: false
      lore-append:
        - ""
        - "&a进行中"
    completed:
      glow: true
      overlay-material: LIME_STAINED_GLASS_PANE
      lore-append:
        - ""
        - "&a✓ 已完成 - 点击领取奖励!"
    claimed:
      glow: false
      name-prefix: "&7&m"
      lore-append:
        - ""
        - "&7奖励已领取"

# 分页设置
pagination:
  enabled: true
  quests-per-page: 21  # 7 列 x 3 行
  prev-button:
    slot: 45
    material: ARROW
    name: "&e上一页"
  next-button:
    slot: 53
    material: ARROW
    name: "&e下一页"

# 导航按钮
navigation:
  back:
    slot: 49
    material: DARK_OAK_DOOR
    name: "&c返回主菜单"
    lore:
      - "&7点击返回"
    action:
      type: OPEN_GUI
      gui: main
```

<h2 id="奖励界面配置">
  奖励界面配置
</h2>

```yaml theme={null}
# gui/rewards.yml

title: "&6&l奖励轨道"
size: 54  # 6 行

# 边框填充
border:
  enabled: true
  material: GRAY_STAINED_GLASS_PANE
  name: " "

# 分页设置
pagination:
  levels-per-page: 7
  prev-button:
    slot: 45
    material: ARROW
    name: "&e上一页"
    lore:
      - "&7点击查看上一页"
  next-button:
    slot: 53
    material: ARROW
    name: "&e下一页"
    lore:
      - "&7点击查看下一页"
  page-info:
    slot: 49
    material: PAPER
    name: "&e第 %page% 页"
    lore:
      - "&7共 %total_pages% 页"

# 档位标题行（第0行，槽位1-7）
tier-headers:
  start-slot: 1
  slot-spacing: 2  # 每隔2个槽位
  unlocked:
    glow: true
    lore-append:
      - ""
      - "&a已解锁"
  locked:
    glow: false
    lore-append:
      - ""
      - "&c未解锁"
      - "&7价格: &e%tier_price%"

# 等级指示器（第0列）
level-indicators:
  reached:
    material: LIME_DYE
    name: "&e等级 %level%"
    lore:
      - "&a已达成"
  not-reached:
    material: GRAY_DYE
    name: "&7等级 %level%"
    lore:
      - "&c未达成"
      - "&7需要 &e%exp_required% &7经验"

# 奖励显示
rewards:
  # 可领取状态
  claimable:
    glow: true
    name-prefix: "&a"
    lore-append:
      - ""
      - "&a▸ 点击领取!"

  # 已领取状态
  claimed:
    name-prefix: "&7&m"
    overlay-material: LIME_STAINED_GLASS_PANE
    lore-append:
      - ""
      - "&7✓ 已领取"

  # 档位锁定状态
  tier-locked:
    name-prefix: "&c"
    overlay-material: RED_STAINED_GLASS_PANE
    lore-append:
      - ""
      - "&c需要 %tier_name% 档位"

  # 等级未达成状态
  level-locked:
    name-prefix: "&8"
    lore-append:
      - ""
      - "&c需要达到等级 %level%"

  # 空奖励槽位
  empty:
    material: LIGHT_GRAY_STAINED_GLASS_PANE
    name: "&7-"
    lore: []

# 导航按钮
navigation:
  back:
    slot: 48
    material: DARK_OAK_DOOR
    name: "&c返回主菜单"
    lore:
      - "&7点击返回"
    action:
      type: OPEN_GUI
      gui: main

# 一键领取按钮
claim-all:
  slot: 50
  material: HOPPER
  name: "&a一键领取"
  lore:
    - "&7领取当前页所有可领取的奖励"
    - ""
    - "&7可领取: &e%claimable_count%"
  action:
    type: CLAIM_ALL_PAGE
```

<h2 id="动态内容">
  动态内容
</h2>

<h3 id="条件显示">
  条件显示
</h3>

```yaml theme={null}
items:
  premium_info:
    slot: 31
    # 条件：拥有 premium 档位时显示
    condition: "has_tier:premium"
    material: GOLD_BLOCK
    name: "&6高级会员"
    lore:
      - "&a您已拥有高级通行证！"

  premium_buy:
    slot: 31
    # 条件：没有 premium 档位时显示
    condition: "!has_tier:premium"
    material: GOLD_INGOT
    name: "&6购买高级通行证"
    lore:
      - "&7点击购买"
    action: "buy_tier:premium"
```

<h3 id="动态物品数量">
  动态物品数量
</h3>

```yaml theme={null}
items:
  exp_display:
    slot: 13
    material: EXPERIENCE_BOTTLE
    # 数量显示为等级
    amount: "%level%"
    name: "&a经验瓶"
```

<h2 id="声音效果">
  声音效果
</h2>

```yaml theme={null}
sounds:
  # 打开 GUI
  open: "BLOCK_CHEST_OPEN"
  # 点击按钮
  click: "UI_BUTTON_CLICK"
  # 领取奖励
  claim: "ENTITY_PLAYER_LEVELUP"
  # 购买成功
  purchase: "BLOCK_NOTE_BLOCK_PLING"
  # 操作失败
  error: "ENTITY_VILLAGER_NO"
```

<h2 id="下一步">
  下一步
</h2>

<Columns cols={2}>
  <Card title="查看命令" icon="terminal" href="/arcpass/commands">
    命令和权限列表
  </Card>

  <Card title="PlaceholderAPI 变量" icon="code" href="/arcpass/placeholders">
    可用的占位符变量
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.