全球市场

global_market / global-market 是全服共享的寄售市场。当前默认配置包含详情页、挂单级收藏、同类比价、来源搜索、卖家改价、分类菜单、卖家筛选、配置化属性筛选、独立排序和返回状态保留，让玩家从“只看列表”升级为“列表浏览 + 条件筛选 + 详情决策”的交易体验。

适用场景

群组服统一交易所。
RPG 装备市场：玩家根据品质、类型、等级等 Lore 关键词筛选。
生存服寄售行：玩家自由上架，其他玩家按价格排序购买。
需要右键查看详情、比价、收藏和改价的高价值物品市场。

关键配置

字段	说明
`mode`	`global_market`、`global-market` 或 `GLOBAL_MARKET`
`currency`	必填；玩家交易建议配置完整 `give`、`take`、`deny` 动作
`goods`	不读取；市场商品来自玩家上架数据
`detail.*`	控制详情页开关、打开按键、自己的商品左键行为、原物品展示和日期格式
`navigation.*`	控制详情页 / 我的上架返回时是否保留原市场页码、筛选、排序和搜索状态
`favorite.*`	控制全球市场挂单级收藏功能
`compare.*`	控制同类比价的匹配顺序与单次展示上限
`price-edit.*`	控制卖家改价、价格上下限、创建时是否复用上下限、是否保留原上架时间和管理员代改价
`purchase.*`	控制全球市场购买方式，包含整批购买和单次最大购买数量
`upload.*`	控制旧参数式 `/malkuth market upload` 的冷却与聊天确认
`expire.*`	控制挂单到期退回、到期提醒和续期
`announcement.*`	控制全球市场上架/成交公告
`categories.*`	控制自定义分类与未分类入口
`tax.*`	控制成交税，卖家实收会扣除税费
`limit.create.limit`	每个玩家可上架数量上限，支持 Kether 表达式
`limit.white_list`	允许上架的物品匹配规则
`limit.black_list`	禁止上架的物品匹配规则，命中后优先拦截
`filters.attributes`	筛选维度；当前按物品 Lore 关键词匹配，并由 `global_market_filter.yml` / `global_market_filter_keywords.yml` 分页选择
`layout`	主市场布局，`g` 展示市场商品
`icons`	建议放筛选、排序、我的上架、返回等入口

玩家能做什么

功能	入口	说明
浏览市场	打开 `global_market` 商店	查看所有玩家共享的上架商品
打开详情页	别人的商品默认右键；自己的商品默认右键或左键	查看原物品、卖家、价格、库存、上架时间、近期均价和来源识别
上架商品	我的上架页按钮、`/malkuth market gui [商店]`，或 `/malkuth market upload <商店> <价格> [数量]`	推荐用 GUI 选择物品数量和价格；参数命令保留快速上架入口
管理我的商品	上架管理界面	左键 / 右键查看详情，`Shift + 左键` 直接下架
收藏挂单	详情页 `malkuth global_market favorite`	收藏的是具体挂单 `listingId`，不是普通商店商品收藏
同类比价	详情页 `malkuth global_market compare`	先按匹配规则筛出同类挂单，再按价格升序展示
同类搜索	详情页 `malkuth global_market search_similar` / `search_source`	左键按名称搜，右键按来源搜；识别不到来源时会自动回退到名称搜索
搜索 / 筛选 / 排序	`malkuth global_market search` / `filter` / `sort`	按关键词、卖家、Lore 属性和价格 / 名称排序浏览市场
按卖家直达	`/malshop seller <全球市场ID> <卖家>`	不经过搜索菜单，直接打开指定卖家的全球市场挂单列表
分类筛选	`malkuth global_market category`	按 `categories.groups` 中的材质、来源、名称或 Lore 规则筛选挂单
卖家改价	详情页 `malkuth global_market edit_price`	支持聊天输入新价格，输入 `cancel` 可取消
购买或下架	详情页 `confirm` / `delist`	买家点击购买，卖家点击下架；管理员可用独立权限处理他人挂单
续期挂单	详情页 `malkuth global_market renew`	开启续期后，店主可延长自己的挂单到期时间
查看均价	商品模板或详情页	展示最近 24 小时成交均价
查看税收	`/malkuth tax ...`	统计全球市场成交税、卖家实收和成交额

配置示例

下面节选自默认 shop/global_market.yml：

mode: GLOBAL_MARKET

currency:
  mode: "vault"

title: '全球市场'
display: '&6全球市场'

