也提供中文版本，请往下滑。

WebShopX v3: A Web-Driven Minecraft Store and Trading System

Official Store (B2C) + Player Market (C2C) + Auctions + Dynamic Pricing + Order Fulfillment + Admin Dashboard

WebShopX is a complete trading system: the Minecraft plugin provides business logic and APIs, while a modern web frontend serves both players and server operators. Version 3 completely rebuilds the frontend and supports three deployment modes: embedded, external, and Relay.

v3 Highlights

• SQLite works out of the box, with MySQL and MariaDB also supported
• WebShopX Relay deployment without exposing a server port
• Fixed-price listings, buy orders, four auction formats, and dynamic pricing for official products
• Dual-currency wallets, recharging, refunds, an in-game mailbox, and fallback handling for failed deliveries
• Redis-powered cross-server events and player-presence synchronization
• Plugin update checks, Relay status monitoring, and immediate reconnection
• A standalone server homepage with a visual editor and database-backed revision management

1 Runtime Requirements

Download the build that matches both your Minecraft version and server type.

Minecraft target	Java	Supported servers
1.18.2+	17	Paper / Purpur / Spigot
1.20.6+	21	Paper / Purpur / Spigot / Folia
26.1+	25	Paper / Purpur / Spigot / Folia
26.2+	25	Paper / Purpur / Spigot / Folia

• Databases: SQLite, MySQL, or MariaDB
• Optional dependencies: Vault, WebShopX-Payments, and others
• Multi-server deployments: MySQL/MariaDB + Redis
• Bundled languages: zh-CN and en-US

2 Three Web Deployment Modes

Embedded Mode

The plugin serves both the API and static web files. After installing the JAR, the site is available on port 8819 by default. This mode is ideal for single-server setups and quick deployment.

External Mode

The plugin provides the API, while Vue static files are hosted by Nginx, a hosting panel, or a CDN. This mode is designed for servers that already have a domain, reverse proxy, and TLS infrastructure.

Relay Mode

Relay mode is implemented but is still undergoing further testing. Before using it, consult the GitHub/Wiki guides or join the QQ group or Discord for assistance.

The Minecraft server establishes an outbound connection to WebShopX Relay, so neither the WebShopX port nor the Minecraft port needs to be exposed publicly. Relay instances, server bindings, and public endpoints can all be managed from the Relay website.

webshop:
  server-mode: relay

relay:
  url: "" # Leave empty to use the built-in Relay server
  access-key: "wsx_user_xxxxxxxxx"

3 Complete Trading Lifecycle

Module	Implemented capabilities
Official Store	Commands, item delivery, item recycling, potion effects, and group-buy vouchers
Dynamic Pricing	Multiple algorithms, demand pressure, price trends, and popularity decay
Player Market	Sell orders, buy orders, supply containers, automatic restocking, tags, and restriction rules
Auction System	English, Dutch, Vickrey, and Candle auctions with expiration settlement
Wallets and Payments	ShopCoin / GameCoin, Vault, currency exchange, and recharge orders
Fulfillment and Support	Automatic delivery, manual claims, mailbox fallback, refunds, and group-buy voucher redemption
Admin Dashboard	Product, order, market, user, economy, announcement, language, and theme management
Server Homepage	Standalone presentation site, visual section editing, draft publishing, revision history, and asset library
Security and Auditing	Role-based permissions, admin audit logs, and business ledger

4 Player Experience

• Sign in with a Minecraft username and a password configured in game
• View dual-currency balances, wallet transactions, orders, and notifications
• Browse the official store and purchase or recycle products
• Browse player listings and player shops with search, filters, and sorting
• Create sell or buy orders, purchase items, fulfill buy orders, and participate in auctions
• Manage personal listings, offers, and transaction history
• Request eligible refunds and recover pending deliveries or mailbox compensation
• Create recharge orders when a supported payment provider is installed
• Use the standalone server homepage to view server status, features, showcases, announcements, services, rankings, and market content

Player Market, Auctions, and Dynamic Pricing

Market Trading

