商店模式

Malkuth 当前支持 8 种商店模式。你可以通过 shop/*.yml 顶层的 mode 字段选择模式；mode 缺省或写错时会回退为 normal。

模式一览

模式值	页面	`currency`	`goods`	适合场景
`normal`	普通商店	必填	必填	固定商品商城、礼包、权限/脚本商品、物物交换
`limit_time` / `limit-time`	限时商店	必填	必填	限时活动、节日特卖、限时抢购
`player`	玩家自制商店	必填	不读取	玩家自己上架商品、摆摊、玩家商店方块
`recycle`	回收商店	可省略	必填	服务器回收物品、按规则发放奖励
`recycle_shop` / `recycle-shop`	回收兑换商店	必填	必填	复用回收会话但要求货币上下文的回收入口
`auction`	拍卖行	必填	不读取	玩家竞价拍卖、出价记录、拍品结算
`global_market` / `global-market`	全球市场	必填	不读取	全服寄售市场、搜索、排序、筛选、均价展示
`decompose`	分解商店	必填	必填	拖入物品后按回收规则分解成奖励

通用配置

以下字段是商店配置的通用入口，具体是否生效要看对应模式页面：

字段	说明
`mode`	商店模式，支持上表中的小写值、短横线别名，以及同名枚举写法如 `LIMIT_TIME`
`enable`	商店开关，支持 Kether 表达式，例如 `true`、`false`、`perm vip.shop`
`display`	商店显示名称，用于搜索、比价、市场等展示场景；不配置时通常显示配置文件名
`on_disable`	商店关闭或 `enable` 不通过时执行的 Kether 动作
`currency`	商店货币配置；除 `recycle` 外，其余模式都必须能解析出货币
`title`	商店标题；普通分页标题常用 `{page}` / `{max-page}`，限时商店还可用 `{countdown}`
`layout`	GUI 字符布局；`g` 通常表示商品槽位，其他字符对应 `icons`
`icons`	布局中非 `g` 字符的图标与动作定义
`confirm.open`	普通购买链路的确认界面开关，可被商品级 `goods.*.confirm.open` 覆盖
`item_count_limit`	购买链路的商店级商品数量限制
`trade_amount_limit`	购买链路的商店级交易金额限制
`target_inventory`	购买发货或回收扣物的目标背包源；常用值：`vanilla` / `legendwarehouse` / `soulringx`
`refresh`	随机商品刷新配置，最常用于 `normal` / `limit_time` 这类读取 `goods` 的购买型商店
`schedule`	定时活动折扣配置；命中窗口后会给当前商店价格乘上 `discount`
`decompose`	`decompose` 模式专用配置，其他模式不会读取这部分

更多商品字段见商品配置，货币写法见货币系统。

商品展示变量

普通购买型商店的 template 与商品展示通常可以使用：

变量	说明
`{name}`	商品名称
`{lore}`	商品 lore（全部）
`{lore_N}`	商品第 N 组 lore
`{price}`	商品价格；纯物品购买模式下会显示所需物品描述
`{has_currency}`	玩家持有货币数量；纯物品购买模式下会显示已满足的物品数量
`{limit}` / `{limit_remaining}`	当前商品可购买剩余次数
`{amount}`	本次购买数量
`{buy_mode}`	当前购买模式文本（货币 / 物品 / 混合）
`{buy_items}` / `{buy_items_N}`	当前商品需要的物品描述；`N` 从 1 开始
`{currency_type}`	当前生效货币标识；商品级货币覆盖后也会跟着变化
`{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}`	商品级全局限制状态

回收模式还有额外的回收占位符，详见回收商店与回收系统。

随机商品

随机商品不是单独的商店模式，而是给读取 goods 的商店槽位追加随机结果。默认示例在 shop/random_daily.yml 与 shop/random_weekly_cron.yml。

# shop/random_daily.yml
mode: NORMAL
currency: vault
title: '&6&l每日随机商店 &7{page}/{max-page}'

refresh:
  window: DAILY

goods:
  random_weapons:
    random_pool:
      count: 7
      unique: true
      items:
        - id: 'diamond_sword_basic'
          weight: 30
        - id: 'diamond_sword_enhanced'
          weight: 15
        - id: 'mm_legendary_sword'
          weight: 5
    random_price:
      min: 100
      max: 500
    amount: 1

字段	说明
`refresh.window`	刷新窗口：`DAILY` / `WEEKLY` / `MONTHLY` / `PERMANENT` / `CUSTOM` / `CRON`
`refresh.custom_hours`	`CUSTOM` 窗口的自定义小时数
`refresh.cron_expression`	`CRON` 窗口的 Cron 表达式
`random_pool.count`	从候选池中抽取的数量
`random_pool.unique`	是否去重，默认 `true`
`random_pool.items[].id`	候选商品 ID，对应 `goods/*.yml`
`random_pool.items[].weight`	权重，越大越容易被抽中
`random_pool.items[].random_price`	候选商品级随机价格，优先于槽位级价格
`random_price.min` / `random_price.max`	槽位级随机价格范围
`random_price.decimal`	是否允许小数，默认 `false`

管理员可用 /malkuth random refresh <商店ID> [玩家] 手动刷新随机结果，用 /malkuth random info <商店ID> <玩家> 查看指定玩家的随机结果。

定时活动折扣

定时活动折扣不是独立商店模式，而是给任意商店追加一个按 Cron 生效的价格乘数。默认示例在 shop/schedule_example.yml。

schedule:
  cron: '0 0 20 * * ?'
  duration_hours: 2
  discount: 0.8

字段	说明
`schedule.cron`	Quartz Cron 表达式；命中时段开始后商店进入活动窗口
`schedule.duration_hours`	每次活动持续小时数；必须大于 `0`
`schedule.discount`	活动窗口内的价格乘数；`1.0` 不打折，`0.8` 表示八折

当前实现里，discount 会在 ShopGoods.getEffectivePrice() 的最后阶段乘到有效价格上，所以它会叠加在基础价格、条件价、随机价、动态价之后统一生效。

选择建议

想做固定菜单售卖、礼包、虚拟商品：用普通商店。
想做活动倒计时、限时折扣：用限时商店。
想让玩家自己摆摊：用玩家自制商店。
想让玩家把物品卖回服务器：用回收商店。
想保留 recycle_shop 这个模式值并强制配置货币：用回收兑换商店。
想做竞价玩法：用拍卖行。
想做全服寄售市场：用全球市场。
想做拖入物品再分解：用分解商店。

模式一览​

通用配置​

商品展示变量​

随机商品​

定时活动折扣​

选择建议​