detail:
  enabled: true
  open-click: right
  own-left-action: detail
  show-original-item: true
  show-info-on-item: false
  show-source-id: true
  date-format: 'yyyy-MM-dd HH:mm'

navigation:
  preserve-state: true
  my-uploads-back-to-market: true

favorite:
  enabled: true
  mode: listing
  cleanup-invalid-on-open: false

compare:
  enabled: true
  match-order:
    - source_id
    - display_name
    - material
  max-results-per-open: 500
  # 兼容旧配置：仍支持读取 max-scan-per-open，但建议迁移到 max-results-per-open

price-edit:
  enabled: true
  min-price: 0
  max-price: -1
  apply_to_create: false
  keep-listed-time: true
  allow-admin-edit: true

purchase:
  bulk_buy_all: true
  max_buy_per_transaction: -1

upload:
  command-cooldown-seconds: 5
  command-confirm: true

categories:
  enabled: false
  show_uncategorized: true
  uncategorized_display: '&7其他'
  uncategorized_icon: BARRIER

expire:
  enabled: true
  duration-hours: 168
  check-interval-ticks: 1200
  max-process-per-check: 100
  return-to-mailbox: true
  remind_before_hours: 24
  remind_type: CHAT
  renew:
    enabled: false
    max_times: 3
    cooldown_hours: 24
    cost: 0
    cost_mode: FIXED
    cost_percent: 5

tax:
  enabled: false
  rate: 0.0

layout:
  - '#########'
  - ' ggggggg '
  - ' ggggggg '
  - ' ggggggg '
  - ' ggggggg '
  - 'PCFSLU#BN'

icons:
  'C':
    material: "book"
    name: '&b分类'
    lore:
      - '&7当前分类: &f{category}'
      - '&7当前数量: &a{category_count}'
    actions:
      left:
        - 'malkuth global_market category'
  'F':
    material: "hopper"
    name: '&e筛选'
    actions:
      left:
        - 'malkuth global_market filter'
  'L':
    material: "name tag"
    name: '&b卖家筛选'
    lore:
      - '&7当前筛选: &f{seller_filter}'
      - '&7点击清除卖家筛选'
    actions:
      left:
        - 'malkuth global_market clear_seller_filter'
  'S':
    material: "comparator"
    name: '&e排序'
    actions:
      left:
        - 'malkuth global_market sort'
  'U':
    material: "chest"
    name: '&a我的上架'
    actions:
      left:
        - 'malkuth global_market upload'

limit:
  create:
    limit: '10'
  white_list:
    - contains_lore:
        uncolor: true
        match: 允许上架
    - contains_name:
        uncolor: true
        match: 传说
    # - source: 'mythicmobs:legendary_box'
    # - source:
    #     source: itemsadder
    #     item: weapons:legendary_blade
    # - nbt: 'malkuth_item_source=mythicmobs'
  black_list:
    - contains_lore:
        uncolor: true
        match: 不允许上架

GUI 创建与参数式上架

我的上架页的 malkuth global_market upload 动作和 /malkuth market gui [商店] 都会打开 global_market_create.yml。玩家先从背包选择物品，再编辑数量与价格；purchase.bulk_buy_all: true 时这里填写整批总价，关闭时按单价语义处理。

config.yml -> upload_entry.defaults.global_market 只在 gui 命令未指定商店时作为默认值；留空且存在多个可用全球市场时打开 upload_shop_select.yml。
config.yml -> upload_editor.input_mode 控制价格和数量输入；confirm_before_submit 控制共享 upload_create_confirm.yml。
shop/global_market.yml -> upload.command-confirm 只控制 /malkuth market upload ... 参数命令的聊天确认。
price-edit.apply_to_create: false 是兼容默认值：改价上下限只约束存量挂单改价；设为 true 后，GUI 与参数命令创建挂单也会复用 min-price / max-price。
两种入口都要求 malkuth.command.market.upload 和目标商店访问权限 malkuth.shop.<商店ID> / malkuth.shop.*；该上架权限默认 OP。
/malkuth reload 会清除尚未提交的全球市场草稿。

完整 UI 布局、动作和变量见上架创建编辑器。

1.18.0 交互升级