• Player buy orders backed by escrowed funds
• Standard item listings and automatic restocking from supply containers
• Market tags, item and currency restrictions, listing fees, and taxes
• Market broadcasts, seller transaction logs, and scheduled settlement

Auction Algorithms

Algorithm	Rules
English Auction	Public ascending bids; the highest valid bidder wins; anti-sniping extensions are supported
Dutch Auction	The price decreases over time; the first buyer to accept the current price wins
Vickrey Auction	Sealed bids; the highest bidder wins and pays the second-highest bid
Candle Auction	The closing moment is randomized during the final stage, reducing the advantage of last-second bidding

Dynamic Pricing

Prices can respond to demand pressure generated by purchases or recycling, then decay toward an equilibrium value over time. The admin dashboard provides algorithm settings, price trends, market insights, and operational overviews.

5 Official Store

Product type	Purpose
COMMAND	Execute configured commands after purchase
GIVE_ITEM	Deliver a serialized item snapshot to the player
RECYCLE_ITEM	Accept specified items and pay the configured currency
POTION_EFFECT	Apply configured potion effects to the player
GROUP_BUY_VOUCHER	Issue a redeemable group-buy voucher

Products support stock limits, per-player purchase limits, publishing schedules, and operator notes. Orders cover creation, payment, pending claim, completion, cancellation, and refunds. If a player is offline or lacks inventory space, delivery can continue through /ws claim or the in-game mailbox.

6 Delivery System

Transaction / order
        ↓
Pending delivery ── /ws claim [token]
        ↓ Inventory unavailable during automatic delivery
In-game mailbox ── /ws mailbox (GUI) or /ws mailbox collect
        ↓
Player inventory

7 Admin Dashboard

• Product, inventory, purchase-limit, and dynamic-pricing management
• Order lookup, refunds, delivery tracking, and exception handling
• Market listings, auctions, offers, tags, and restriction-rule management
• User lookup, account unbinding, password resets, forced logout, and wallet adjustments
• Redeem codes, group-buy vouchers, recharge orders, and payment-status management
• Exchange rates, market fees, display options, and runtime business settings
• Server-wide announcements, notifications, language center, and theme center
• Standalone server homepage, visual section editing, full JSON editing, asset library, draft publishing, and revision history

Built-in role templates include SUPER_ADMIN, SHOP_ADMIN, MARKET_MODERATOR, SUPPORT_ADMIN, and AUDITOR. You can also combine permissions into custom roles as needed.

8 Databases and Server Networks

SQLite is the default option and requires no separate database service, making it suitable for single-server and lightweight deployments. SQLite supports only standalone mode.

Server networks should use a shared MySQL/MariaDB database and assign a unique server-id to each instance. Redis carries market broadcasts, cluster events, and configuration refreshes, while player-presence and business data are coordinated across backend servers.

9 In-Game Commands

The main command is /webshopx, with /ws as its alias.

Command	Description
/ws	Open the market GUI
/ws gui	Same as /ws
/ws home	Show a clickable server-homepage link in chat
/ws password <new_password>	Create or reset the web login password
/ws market	Same as /ws
/ws market sell <price> [amount] [currency]	Quickly list held items for sale
/ws market logs [count]	View recent transaction records
/ws claim [all|token]	Claim pending deliveries
/ws mailbox	Open the in-game mailbox GUI
/ws mailbox collect	Quickly collect all items from the in-game mailbox
/ws reload	Reload configuration and web resources (admin)
/ws recharge fix <orderId>	Query the payment provider and repair a recharge order (admin)
/ws gamecoin <player> <delta>	Adjust GameCoin (admin)
/ws shopcoin <player> <delta>	Adjust ShopCoin (admin)

10 Quick Start

1. Download the JAR that matches your Minecraft runtime and server type.
2. Place it in plugins/ and start the server once.
3. SQLite works immediately by default; MySQL/MariaDB is recommended for production deployments and server networks.
4. Players run /ws password <new_password> in game.
5. In embedded mode, visit http://your-server-address:8819/; the admin entry point is /admin.html.
6. After signing in with the bootstrap administrator, immediately change the default credentials and disable the bootstrap account.

