跳到主要内容

界面自定义

Malkuth 的所有界面都可以通过 YAML 配置文件完全自定义，包括布局、图标、动作和模板。

按当前源码，title、icons.name、icons.lore、template.name、template.lore 在完成内部占位符替换后，还会继续执行 PlaceholderAPI 解析。

layout 布局系统​

每个界面通过 layout 定义布局结构。每一行是一个由 9 个字符组成的字符串，对应箱子界面中的一行（标准箱子宽度为 9 格）：

layout:
  - '#########'
  - ' ggggggg '
  - ' ggggggg '
  - ' ggggggg '
  - ' ggggggg '
  - 'P##I#S##N'

字符含义：

  • g = 商品/物品槽位，由系统自动分页填充商品列表
  • 其他字符 = 在 icons 部分定义的功能按钮或装饰
  • 空格 = 空槽位

布局行数决定界面的行数（最多 6 行，即大箱子）。商品槽位 g 的数量决定每页显示多少商品，超出的商品自动分页。

icons 动作系统​

每个非 g 字符在 icons 中定义其材质、名称、描述和点击动作：

icons:
  '#':
    material: "gray stained glass pane"
    name: " "
  'N':
    material: "arrow"
    name: '&a下一页 →'
    lore:
      - '&7点击翻到下一页'
    actions:
      left:
        - 'page next'
      right:
        - 'page pre'
  # 自定义头颅示例
  'H':
    skull_texture: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvLi4uIn19fQ=="
    name: '&e自定义头颅'

点击键名按源码解析，常用包括 left、right、shift_left、shift_right 以及 Bukkit 原生 click 名。每个动作可配置多条指令。

可用动作指令​

以下是所有可用的动作指令一览：

通用导航​

指令说明
page next下一页
page pre上一页
menu back返回上一界面
menu close关闭界面
command <内容>让玩家执行命令（如 command spawn）

搜索与比价​

指令说明
malkuth search搜索商品
malkuth compare / malkuth compare open打开比价界面
malkuth compare search比价搜索

购买确认界面​

指令说明
malkuth confirm buy [N]确认购买（支持可选数量参数，默认模板常用 1/16/32/64）
malkuth confirm gift赠送给好友
malkuth confirm cart加入购物车
malkuth confirm action确认操作（玩家商店/全球市场购买）
malkuth confirm add N增加购买数量（N 为数字，如 add 1、add 10）
malkuth confirm sub N减少购买数量（N 为数字，如 sub 1、sub 10）
malkuth confirm input在聊天栏输入购买数量

购物车​

指令说明
malkuth cart open打开购物车
malkuth cart checkout结算购物车
malkuth cart clear清空购物车

收藏夹​

指令说明
malkuth favorite open打开收藏夹

回收​

指令说明
malkuth recycle all一键回收
malkuth recycle same同类回收（按主手物品匹配）
malkuth recycle preview预览可回收物品与预估收益
malkuth recycle rollback撤回最近一次回收

邮箱​

指令说明
malkuth mailbox claim_all一键领取所有邮件

拍卖行​

指令说明
malkuth auction my_bids查看我的出价
malkuth auction my_items查看我的拍品
malkuth auction upload上架拍卖物品

玩家商店​

指令说明
malkuth player_shop edit编辑玩家商店
malkuth player_shop upload上架商品到玩家商店

全球市场​

指令说明
malkuth global_market filter打开筛选菜单
malkuth global_market sort选择排序方式
malkuth global_market search聊天栏输入搜索关键词
malkuth global_market upload打开上架管理界面
malkuth global_market confirm在详情页购买当前挂单；若当前是自己的挂单，则改为下架处理
malkuth global_market delist在详情页下架当前挂单
malkuth global_market favorite收藏或取消收藏当前挂单
malkuth global_market compare打开当前挂单的同类比价界面
malkuth global_market edit_price关闭 GUI 并在聊天栏输入新价格
malkuth global_market search_similar按当前物品名称搜索同类挂单
malkuth global_market search_source按当前物品来源搜索同类挂单；没有来源时会回退到名称搜索

详情页本身没有单独的“打开详情”动作指令，而是由列表点击语义控制：别人商品默认左键购买、右键详情；自己的商品默认右键详情，左键行为由 detail.own-left-action 决定，Shift + 左键 固定走下架确认。