默认 detail.enabled: true 且 open-click: right，别人商品默认左键购买、右键看详情；自己的商品默认右键看详情，左键由 detail.own-left-action 决定是进详情还是直接下架确认。
show-original-item: true 时，详情页中间 g 槽会显示原始物品快照；show-info-on-item: true 时，会把卖家、价格、库存、均价和来源识别追加到物品 Lore 中。
navigation.preserve-state: true 与 my-uploads-back-to-market: true 会保留原市场页码、筛选、排序和搜索状态；从“我的上架”进详情再返回时，也会尽量回到你来的那一层界面。
favorite.mode: listing 表示收藏的是具体挂单而不是商品模板；挂单售出或下架后，可以配合 cleanup-invalid-on-open 自动清理失效收藏。
compare.match-order 当前支持 source_id、display_name、material 三种匹配维度；系统会先匹配，再按价格升序展示，最后才应用 max-results-per-open 上限。
price-edit.apply_to_create: false 时，价格上下限只用于存量挂单改价；设为 true 后也约束新建挂单。keep-listed-time: true 时改价不会刷新原上架时间；开启 allow-admin-edit: true 后，拥有管理员权限的玩家可以代替卖家改价，源码还会额外输出审计日志。

购买、分类与搜索

配置项	说明
`purchase.bulk_buy_all`	`true` 时，玩家上架一组物品输入整批总价，买家默认按数量购买；`false` 时兼容旧单价行为
`purchase.max_buy_per_transaction`	单次最多购买数量；`-1` 表示只受挂单剩余数量限制
`categories.enabled`	是否启用自定义分类菜单
`categories.show_uncategorized`	未匹配任何分类的物品是否进入“其他”分类
`categories.uncategorized_display`	“其他”分类显示名
`categories.uncategorized_icon`	“其他”分类图标材质
`categories.groups`	自定义分类列表，支持 `material`、`source`、`name`、`lore` 匹配

分类示例：

categories:
  enabled: true
  groups:
    weapon:
      display: '&c武器'
      icon: DIAMOND_SWORD
      lore:
        - '&7点击筛选武器类物品'
        - '&7当前商品: {count} 件'
      match:
        - 'material:*_SWORD'
        - 'material:*_AXE'
        - 'source:mythicmobs:*sword*'

搜索菜单由 global_market_search.yml 控制，支持关键词搜索、卖家搜索和一键清除所有筛选。关键词可以直接输入物品名称或描述，也可以输入 source:<来源ID> 做来源搜索。

属性筛选现在由 shop/global_market.yml -> filters.attributes 提供数据，并分别读取 ui/global_market_filter.yml 与 ui/global_market_filter_keywords.yml 展示“筛选维度 → 关键词”两级分页菜单。点击关键词后按物品 Lore 是否包含该文本筛选；这两个界面不再承担升序/降序，价格与名称排序统一交给 global_market_sort.yml。

默认配置仍兼容旧的 name + keywords 写法：

filters:
  # 词条筛选 - 根据物品 Lore 中的特定词条进行筛选
  attributes:
    - name: '品质'
      keywords:
        - '普通'
        - '稀有'
        - '史诗'
        - '传说'
    - name: '类型'
      keywords:
        - '武器'
        - '防具'
        - '饰品'
        - '消耗品'
    - name: '等级'
      keywords:
        - 'Lv.1'
        - 'Lv.10'
        - 'Lv.20'
        - 'Lv.30'
        - 'Lv.40'
        - 'Lv.50'

解析器会为未填写 id 的旧格式生成稳定的兼容 ID 并给出迁移提示。新配置可以为每个维度补充唯一 id 和可选 display；重复 ID、空名称或空关键词列表会被跳过。

到期退回与续期

expire 用于避免全球市场挂单长期堆积。开启后，过期挂单会自动下架并通过邮箱退回给卖家。

配置项	说明
`expire.enabled`	是否启用挂单到期处理
`expire.duration-hours`	每个挂单保留多久，按上架时间计算
`expire.check-interval-ticks`	到期扫描间隔
`expire.max-process-per-check`	单次扫描最多处理多少个过期挂单
`expire.return-to-mailbox`	是否退回邮箱；关闭后不会执行自动到期处理
`expire.remind_before_hours`	到期前多少小时提醒卖家，`0` 表示不提醒
`expire.remind_type`	提醒方式：`CHAT`、`ACTION_BAR`、`TITLE`
`expire.remind_message`	提醒文本，支持 `{item_name}`、`{amount}`、`{price}`、`{remaining}`、`{expire_time}`、`{shop}`、`{listing_id}`
`expire.renew.enabled`	是否允许玩家续期自己的挂单
`expire.renew.max_times`	最大续期次数，`-1` 表示不限制；当前计数为运行期内存计数，重启后重置
`expire.renew.cooldown_hours`	同一挂单两次续期之间的冷却时间
`expire.renew.cost`	固定续期费用
`expire.renew.cost_mode`	`FIXED` 固定金额，`PERCENT` 按挂单价格百分比
`expire.renew.cost_percent`	百分比续期费用，`5` 表示挂单价格的 5%

