SystemShop

入口文件

SystemShop 的主要文件是：

SystemShop/settings.yml
SystemShop/goods/*.yml
SystemShop/shops/*.yml
SystemShop/ui/shop.yml
SystemShop/ui/confirm.yml
SystemShop/ui/goods-browser.yml
SystemShop/ui/goods-editor.yml
SystemShop/ui/goods-shops.yml

默认主分类来自顶层 config.yml：

system-shop:
  default-category: weapon

分类与 `shopId`

当前默认示例有：

SystemShop/shops/weapon.yml
SystemShop/shops/food.yml
SystemShop/shops/material.yml

这里的文件名就是可打开的分类 ID，例如：

/ms system open weapon
/ms open systemshop:weapon

商品定义

当前推荐结构是把商品单独放进 goods 目录，然后在分类文件中引用：

# SystemShop/shops/weapon.yml
goods:
  - iron_sword
  - bow

# SystemShop/goods/iron_sword.yml
id: iron_sword
material: 'IRON_SWORD'
amount: 1
price: 120
buy-max: 16
name: '&f铁剑'

每个商品通常至少要明确：

material
amount
price
buy-max

可选字段包括：

item
name
lore
currency

price 当前支持两种写法：

price: 120

price:
  base: 120
  discounts:
    - id: vip
      percent: 10
      condition:
        - "perm 'group.vip'"
    - id: event
      amount-off: 5
    - id: night-surge
      surcharge: 8

折扣规则说明：

percent
- 百分比折扣，多个命中规则按百分比相加
amount-off
- 固定减免
surcharge
- 固定加价
condition
- Kether 条件列表，不写则视为始终命中
whitelist
- 指定当前规则只允许与哪些折扣 id 叠加
blacklist
- 指定当前规则不能与哪些折扣 id 叠加

当前行为：

百分比折扣总和上限为 100
最终成交价不会低于一个最小正价
商品页、确认页和实际扣费都使用折后最终价

叠加控制示例：

price:
  base: 420
  discounts:
    - id: vip
      percent: 10
      condition:
        - "perm 'group.vip'"
    - id: svip
      percent: 15
      blacklist:
        - vip
      condition:
        - "perm 'group.svip'"
    - id: mvp
      percent: 20
      blacklist:
        - svip
      condition:
        - "perm 'group.mvp'"

按上面这个例子：

SVIP 命中时不会再叠加 VIP
MVP 命中时不会再叠加 SVIP
如果你希望某条规则只允许和特定折扣共存，可以改用 whitelist

goods 目录当前还支持两种可复用资源：

商品组
随机池

示例：

# SystemShop/goods/starter_weapons.yml
id: starter_weapons
Kind: group
entries:
  - wooden_sword
  - iron_sword

# SystemShop/goods/weapon_refresh_pool_example.yml
id: weapon_refresh_pool_example
Kind: pool
entries:
  iron_sword_offer:
    goods: iron_sword
    weight: 10
    price: 99

兼容说明：旧版 shops/*.yml 中直接内联 goods.<id> 的写法仍然可以读取，但新配置不建议继续这样写。

管理员维护流

当前后台命令已经拆成两步：

先把主手物品保存到 goods 仓库
再把已保存商品挂到某个系统商店分类

对应命令：

/matrixshopadmin goods ui [page]
/matrixshopadmin goods save <price> [buy-max] [product-id]
/matrixshopadmin goods add <category> <product-id>
/matrixshopadmin goods select <category> <product-id>
/matrixshopadmin goods edit <price|buy-max|currency|name|item|remove> ...

当前还支持系统商店刷新管理命令：

/matrixshopadmin refresh list [category]
/matrixshopadmin refresh run <category> [icon]

后台 UI 文件分别负责：

goods-browser.yml
- 展示 goods 仓库分页列表，并从列表进入编辑
goods-editor.yml
- 调整价格、限购、主手物品同步和上架入口
goods-shops.yml
- 选择某个 goods 当前挂载到哪些系统商店分类

刷新区域

当前已经实现一套 SystemShop 刷新基础能力，刷新规则直接挂在 icons.<char>.refresh 下。

示例结构：

icons:
  'g':
    material: 'AIR'
    mode: 'goods'
    refresh:
      Enabled: true
      Cron: '0 0 6 * * ?'
      Timezone: 'Asia/Shanghai'
      Same-For-Players-In-Group: true
      groups:
        default:
          Enabled: true
          Random-Refresh: true
          Pick: 2
          Pool-Ref: 'weapon_refresh_pool_example'

字段含义：

Same-For-Players-In-Group
- true 时，同组玩家共用一份刷新结果
- false 时，同组玩家各自独立生成结果
groups.<id>.Match-Script
- 使用 Kether 脚本匹配当前玩家是否命中该组
groups.<id>.Pool-Ref
- 引用 goods 目录中的 Kind: pool 文件
groups.<id>.goods
- 非随机模式下直接引用静态商品或商品组

刷新池条目的 price 同样支持对象结构，并会与商品本体中的 discounts 合并结算。

默认资源里已经带了一个关闭状态的注释示例：

SystemShop/shops/weapon.yml

菜单渲染规则

入口菜单通常会在 layout 里放一个 mode: goods 的图标槽位，例如：

icons:
  'g':
    material: 'AIR'
    mode: 'goods'

商品显示名称和 Lore 则来自 template：

template:
  name: '&f{name}'
  lore:
    - '&7价格: &e{price} {currency}'

购买确认流

当前主流程是：

打开某个分类页面
点击商品
进入确认界面
在确认界面里选择：
- 直接购买
- 加入购物车
- 增减购买数量

对应命令接口在代码里是：

/ms system confirm buy
/ms system confirm cart
/ms system confirm amount add <number>

因此如果你要自定义 UI，最好围绕这一条确认流来设计，而不是假定 SystemShop 会直接在第一页完成所有交易。

入口文件​

分类与 shopId​

商品定义​

管理员维护流​

刷新区域​

菜单渲染规则​

购买确认流​