商品编辑​

指令说明
malkuth modify price修改商品价格
malkuth modify lore修改商品描述
malkuth modify name修改商品名称
malkuth modify model_data修改 Custom Model Data
malkuth modify material修改商品材质

template 模板变量​

template 定义商品在界面中的展示样式。不同界面支持不同的模板变量：

商店模板​

template:
  name: '&f{name}'
  lore:
    - '{lore}'
    - '&e价格: &f{price}'
    - '&7持有: &f{has_currency}'
    - '&7剩余: &f{limit}'
变量说明
{name}商品名称
{lore}商品描述（全部）
{lore_N}商品第 N 组描述
{price}商品价格
{has_currency}玩家持有货币数量
{limit} / {limit_remaining}剩余限购数量（所有限制中的最小值）
{amount}购买数量
{shop_player_current}商店级别 - 个人已购买数量
{shop_player_max}商店级别 - 个人最大限制
{shop_player_remaining}商店级别 - 个人剩余限制
{shop_global_current}商店级别 - 全局已购买数量
{shop_global_max}商店级别 - 全局最大限制
{shop_global_remaining}商店级别 - 全局剩余限制
{goods_player_current}商品级别 - 个人已购买数量
{goods_player_max}商品级别 - 个人最大限制
{goods_player_remaining}商品级别 - 个人剩余限制
{goods_global_current}商品级别 - 全局已购买数量
{goods_global_max}商品级别 - 全局最大限制
{goods_global_remaining}商品级别 - 全局剩余限制

确认购买界面​

变量说明
{name}商品名称
{lore}商品描述
{price}单价
{amount}购买数量
{total}总价
{balance}持有货币
{limit} / {limit_remaining}剩余限购

购物车​

变量说明
{name}商品名称
{lore}商品描述
{amount}数量
{price}单价
{subtotal}小计
{shop}来源商店
{count}购物车商品件数（用于标题）
{total}购物车合计金额（用于标题）

收藏夹​

变量说明
{lore}商品描述
{shop}来源商店
{count}收藏商品件数（用于标题）
{page}当前页码（用于标题）
{max-page}最大页数（用于标题）

邮箱​

变量说明
{lore}物品描述
{sender}发送者
{reason}原因
{message}邮件附言；为空时显示 -
{time}时间
{page}当前页码（用于标题）
{max-page}最大页数（用于标题）

交易记录​

变量说明
{type_label}交易类型
{goods_id}商品 ID
{shop}商店名称
{amount}数量
{price}价格
{seller}卖家
{time}时间

拍卖物品​

变量说明
{lore}物品描述
{start_price}起拍价
{current_price}当前价
{bidder}最高出价者
{remaining}剩余时间
{bid_percent}加价百分比

拍卖行 - 我的出价​

变量说明
{lore}物品描述
{current_price}当前价
{my_bid}我的出价
{remaining}剩余时间

拍卖行 - 我的拍品​

变量说明
{lore}物品描述
{start_price}起拍价
{current_price}当前价
{remaining}剩余时间

玩家商店​

变量说明
{lore}物品描述
{name}物品名称（主要用于确认界面标题/图标文本）
{player}商店主人名称（用于标题与图标文本）
{seller}卖家名称
{price}价格
{stock}库存数量
{action_hint}操作提示（购买/下架确认等）

全球市场​

变量说明
{lore}物品描述
{name}物品名称（主要用于确认界面标题/图标文本）
{seller}卖家名称
{price}价格
{stock}库存数量
{avg_price}近期均价（24 小时交易均价）
{action_hint}操作提示（左键购买/右键查看等）
{filter_count}当前筛选条件数量（用于主界面图标文本）
{sort_mode}当前排序模式（用于主界面图标文本）
{search_keyword}当前搜索关键词（用于主界面图标文本）
{filter}当前筛选维度名称（用于筛选子菜单标题）

全球市场详情​

