UI 自定义总览
Malkuth 的所有界面都可以通过 ui/ 目录下的 YAML 配置文件完全自定义，包括布局、图标、动作和模板。
每个界面配置文件由五个部分组成：title、layout、icons、template、messages。title、icons.name、icons.lore、template.name、template.lore 在完成内部占位符替换后，还会继续执行 PlaceholderAPI 解析。
layout 布局系统
每个界面通过 layout 定义格子结构。每一行是一个由 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'
图标可配置字段
| 字段 | 类型 | 说明 |
|---|---|---|
material | 字符串 | 物品材质（如 arrow、lime wool）。配置 skull_texture / texture 后可省略 |
name | 字符串 | 显示名称，支持颜色代码 |
lore | 字符串列表 | 描述文本行，支持 \n 换行 |
skull_texture | 字符串 | 自定义头颅纹理（Mojang Base64），配置后自动使用 PLAYER_HEAD |
texture | 字符串 | skull_texture 的别名，两者同时存在时 skull_texture 优先 |
color | 字符串 | 皮革盔甲颜色（格式如 255,0,0） |
nbt | Map | 附加 NBT 数据 |
actions | Map | 点击动作，key 为点击类型 |
点击类型
常用包括 left、right、shift_left、shift_right 以及 Bukkit 原生 click 名。每个动作可配置多条指令。
template 模板变量
template 定义商品/物品在 g 槽位中的展示样式：
template:
name: '&f{name}'
lore:
- '{lore}'
- '&e价格: &f{price}'
不同界面支持的模板变量各不相同，详见各界面分组页面。
MiniMessage 与传统色码
UI 标题、图标名称、Lore 和模板文本支持传统 & 色码。只有同时满足以下条件时，MiniMessage 标签才会生效：
config.yml -> minimessage.enabled已设为true。- Minecraft 服务端版本为 1.16 或更高。
- 服务端运行环境提供完整且兼容的 Adventure、MiniMessage 和 Examination 依赖。
当前允许颜色标签、文字装饰、gradient、rainbow 和 reset，例如 <red>、<#55FFAA>、<bold>、<gradient:#FF0000:#00FF00>、<rainbow>。传统 &a、&l 等色码仍然兼容；配置关闭、版本过低或依赖不可用时会自动回退到传统色码。
动作指令总表
所有界面通用的动作指令一览。
通用导航
| 指令 | 说明 |
|---|---|
page next | 下一页 |
page pre | 上一页 |
menu back | 返回上一界面 |
menu close | 关闭界面 |
command <内容> | 让玩家执行命令（如 command spawn） |
kether <脚本> | 显式执行一段 Kether 脚本；kether 前缀不会当作玩家命令处理 |
malkuth ... 是各界面代码显式接入的内部动作，只能使用本页和对应分组页面列出的完整动作。未接入的 malkuth 动作不会自动转成玩家命令或 Kether，也不会产生新功能；部分界面还会记录未识别动作警告。自定义逻辑请使用 kether <脚本>。
搜索与比价
| 指令 | 说明 |
|---|---|
malkuth search | 搜索商品 |
malkuth compare / malkuth compare open | 打开比价界面 |
malkuth compare search | 比价搜索 |
购买确认
| 指令 | 说明 |
|---|---|
malkuth confirm buy [N] | 确认购买（支持可选数量参数） |
malkuth confirm gift | 赠送给好友 |
malkuth confirm cart | 加入购物车 |
malkuth confirm action | 确认操作（玩家商店/全球市场购买） |
malkuth confirm add N | 增加购买数量 |
malkuth confirm sub N | 减少购买数量 |
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 search | 在拍卖行聊天栏输入搜索关键词 |
malkuth auction clear_search | 清除拍卖行搜索关键词 |
malkuth auction clear_seller_filter | 清除拍卖行卖家筛选 |
malkuth auction my_bids | 查看我的出价 |
malkuth auction my_items | 查看我的拍品 |
malkuth auction upload | 打开拍卖创建编辑器 |
上架创建编辑器
| 指令 | 说明 |
|---|---|
malkuth upload amount increase left / right / shift_left / shift_right | 按当前点击档位增加草稿数量 |
malkuth upload amount decrease left / right / shift_left / shift_right | 按当前点击档位减少草稿数量 |
malkuth upload input price | 输入全球市场价格、拍卖起拍价或求购单价 |
malkuth upload input amount | 输入精确数量 |
malkuth upload input buyout | 输入或清除拍卖一口价 |
malkuth upload input duration | 输入拍卖时长 |
malkuth upload input note | 输入全球求购备注 |
malkuth upload switch match_mode | 切换全球求购匹配方式 |
malkuth upload review | 校验草稿并进入共享确认页；不会直接提交 |
malkuth upload confirm_submit | 在共享确认页进入真实提交阶段 |
malkuth upload cancel | 清理当前草稿并返回来源界面 |
完整布局、变量和草稿边界见 上架创建编辑器。
玩家商店
| 指令 | 说明 |
|---|---|
malkuth player_shop edit | 编辑玩家商店 |
malkuth player_shop upload | 上架商品到玩家商店 |
malkuth player_shop search | 在玩家商店中搜索商品 |
malkuth player_shop search_seller | 在玩家商店中按卖家筛选 |
malkuth player_shop clear_filters | 清空玩家商店商品搜索与卖家筛选 |
malkuth player_shop_browse search | 在玩家商店浏览列表中搜索店主 |
全球市场
| 指令 | 说明 |
|---|---|
malkuth global_market filter | 打开 global_market_filter.yml 分页筛选类型菜单 |
malkuth global_market filter clear_all | 从筛选类型或关键词页清除关键词、卖家、分类与属性筛选 |
malkuth global_market filter search | 从筛选类型或关键词页打开搜索菜单 |
malkuth global_market category | 打开分类选择菜单 |
malkuth global_market sort | 打开 global_market_sort.yml，选择价格 / 名称排序方式 |
malkuth global_market search | 打开搜索菜单 |
malkuth global_market search_keyword | 在搜索菜单中输入物品关键词 |
malkuth global_market search_seller | 在搜索菜单中输入卖家筛选 |
malkuth global_market clear_all_filters | 清除关键词、卖家、属性、分类与排序 |
malkuth global_market clear_seller_filter | 仅清除卖家筛选 |
malkuth global_market my_uploads | 打开我的上架管理界面 |
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 renew | 续期自己的全球市场挂单 |
malkuth global_market search_similar | 按当前物品名称搜索同类挂单 |
malkuth global_market search_source | 按当前物品来源搜索同类挂单 |
全球求购
| 指令 | 说明 |
|---|---|
malkuth global_request create | 打开发布求购界面 |
malkuth global_request my_requests | 切换“全部 / 我的求购”筛选 |
malkuth global_request search | 在聊天栏输入求购搜索关键词 |
malkuth global_request clear_all_filters | 清除求购关键词、求购者和来源筛选 |
malkuth global_request sort | 切换求购列表排序方式 |
malkuth global_request submit | 对当前求购提交供货 |
malkuth global_request offers | 打开当前求购的供货申请列表 |
malkuth global_request cancel_confirm | 打开取消求购确认界面 |
malkuth global_request refresh | 刷新当前求购详情 |
malkuth global_request refresh_offers | 刷新供货申请列表 |
malkuth global_request confirm | 执行当前求购确认操作 |
malkuth global_request quantity_decrease / quantity_decrease_10 | 确认界面减少数量 |
malkuth global_request quantity_increase / quantity_increase_10 | 确认界面增加数量 |
商品编辑
| 指令 | 说明 |
|---|---|
malkuth modify price | 修改商品价格 |
malkuth modify lore | 修改商品描述 |
malkuth modify name | 修改商品名称 |
malkuth modify model_data | 修改 Custom Model Data |
malkuth modify material | 修改商品材质 |
自定义头颅 (skull_texture)
你可以通过 skull_texture 字段为任意 UI 图标设置自定义头颅材质。配置后 material 可以省略，物品会自动使用 PLAYER_HEAD。
skull_texture 的值是 Mojang Base64 皮肤纹理值，可以从 Minecraft Heads 获取。在头颅详情页找到 Value 字段，复制整段 Base64 字符串即可。
也可以使用 texture 作为别名，效果完全相同。当两者同时存在时，skull_texture 优先。
icons:
'H':
skull_texture: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvLi4uIn19fQ=="
name: '&e自定义头颅按钮'
lore:
- '&7这是一个自定义头颅图标'
actions:
left:
- 'menu close'
当 skull_texture 值无效（非合法 Base64 或不包含 textures.SKIN.url）或应用失败时，系统会优雅降级为普通图标显示。相同的 texture 值会基于 SHA-256 生成固定 UUID，保证头颅缓存的正确性。
所有 40 个 UI 配置文件的 icons 节点均支持此字段。
界面分组
Malkuth 当前提供 40 个 UI 配置文件。相比原有 34 个模板，本轮加入 upload_shop_select.yml、global_market_create.yml、auction_create.yml、upload_create_confirm.yml、global_market_filter.yml、global_market_filter_keywords.yml 六个已接入文件，按功能分为以下分组：
| 分组 | 配置文件 | 说明 |
|---|---|---|
| 确认购买界面 | confirm.yml、confirm_global_market.yml、confirm_player_shop.yml | 购买确认、数量调整、赠送、购物车 |
| 上架创建编辑器 | upload_shop_select.yml、global_market_create.yml、auction_create.yml、upload_create_confirm.yml | 商店选择、草稿编辑、精确输入、共享确认 |
| 全球市场界面 | global_market_item.yml、global_market_detail.yml、global_market_compare.yml、global_market_category.yml、global_market_search.yml、global_market_sort.yml、global_market_filter.yml、global_market_filter_keywords.yml、upload_global_market.yml | 商品列表、详情、比价、分类、搜索、分页筛选、排序、上架管理 |
| 全球求购界面 | global_request_item.yml、upload_global_request.yml、global_request_detail.yml、global_request_offers.yml、confirm_global_request.yml | 求购列表、发布、详情、供货审核、操作确认 |
| 拍卖行界面 | auction_item.yml、auction_my_bids.yml、auction_upload.yml | 拍卖物品展示、出价、拍品管理 |
| 购物车与收藏夹 | cart.yml、favorite.yml | 购物车结算、收藏管理 |
| 搜索与比价 | search.yml、price_compare.yml | 商品搜索、跨店比价 |
| 玩家商店界面 | player_shop_item.yml、browse_player_shops.yml、edit_goods.yml、upload_shop.yml、stall_model_select.yml | 玩家商店物品展示、浏览、编辑、上架、摆摊模型选择 |
| 邮箱与记录 | mailbox.yml、transaction.yml、order.yml | 邮箱领取、交易记录、挂单管理 |
| 其他模板 | autosell_chest_upgrade.yml、group_buy_detail.yml、group_buy_list.yml、group_buy_record.yml | 自动售卖箱升级界面与团购预留模板 |