For detailed configuration instructions, read the official Wiki or watch the setup tutorial. Public deployments should use HTTPS, a reverse proxy, and appropriate access controls.

11 Feedback and Community

• Video introduction
• Setup tutorial
• Official Wiki
• Issue tracker
• QQ group: 636803372
• Discord

---

WebShopX v3：Web 驱动的 Minecraft 商城与交易系统

官方商城（B2C）+ 玩家市场（C2C）+ 拍卖 + 动态定价 + 订单履约 + 管理后台

WebShopX 是一套由 Minecraft 插件提供业务逻辑和 API、由现代 Web 前端提供玩家与运营界面的完整交易系统。v3 全面重构了前端页面，并提供内置、外置和 Relay 三种部署方式。

v3 亮点

• SQLite 开箱即用，也支持 MySQL / MariaDB
• 无需开放服务器端口的 WebShopX Relay 部署
• 固定价、收购、四类拍卖和官方商品动态定价
• 双币钱包、充值、退款、邮箱和失败发货兜底
• Redis 多服事件同步与玩家在线状态管理
• 插件更新检测、Relay 状态查看与立即重连
• 独立服务器主页、可视化主页编辑器与数据库版本管理

1 运行环境

请下载与你的 Minecraft 版本和服务端类型匹配的文件。

Minecraft 目标	Java	服务端支持
1.18.2+	17	Paper / Purpur / Spigot
1.20.6+	21	Paper / Purpur / Spigot / Folia
26.1+	25	Paper / Purpur / Spigot / Folia
26.2+	25	Paper / Purpur / Spigot / Folia

• 数据库：SQLite、MySQL 或 MariaDB
• 可选依赖：Vault、WebShopX-Payments 等
• 多服部署：MySQL/MariaDB + Redis
• 内置语言：zh-CN、en-US

2 三种 Web 部署方式

内置模式

插件同时提供 API 和静态网页。安装 JAR 后即可通过默认的 8819 端口访问，适合单服和快速部署。

外置模式

插件提供 API，Vue 静态文件交由 Nginx、面板或 CDN 托管。适合已有域名、反向代理和 TLS 基础设施的服务器。

Relay 模式

该模式已经实现功能，但仍在进一步测试中。如需使用，请前往 GitHub/Wiki 查阅教程，或加入 QQ 群、Discord 获取帮助。

Minecraft 服务器主动连接 WebShopX Relay，无需向公网开放 WebShopX 或 Minecraft 端口。实例创建、服务器绑定和公网入口均可在 Relay 网页管理。

webshop:
  server-mode: relay

relay:
  url: "" # 留空使用内置 Relay 服务器
  access-key: "wsx_user_xxxxxxxxx"

3 完整交易闭环

模块	已实现能力
官方商城	指令、物品发放、物品回收、药水效果、团购券
动态定价	多算法、需求压力、价格趋势与热度衰减
玩家市场	出售、收购、供货箱、自动补货、标签、限制规则
拍卖系统	英式、荷兰式、维克里、烛台拍卖与到期结算
钱包支付	ShopCoin / GameCoin、Vault、兑换、充值订单
履约售后	自动发货、手动领取、邮箱、退款、团购券核销
运营后台	商品、订单、市场、用户、经济、公告、语言与主题管理
服务器主页	独立展示页面、可视化区块编辑、草稿发布、历史版本与资源库
安全审计	角色权限、管理员审计日志、业务账本

4 玩家端

• 使用 Minecraft 用户名和游戏内设置的密码登录
• 查看双币余额、钱包流水、订单和通知
• 浏览官方商城，购买或回收商品
• 浏览玩家市场和玩家店铺，搜索、筛选和排序
• 发布出售单或收购单，购买、供货和参与拍卖
• 管理自己的上架、报价和成交记录
• 按规则退款，领取待发货内容和邮箱补偿
• 创建充值订单（需安装可用的支付提供方）
• 通过独立服务器主页查看服务器状态、特色、作品、公告、服务、排行榜和市场内容

玩家市场、拍卖与动态定价

市场交易

• 玩家收购单与托管资金
• 普通物品上架和供货箱自动补货
• 市场标签、物品与货币限制、创建费用及税费
• 市场广播、卖家成交日志与周期性结算