变量说明
{listing_id}当前挂单唯一 ID
{seller}卖家名称
{seller_uuid}卖家 UUID
{name}物品名称
{material}物品材质
{price}当前单价
{stock}当前库存数量
{listed_time}按 detail.date-format 格式化后的上架时间
{listed_timestamp}原始毫秒时间戳
{avg_price}最近 24 小时均价；没有数据时显示语言文件里的默认文本
{source_id}当前识别到的来源 ID；关闭 show-source-id 时为空
{is_own}是否为自己的挂单
{favorite_state}当前收藏状态文本
{search_keyword}来源列表当前搜索关键词；便于在详情页标题或按钮里提示玩家
{filter_count}来源列表当前激活的筛选数量

全球市场上架管理​

变量说明
{lore}物品描述
{price}价格
{amount}数量
{player}当前玩家名称（用于图标文本）
{shop}当前商店 ID（用于图标文本）

全球市场同类比价​

变量说明
{lore}物品描述
{seller}卖家名称
{price}当前单价
{stock}当前库存
{listed_time}当前挂单的格式化上架时间
{source_id}当前挂单的来源 ID
{match_type}当前命中的匹配方式；源码当前会返回 current、source_id、display_name 或 material
{page}当前页码（用于标题）
{max-page}最大页数（用于标题）

比价​

变量说明
{lore}物品描述
{shop}商店名称
{price}单价
{currency}货币类型
{limit}限购信息

搜索结果​

变量说明
{lore}物品描述
{shop}来源商店
{goods_id}商品 ID
{tags}商品标签列表（逗号分隔）
{count}搜索结果数量（用于标题）
{page}当前页码（用于标题）
{max-page}最大页数（用于标题）

挂单​

变量说明
{matcher}匹配商品
{max_price}最高价
{amount}数量
{status}状态
{time}时间

自定义头颅 (skull_texture)​

你可以通过 skull_texture 字段为任意 UI 图标设置自定义头颅材质。配置后 material 可以省略，物品会自动使用 PLAYER_HEAD。

skull_texture 的值是 Mojang Base64 皮肤纹理值，你可以从 Minecraft Heads 获取。在头颅详情页找到 Value 字段，复制整段 Base64 字符串即可。

也可以使用 texture 作为别名，效果完全相同。当两者同时存在时，skull_texture 优先。

icons:
  'H':
    # 填写 Mojang Base64 皮肤纹理值，material 可省略
    skull_texture: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvLi4uIn19fQ=="
    name: '&e自定义头颅按钮'
    lore:
      - '&7这是一个自定义头颅图标'
    actions:
      left:
        - 'menu close'
提示

当 skull_texture 值无效（非合法 Base64 或不包含 textures.SKIN.url）或应用失败时，系统会优雅降级为普通图标显示，不会导致报错。相同的 texture 值会基于 SHA-256 生成固定 UUID，保证头颅缓存的正确性。

所有 26 个 UI 配置文件的 icons 节点均支持此字段。

UI 配置文件一览​

Malkuth 当前提供 26 个 UI 配置文件，你可以在 ui/ 目录下找到并自定义它们：

文件说明
auction_my_bids.yml拍卖行「我的出价」界面
auction_upload.yml拍卖行上架/管理界面
browse_player_shops.yml玩家商店浏览列表
confirm.yml购买确认界面（数量调整、赠送、购物车）
confirm_global_market.yml全球市场确认界面
confirm_player_shop.yml玩家商店确认界面
cart.yml购物车界面
mailbox.yml邮箱界面
favorite.yml收藏夹界面
global_market_item.yml全球市场商品列表模板
global_market_sort.yml全球市场排序菜单
search.yml搜索结果界面
transaction.yml交易记录界面
order.yml挂单列表界面
auction_item.yml拍卖物品展示模板
auction_my_bids.yml拍卖行「我的出价」界面
auction_upload.yml拍卖行上架/管理界面
autosell_chest_upgrade.yml自动售卖箱升级界面（当前更偏向预留模板）
browse_player_shops.yml玩家商店浏览列表
cart.yml购物车界面
confirm.yml购买确认界面（数量调整、赠送、购物车）
confirm_global_market.yml全球市场确认界面
confirm_player_shop.yml玩家商店确认界面
edit_goods.yml商品编辑界面
favorite.yml收藏夹界面
global_market_compare.yml全球市场同类比价界面
global_market_detail.yml全球市场详情页
global_market_item.yml全球市场商品列表模板
global_market_sort.yml全球市场排序菜单
group_buy_detail.yml团购详情界面（当前更偏向预留模板）
group_buy_list.yml团购列表界面（当前更偏向预留模板）
group_buy_record.yml团购记录界面（当前更偏向预留模板）
mailbox.yml邮箱界面
order.yml挂单列表界面
player_shop_item.yml玩家商店物品模板
price_compare.yml比价界面
search.yml搜索结果界面
transaction.yml交易记录界面
upload_global_market.yml全球市场上架管理界面
upload_shop.yml商品上架界面

