GUI 配置

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

文件位置

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

基本结构

# 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%"

十六进制 RGB 色彩 v1.9.2

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

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

槽位编号

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

也可以使用多个槽位：

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: " "

点击动作

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

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

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

变量占位符

GUI 支持以下内置变量：

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

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

截图展示

主菜单配置示例

# 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%%)"

任务界面配置

# 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

奖励界面配置

# 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

动态内容

条件显示

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"

动态物品数量

items:
  exp_display:
    slot: 13
    material: EXPERIENCE_BOTTLE
    # 数量显示为等级
    amount: "%level%"
    name: "&a经验瓶"

声音效果

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

快速开始

安装配置

配置文件

使用指南

开发者 API

帮助

文件位置

基本结构

十六进制 RGB 色彩 v1.9.2

槽位编号

点击动作

变量占位符

截图展示

主菜单配置示例

任务界面配置

奖励界面配置

动态内容

条件显示

动态物品数量

声音效果

下一步

查看命令

PlaceholderAPI 变量

​文件位置

​基本结构

​十六进制 RGB 色彩 v1.9.2

​槽位编号

​点击动作

​变量占位符

​截图展示

​主菜单配置示例

​任务界面配置

​奖励界面配置

​动态内容

​条件显示

​动态物品数量

​声音效果

​下一步

查看命令

PlaceholderAPI 变量

文件位置

基本结构

十六进制 RGB 色彩 v1.9.2

槽位编号

点击动作

变量占位符

截图展示

主菜单配置示例

任务界面配置

奖励界面配置

动态内容

条件显示

动态物品数量

声音效果

下一步