GUI 自定义

Assiah 的所有界面都通过 YAML 配置文件定义，你可以自由修改布局、图标、文本和交互动作。

GUI 文件列表

文件	界面
`ui/mailbox-main.yml`	邮箱主界面（邮件列表）
`ui/mailbox-detail.yml`	邮件详情
`ui/mailbox-compose.yml`	撰写邮件
`ui/mailbox-draft.yml`	草稿箱
`ui/mailbox-admin.yml`	管理员面板
`ui/mailbox-preference.yml`	偏好设置

配置结构

每个 GUI 配置文件包含以下部分：

# 窗口标题（支持占位符）
title: "&8邮箱 {folder-display} &7[{page}/{max-page}]"

# 内部标识名
display: mailbox-main

# 行数（1~6）
rows: 6

# 字符布局
layout:
  - "IIIIIIIII"
  - "IMMMMMMMI"
  - "IMMMMMMMI"
  - "IMMMMMMMI"
  - "IPMMMMMNI"
  - "WBSDATREC"

# 图标定义
icons:
  I:
    role: STATIC
    material: GRAY_STAINED_GLASS_PANE
    name: " "
  M:
    role: MAIL_LIST
    template: mail-summary
    actions:
      left:
        - "mail:open-detail"

# 模板定义
templates:
  mail-summary:
    material: PAPER
    name: "&f{mail.title}"
    lore:
      - "&7发件人: &f{mail.sender}"

下图展示了图标在 GUI 中的实际效果：

按钮图标效果

对应的 YAML 配置：

按钮配置示例

字符布局系统

layout 中的每个字符对应 icons 中的一个图标定义。每行 9 个字符，对应 GUI 中的 9 个槽位。

例如邮箱主界面的布局：

IIIIIIIII    ← 顶部装饰
IMMMMMMMI    ← 邮件列表（7 个槽位）
IMMMMMMMI    ← 邮件列表
IMMMMMMMI    ← 邮件列表
IPMMMMMNI    ← 上一页 + 邮件列表 + 下一页
WBSDATREC    ← 功能按钮行

底部按钮行：W=写信, B=返回, S=已发送, D=草稿, A=归档, T=回收站, R=刷新, E=偏好, C=关闭

图标角色 (Role)

每个图标必须指定一个 role，决定该槽位的功能类型：

通用角色

角色	说明
`STATIC`	静态装饰物品，无交互
`CLOSE`	关闭 GUI
`BACK`	返回上一级界面
`REFRESH`	刷新当前页面数据
`PREV_PAGE`	上一页
`NEXT_PAGE`	下一页

邮箱主界面角色

角色	说明
`MAIL_LIST`	邮件/草稿列表槽位，动态填充
`COMPOSE`	写新邮件
`OPEN_FOLDER`	打开指定文件夹
`OPEN_DRAFT`	打开草稿箱
`OPEN_PREFERENCE`	打开偏好设置

邮件详情角色

角色	说明
`DETAIL`	邮件详情展示
`ATTACHMENT_LIST`	附件列表
`CLAIM`	领取全部附件
`DELETE`	删除邮件
`REPLY`	回复邮件
`FORWARD`	转发邮件
`ARCHIVE`	归档邮件
`RESTORE`	从回收站恢复
`MARK_UNREAD`	切换已读/未读

撰写界面角色

角色	说明
`EDIT_RECIPIENT`	编辑收件人
`EDIT_TITLE`	编辑标题
`EDIT_BODY`	编辑正文
`UPLOAD_ITEM`	上传物品附件
`UPLOAD_SOURCE_ITEM`	上传物品库物品附件（仅管理员）
`EDIT_KETHER`	编辑 Kether 脚本附件（仅管理员）
`UPLOAD_CURRENCY`	上传货币附件
`EDIT_RECEIVE_CONDITION`	编辑接收条件（仅管理员）
`EDIT_CLAIM_CONDITION`	编辑领取条件（仅管理员）
`SAVE_DRAFT`	保存草稿
`SEND_DRAFT`	发送邮件

偏好设置角色

角色	说明
`TOGGLE_PLAYER_MAIL`	切换玩家邮件接收
`TOGGLE_SYSTEM_MAIL`	切换系统邮件接收
`TOGGLE_WHITELIST`	切换白名单模式
`TOGGLE_BLACKLIST`	黑名单管理

管理员面板角色

角色	说明
`ADMIN_INSPECT`	管理员检查信息展示

动作系统

通过 actions 配置点击动作，按鼠标按键分类：