完整示例：confirm.yml​

以下是购买确认界面 ui/confirm.yml 的完整配置，展示了布局、图标和模板的综合用法：

# 购买确认界面标题，{name} 为商品名称
title: '&8确认购买 &f{name}'

# 布局定义
# g = 商品预览槽位
# + / - = 数量调整按钮
# d / u = 装饰箭头（提示上下方有按钮）
# Y = 确认购买  C = 取消  G = 赠送  I = 输入数量  T = 加入购物车
layout:
  - '#########'
  - '###d#####'
  - '#-#g#+###'
  - '###u#####'
  - '#########'
  - 'C#G#I#T#Y'

icons:
  # 装饰：灰色玻璃板填充空位
  '#':
    material: "gray stained glass pane"
    name: " "

  # 增加数量：左键 +1，右键 +10
  '+':
    material: "lime stained glass pane"
    name: '&a+1'
    lore:
      - '&7左键: +1'
      - '&7右键: +10'
    actions:
      left:
        - 'malkuth confirm add 1'
      right:
        - 'malkuth confirm add 10'

  # 减少数量：左键 -1，右键 -10
  '-':
    material: "red stained glass pane"
    name: '&c-1'
    lore:
      - '&7左键: -1'
      - '&7右键: -10'
    actions:
      left:
        - 'malkuth confirm sub 1'
      right:
        - 'malkuth confirm sub 10'

  # 上方装饰箭头
  'd':
    material: "arrow"
    name: '&7数量信息'
    lore:
      - '&7点击 + 或 - 调整数量'
      - '&7或点击下方输入数量'

  # 下方装饰箭头
  'u':
    material: "arrow"
    name: '&7数量信息'
    lore:
      - '&7点击 + 或 - 调整数量'
      - '&7或点击下方输入数量'

  # 确认购买
  'Y':
    material: "lime wool"
    name: '&a确认购买'
    lore:
      - '&7左键: 购买 1'
      - '&7右键: 购买 16'
      - '&7Shift+左键: 购买 32'
      - '&7Shift+右键: 购买 64'
    actions:
      left:
        - 'malkuth confirm buy 1'
      right:
        - 'malkuth confirm buy 16'
      shift_left:
        - 'malkuth confirm buy 32'
      shift_right:
        - 'malkuth confirm buy 64'

  # 取消（返回商店）
  'C':
    material: "red wool"
    name: '&c取消'
    actions:
      left:
        - 'menu back'

  # 赠送给好友
  'G':
    material: "writable_book"
    name: '&d赠送给好友'
    lore:
      - '&7将商品作为礼物赠送'
    actions:
      left:
        - 'malkuth confirm gift'

  # 输入数量（在聊天栏输入）
  'I':
    material: "paper"
    name: '&e输入数量'
    lore:
      - '&7点击后在聊天栏输入购买数量'
    actions:
      left:
        - 'malkuth confirm input'

  # 加入购物车
  'T':
    material: "chest_minecart"
    name: '&6加入购物车'
    lore:
      - '&7加入购物车后继续购物'
    actions:
      left:
        - 'malkuth confirm cart'

# 商品预览模板（g 槽位的展示内容）
template:
  name: '&f{name}'
  lore:
    - '{lore}'
    - ''
    - '&e单价: &f{price}'
    - '&e数量: &f{amount}'
    - '&e总价: &f{total}'
    - '&7持有: &f{balance}'
    - '&7剩余限购: &f{limit_remaining}'

这个示例展示了 Malkuth UI 系统的核心设计模式：通过 layout 定义空间布局，通过 icons 赋予每个字符功能，通过 template 控制商品展示样式。你可以参照这个结构自定义任何界面。