MatrixShop

中文优先的 Minecraft GUI 经济与商业插件
Chinese-first Minecraft GUI economy and commerce plugin

MatrixShop 将系统商店、玩家商店、全局市场、拍卖、箱子商店、面对面交易、购物车和交易记录整合到同一个项目中，面向 Paper、Bukkit、Spigot 和 Folia 服务端生态。

文档	更新日志	Releases	依赖
Docs	Release Notes	GitHub Releases	MatrixLib 1.5.0

中文简介

MatrixShop 是一款面向生存服、经济服和商业玩法场景的综合交易插件。
当前主线重点包括：

• 统一经济模块与货币优先级
• 共享货币定义迁移到 MatrixLib
• SystemShop/goods/*.yml 仓库式商品定义
• product / group / pool 三种 SystemShop 资源模型
• SystemShop 定时刷新区域与后台刷新管理
• 统一命令入口、菜单框架和权限校验
• SQLite / MySQL 数据层与文件回退机制
• bStats 统计与部署分布遥测

English Overview

MatrixShop is a modular commerce plugin for survival and economy servers. It provides a unified stack for shop browsing, listing, trading, checkout, and record tracking, with a Chinese-first default resource set and current documentation aligned to the main branch.

核心模块 / Core Modules

• Economy
• SystemShop
• PlayerShop
• GlobalMarket
• Auction
• ChestShop
• Transaction
• Cart
• Record
• Menu

兼容性测试

版本	兼容性
1.7.0	Paper 1.21.11 smoke boot 通过

SystemShop 重点

SystemShop 当前推荐把商品定义集中放在 SystemShop/goods/*.yml，再由 SystemShop/shops/*.yml 通过 goods: 引用。

支持的可复用资源：

• product
• group
• pool

默认示例池文件：

SystemShop/goods/weapon_refresh_pool_example.yml

默认 weapon 分类中也已经带了可直接启用的刷新示例。

后台维护流程

当前推荐的管理员维护流：

• /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]

折扣系统

SystemShop 现在支持把折扣规则直接写在 price 键下：

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

支持能力：

• 兼容旧写法 price: 420
• 支持 percent、amount-off、surcharge
• 多条百分比折扣按相加计算
• 支持 Kether 条件判断
• 支持 whitelist、blacklist 控制折扣重叠
• 刷新池价格对象会和商品本体折扣规则合并

条件税系统

以下模块现在支持条件税配置：

• PlayerShop
• GlobalMarket
• Auction
• Transaction
• ChestShop

税规则当前支持：

• Enabled
• Mode
• Value
• Priority
• Condition

示例：

Tax:
  Enabled: true
  Mode: percent
  Value: 3.0
  Rules:
    vip:
      Enabled: true
      Priority: 100
      Mode: percent
      Value: 1.0
      Condition:
        - "perm 'group.vip'"

构建与运行信息

• Build target: Bukkit API 1.12.2
• Required dependency: MatrixLib 1.5.0
• Supported economy backends: Vault / PlayerPoints / Placeholder-based custom currencies
• Database: SQLite / MySQL
• Optional sync layer: Redis
• Shared currency file: plugins/MatrixLib/Economy/currency.yml

构建命令：

./gradlew build

运行产物：

build/libs/MatrixShop-1.7.0-all.jar

bStats 遥测

• Plugin ID: 30502
• 遥测通过 MatrixLib 的 MatrixBStats API 注册

当前图表：

Chart ID	类型	含义
database_backend	SimplePie	当前运行后端
configured_database_backend	SimplePie	当前配置后端
enabled_module_count	SingleLineChart	已启用模块数量
enabled_modules	AdvancedPie	已启用模块分布
systemshop_category_count	SingleLineChart	SystemShop 分类数量
systemshop_goods_count	SingleLineChart	SystemShop 商品数量
economy_currency_count	SingleLineChart	当前经济货币数量
economy_currency_modes	AdvancedPie	经济货币模式分布

预留图表位：

预留 Chart ID	计划用途
refresh_area_count	统计定时刷新区域数量
tax_rule_count	统计条件税规则数量
warehouse_delivery_mode	统计仓库投递策略分布

自动更新

MatrixShop 当前接入 MatrixLib 的共享更新器。

• 检查：/matrixlib update check MatrixShop
• 审批下载：/matrixlib update approve MatrixShop
• 更新包下载到 plugins/update/

稳定 API 命名空间

MatrixShop 当前新增稳定公开层：

• com.y54895.matrixshop.api
• com.y54895.matrixshop.api.model
• com.y54895.matrixshop.api.warehouse

文档入口

• 快速开始
• 配置与系统
• 模块总览
• 商店与模块详解
• 更新日志
• bStats 与遥测

Search Keywords

• English: Minecraft shop plugin, GUI shop plugin, auction plugin, player market plugin, trade plugin, Vault economy plugin, Paper plugin, Folia plugin
• 中文: 商店插件, GUI 商店插件, 拍卖插件, 玩家市场插件, 交易插件, 经济插件, 中文服插件, Paper 插件, Folia 插件