actions:
  left:
    - "mail:open-detail"
  right:
    - "mail:quick-claim"
  shift-left:
    - "mail:delete"
  shift-right:
    - "mail:archive"

动作格式为 mail:<动作名> 或 mail:<动作名>:<参数>。

可用动作

动作	说明
`mail:open-detail`	打开邮件详情
`mail:quick-claim`	快速领取附件
`mail:claim`	领取全部附件
`mail:claim-single`	领取单个附件
`mail:delete`	删除邮件
`mail:archive`	归档邮件
`mail:restore`	恢复邮件
`mail:mark-unread`	切换已读/未读
`mail:reply`	回复邮件
`mail:forward`	转发邮件
`mail:open-book`	以书本视图打开
`mail:compose`	写新邮件
`mail:open-folder:<文件夹>`	打开指定文件夹（SENT/ARCHIVE/TRASH）
`mail:open-draft`	打开草稿
`mail:delete-draft`	删除草稿
`mail:open-preference`	打开偏好设置
`mail:toggle-preference:<项>`	切换偏好（player-mail/system-mail/whitelist/blacklist）
`mail:open-filter`	关闭 GUI → 聊天栏输入筛选关键词 → 重新打开列表
`mail:toggle-select`	切换邮件多选状态（用于批量操作）
`mail:edit-recipient`	编辑收件人
`mail:edit-title`	编辑标题
`mail:edit-body`	编辑正文
`mail:upload-item`	上传物品
`mail:upload-source-item`	上传物品库物品（仅管理员，聊天栏输入物品源 ID）
`mail:edit-kether`	编辑 Kether 脚本（仅管理员，笔与书输入）
`mail:upload-currency <key>`	上传货币附件（key 对应 currency.yml 中的货币键名）
`mail:edit-receive-condition`	编辑接收条件（仅管理员，笔与书输入 Kether 脚本）
`mail:edit-claim-condition`	编辑领取条件（仅管理员，笔与书输入 Kether 脚本 + 聊天栏输入提示消息）
`mail:remove-attachment`	移除附件
`mail:save-draft`	保存草稿
`mail:send-draft`	发送邮件
`mail:page-prev`	上一页
`mail:page-next`	下一页
`mail:refresh`	刷新
`mail:back`	返回
`mail:close`	关闭

附件列表模板映射

ATTACHMENT_LIST 角色的槽位支持通过 templates 字段为不同附件类型指定不同的展示模板。

邮件详情界面

邮件详情界面的附件列表支持 5 种附件类型的模板映射：

A:
  role: ATTACHMENT_LIST
  template: attachment          # 默认兜底模板
  templates:
    ITEM: attachment-item       # 物品附件 → 显示物品材质和 Lore
    CURRENCY: attachment-currency  # 货币附件 → 显示货币名称和数量
    KETHER: attachment-kether   # Kether 附件 → 显示脚本预览
    SOURCE_ITEM: attachment-source-item  # 物品库附件 → 显示物品源标识
  actions:
    left:
      - "mail:claim-single"

物品库附件模板示例：

templates:
  attachment-source-item:
    material: ENDER_CHEST
    name: "&b{attachment.name}"
    lore:
      - "&7类型: &f{attachment.type}"
      - "&7来源: &f{attachment.source}"
      - "&7数量: &f{attachment.item.amount}"
      - "&7可领取: &f{attachment.claimable}"
      - ""
      - "&e左键领取此附件"

撰写界面

撰写界面的附件列表同样支持 templates 映射，用于展示已添加的附件。未匹配到类型模板时，回退到 template 指定的默认模板：

L:
  role: ATTACHMENT_LIST
  template: attachment-item     # 默认兜底模板
  templates:
    ITEM: attachment-item
    CURRENCY: attachment-currency
    KETHER: attachment-kether
    SOURCE_ITEM: attachment-source-item
  actions:
    right:
      - "mail:remove-attachment"

提示

支持的类型键：ITEM、CURRENCY、KETHER、SOURCE_ITEM、TEXT。你可以根据需要为每种类型配置独立的展示模板。

模板与占位符

模板用于动态内容槽位（如邮件列表、附件列表）的物品渲染。

邮件摘要占位符

占位符	说明
`{mail.title}`	邮件标题
`{mail.sender}`	发件人显示名称
`{mail.receiver}`	收件人显示名称
`{mail.status-display}`	状态文本（未读/已读/已领取等）
`{mail.time}`	格式化时间
`{mail.id}`	邮件唯一 ID
`{mail.summary}`	正文摘要

撰写界面占位符

撰写界面除了支持上述邮件摘要占位符外，还提供以下专用占位符：