续期入口一般放在详情页按钮中，动作是 malkuth global_market renew。玩家必须是挂单主人，并拥有 malkuth.market.renew 权限。

详情页和列表可用的到期变量：

变量	说明
`{expire_time}`	到期时间文本；未启用时显示“永不过期”
`{expire_remaining}`	剩余时间文本
`{renew_enabled}`	是否启用续期
`{renew_available}`	当前挂单是否可续期
`{renew_cost}`	本次续期费用
`{renew_count}`	当前已续期次数
`{renew_max_times}`	最大续期次数
`{renew_cooldown_remaining}`	续期冷却剩余时间
`{renew_state}`	当前续期状态提示

公告与税收

全球市场公告配置在 announcement.upload 与 announcement.sold：

announcement:
  upload:
    enabled: false
    scopes:
      server:
        enabled: true
        message: '&6[全球市场] &f{seller_name} &7上架了 &f{item_name} x{amount}&7，售价 &e{price}&7！'
        click_action: 'command inline "malshop open global_market"'
    cooldown_seconds: 0
    min_price: 0

公告范围支持 server、bc、world、permission。常用占位符包括 {shop}、{shop_display}、{listing_id}、{item_name}、{material}、{amount}、{stock}、{seller}、{seller_uuid}、{buyer}、{buyer_uuid}、{price}、{listing_price}、{total_price}。

全球市场成交税使用 tax.*，买家按挂单价格付款，卖家实收会扣除税费，并写入税收流水。完整写法见成交税。

上传限制与排查

limit.white_list、limit.black_list 复用和玩家商店相同的 matcher 语法，支持 source、!source、nbt、!nbt、Lore / 名称关键词等规则。
当前上传拦截会优先给出更具体的拒绝原因，例如“来源不允许”“缺少所需标签”“已被服务器标记为不可交易”。
服主排查全局市场上传限制时，建议先用 /malkuth source all 看当前物品能识别到哪些来源，再用 /malkuth itemdebug 查看 source tag / source id tag 等基础信息。

运行时权限

权限	说明
`malkuth.globalmarket.detail`	查看全球市场详情页
`malkuth.globalmarket.favorite`	收藏或取消收藏全球市场挂单
`malkuth.globalmarket.compare`	打开全球市场同类比价界面
`malkuth.globalmarket.search-similar`	在详情页按名称 / 来源搜索同类挂单
`malkuth.globalmarket.edit-price`	修改自己的全球市场挂单价格
`malkuth.globalmarket.admin.edit-price`	允许管理员修改任意全球市场挂单价格
`malkuth.globalmarket.admin.delist`	允许管理员下架任意全球市场挂单
`malkuth.market.renew`	允许玩家续期自己的全球市场挂单

当前实现注意点

global_market 不读取 goods，所有商品都来自玩家上架数据库。
普通收藏夹 favorite.yml 和全球市场挂单收藏是两套数据：前者收藏商店商品，后者收藏具体挂单。
详情页“按来源搜索”内部会把搜索词改成 source:<完整来源ID>；如果当前物品无法识别来源，会提示后回退到按名称搜索。
/malshop seller <全球市场ID> <卖家> 会直接进入带卖家筛选的市场列表；卖家筛选先尝试精确玩家名 / UUID，再按玩家名模糊匹配。
compare.max-results-per-open 是展示上限，不是“先扫多少条再匹配”的老语义；旧配置 max-scan-per-open 仍兼容读取，但建议尽快迁移。
卖家改价默认要求 malkuth.globalmarket.edit-price；管理员代改价和下架他人挂单则分别要求 malkuth.globalmarket.admin.edit-price 与 malkuth.globalmarket.admin.delist。
自定义 PAPI 货币做玩家交易时，建议同时配置 give、take、deny，避免扣款成功但提示不完整。
expire.renew.max_times 与冷却记录当前保存在运行期内存中，服务器重启后会重置。
categories.enabled: false 时，分类按钮会提示未启用并返回市场列表。

适用场景​

关键配置​

玩家能做什么​

配置示例​

GUI 创建与参数式上架​

1.18.0 交互升级​

购买、分类与搜索​

到期退回与续期​

公告与税收​

上传限制与排查​

运行时权限​

当前实现注意点​

相关页面​