拍卖算法

算法	规则
英式拍卖	公开递增出价，最高有效出价者获胜，支持反狙击延时
荷兰式拍卖	价格随时间下降，第一个接受当前价格的买家成交
维克里拍卖	密封投标，最高出价者获胜并按第二高价结算
烛台拍卖	结束时刻在最终阶段随机化，降低压秒出价优势

动态定价

可根据购买或回收产生的需求压力调整价格，并按时间向均衡值衰减。后台提供算法配置、价格趋势、市场洞察和运营概览。

5 官方商城

商品类型	用途
COMMAND	购买后执行预设指令
GIVE_ITEM	向玩家交付物品快照
RECYCLE_ITEM	回收指定物品并支付货币
POTION_EFFECT	为玩家施加指定药水效果
GROUP_BUY_VOUCHER	生成可核销的团购凭证

商品支持库存、个人限购、上下架时间和运营备注。订单覆盖创建、支付、待领取、完成、取消与退款流程；背包空间不足或玩家离线时，可通过 /ws claim 或邮箱继续交付。

6 发货系统

交易/订单
   ↓
待发货任务 —— /ws claim [token]
   ↓ 自动发货时背包无法接收
游戏信箱 —— /ws mailbox（GUI）或 /ws mailbox collect
   ↓
玩家背包

7 管理后台

• 商品、库存、限购和动态定价管理
• 订单查询、退款、交付跟踪与异常处理
• 市场上架、拍卖、报价、标签和限制规则管理
• 用户查询、解绑、重置密码、强制下线和钱包调整
• 兑换码、团购券、充值订单与支付状态管理
• 汇率、市场费用、显示选项和运行时业务设置
• 全服公告、通知、语言中心和主题中心
• 独立服务器主页、可视化区块编辑、完整 JSON 编辑、资源库、草稿发布与历史版本

内置角色模板包括 SUPER_ADMIN、SHOP_ADMIN、MARKET_MODERATOR、SUPPORT_ADMIN 和 AUDITOR，也可按需要组合自定义权限。

8 数据库与群组服

SQLite 是默认选项，无需安装独立数据库，适合单服和轻量环境。SQLite 仅支持 standalone 模式。

群组服请使用共享的 MySQL/MariaDB，并为每个实例设置唯一 server-id。Redis 用于市场广播、集群事件和配置刷新；玩家在线状态与业务数据可在多个后端服之间协调。

9 游戏内命令

主命令为 /webshopx，别名 /ws。

命令	说明
/ws	打开市场 GUI
/ws gui	与 /ws 一致
/ws home	在聊天栏显示可点击的服务器主页链接
/ws password <新密码>	创建或重置网页登录密码
/ws market	与 /ws 一致
/ws market sell <price> [amount] [currency]	快速出售手中物品
/ws market logs [count]	查看最近成交记录
/ws claim [all|token]	领取待发货内容
/ws mailbox	打开游戏信箱 GUI
/ws mailbox collect	快速领取游戏信箱中的全部物品
/ws reload	重载配置和网页资源（管理员）
/ws recharge fix <orderId>	查询支付服务并修复充值订单（管理员）
/ws gamecoin <player> <delta>	调整 GameCoin（管理员）
/ws shopcoin <player> <delta>	调整 ShopCoin（管理员）

10 快速开始

1. 下载与你的 Minecraft 运行时及服务端匹配的 JAR。
2. 放入 plugins/ 并启动一次服务端。
3. 默认 SQLite 可直接使用；生产和群组服建议改用 MySQL/MariaDB。
4. 玩家在游戏内执行 /ws password <新密码>。
5. 内置模式访问 http://服务器地址:8819/，管理入口为 /admin.html。
6. 使用首次引导管理员登录后，立即修改默认凭据并关闭引导账号。

详细配置请阅读 官方 Wiki 或观看 配置教程。公网部署请使用 HTTPS、反向代理和访问控制。

11 反馈与社区

• 视频介绍
• 配置教程
• 官方 Wiki
• 问题反馈
• QQ 群：636803372
• Discord