占位符	说明
`{mail.recipient}`	收件人显示名称（群发时显示群发目标）
`{mail.body}`	草稿正文（截取前 120 字符）
`{attachment.count}`	当前附件总数
`{attachment.<currencyKey>}`	指定货币键名的当前数量（如 `{attachment.vault}`）
`{condition.receive.status}`	接收条件状态（`已设置` / `未设置`）
`{condition.claim.status}`	领取条件状态（`已设置` / `未设置`）
`{condition.receive.preview}`	接收条件脚本预览（前 40 字符）
`{condition.claim.preview}`	领取条件脚本预览（前 40 字符）

附件占位符

通用占位符（所有附件类型均可使用）：

占位符	说明
`{attachment.name}`	附件名称
`{attachment.type}`	附件类型显示文本
`{attachment.claimable}`	是否可领取
`{attachment.count}`	当前附件数量

物品附件 (ITEM) 额外占位符：

占位符	说明
`{attachment.item.name}`	物品显示名称
`{attachment.item.amount}`	物品数量
`{attachment.item.material}`	物品材质名称
`{attachment.lore}`	物品原始 Lore（列表占位符，展开为多行；无 Lore 时该行自动移除）

货币附件 (CURRENCY) 额外占位符：

占位符	说明
`{attachment.currency}`	货币键名（如 vault）
`{attachment.currency.name}`	货币显示名称
`{attachment.amount}`	货币数量

Kether 附件 (KETHER) 额外占位符：

占位符	说明
`{attachment.script.preview}`	脚本内容预览（截取前 40 字符）

物品库附件 (SOURCE_ITEM) 额外占位符：

占位符	说明
`{attachment.source}`	物品源标识（如 `mythicmobs:FireSword`）
`{attachment.item.amount}`	物品数量

偏好占位符

占位符	说明
`{preference.player-mail}`	玩家邮件接收状态
`{preference.system-mail}`	系统邮件接收状态
`{preference.whitelist}`	白名单模式状态
`{preference.blacklist}`	黑名单状态

管理员面板占位符

占位符	说明
`{admin.inbox}`	收件箱邮件总数
`{admin.unread}`	未读邮件数量
`{admin.trash}`	回收站邮件数量
`{admin.archive}`	归档邮件数量
`{admin.failed-claim}`	领取失败数量

分页占位符

占位符	说明
`{page}`	当前页码
`{max-page}`	总页数
`{folder-display}`	当前文件夹显示名称

子图标系统 (icons)

v1.0.9 新增了子图标功能，类似 TrMenu 的 icons 机制。你可以为任意图标定义多个条件子图标，根据 Kether 条件脚本动态切换图标的外观和动作。

配置格式

在图标定义中添加 icons 列表：

icons:
  W:
    role: COMPOSE
    material: WRITABLE_BOOK
    name: "&a写新邮件"
    lore:
      - "&7点击创建新邮件"
    actions:
      left:
        - "mail:compose"
    # 子图标列表
    icons:
      - condition: "perm *assiah.vip"    # Kether 条件脚本（必填）
        priority: 1                       # 优先级，数值越小越先匹配（可选）
        inherit: true                     # 是否继承父图标未覆盖的属性（可选，默认 false）
        material: DIAMOND                 # 覆盖材质（可选）
        name: "&6&lVIP 写信"              # 覆盖名称（可选）
        lore:                             # 覆盖描述（可选）
          - "&e尊贵的 VIP 用户"
          - "&7点击创建新邮件"
        actions:                          # 覆盖动作（可选）
          left:
            - "mail:compose"

匹配规则

子图标按 priority 升序匹配，第一个条件满足的生效
如果所有子图标条件均不满足，使用父图标的默认配置
inherit: true 时，子图标未指定的属性（material/name/lore/actions）会继承父图标
inherit: false（默认）时，子图标必须完整定义所有需要的属性

条件脚本

condition 字段使用 Kether 脚本语法，必须返回布尔值。常用示例：

# 检查权限
condition: "perm *assiah.vip"

# 检查 PAPI 变量
condition: "check papi %player_level% > 10"

GUI 文件列表​

配置结构​

字符布局系统​

图标角色 (Role)​

通用角色​

邮箱主界面角色​

邮件详情角色​

撰写界面角色​

偏好设置角色​

管理员面板角色​

动作系统​

可用动作​

附件列表模板映射​

邮件详情界面​

撰写界面​

模板与占位符​

邮件摘要占位符​

撰写界面占位符​

附件占位符​

偏好占位符​

管理员面板占位符​

分页占位符​

子图标系统 (icons)​

配置格式​

匹配规则​

条件脚本​