SuperStocks
一款适用于 Paper/Purpur 服务器的 Minecraft 虚拟股票投资插件。可将真实股市行情同步至服务器,或创建完全模拟的本地市场。玩家通过箱子 GUI 或命令进行交易,所有交易均通过 Vault 经济系统进行结算。
专为希望增加长期经济玩法、投资系统、排行榜竞争、虚拟金融事件或高风险高回报机制的服务器而设计。它不会修改真实股票数据,但可以按比例缩放价格和波动性以适配您服务器的经济规模。
SuperStocks 仅供娱乐,不构成投资建议。
功能特性
- 通过腾讯财经获取真实股票行情(无需 API 密钥)。
- 支持 A 股、港股和美股,预配置了 60 只股票。
- 可配置的随机游走模拟本地虚拟市场。
- 本地市场支持牛市/熊市/中性市场模式。
- 支持分页、确认对话框和价格迷你图的箱子 GUI 交易。
- 提供买入、卖出、做空、报价、投资组合、排行榜等命令。
- 限价单、止损单和止盈单自动化订单。
- 支持保证金要求的卖空与强制平仓。
- 包含虚拟资本、赛季和 Vault 奖励的投资竞赛。
- IPO 新股发行,支持认购、按比例分配及退款。
- 股票凭证作为可交易的实体物品。
- BossBar 实时钉选显示股价。
- 市场综合指数与定期市场报告。
- 管理员 GUI 面板与审计日志查询。
- Vault 经济集成(兼容 EssentialsX Economy)。
- PlaceholderAPI 支持。
- 使用 SQLite 存储所有持仓、交易、订单和审计数据。
- 内置 13 种语言文件。
- 基于未实现盈亏(P&L)的赢家与输家排行榜。
- 可配置的分层损失惩罚系统。
- 熔断机制与报价异常保护。
- 可选的市场交易时间限制。
- 配置迁移与启动验证。
环境要求
| 项目 |
要求 |
| 服务端 |
兼容 Paper / Purpur |
| Java |
Java 21 |
| 必需 |
Vault + 一个兼容 Vault 的经济插件 |
| 推荐 |
EssentialsX Economy |
| 可选 |
PlaceholderAPI |
| 数据库 |
SQLite(自动创建) |
| 网络 |
获取真实股票行情时需要(腾讯 API) |
推荐环境:
- Minecraft 1.21.x Paper / Purpur
- Java 21
- Vault
- EssentialsX + EssentialsX Economy
- PlaceholderAPI(用于记分板、菜单、聊天显示)
安装指南
- 安装
Vault。
- 安装
EssentialsX Economy 或其他兼容 Vault 的经济插件。
- (可选)安装
PlaceholderAPI。
- 将
SuperStocks.jar 放入服务端的 plugins 文件夹中。
- 启动服务器以生成默认配置文件。
- 根据需要修改配置(然后执行
/stocks reload):
plugins/SuperStocks/config.yml
plugins/SuperStocks/Language/
plugins/SuperStocks/CustomMarkets/
首次启动后,您应该能看到以下文件:
plugins/SuperStocks/config.yml
plugins/SuperStocks/stocks.db
plugins/SuperStocks/Language/zh_CN.yml
plugins/SuperStocks/CustomMarkets/example.yml
快速入门
如果您只想让插件运行起来:
- 确认 Vault 经济系统正常工作。
- 保持默认语言设置:
language: zh_CN
- 保持默认行情提供商:
stock-provider:
active: tencent
-
高风险功能默认已禁用——无需更改。
-
在游戏中执行:
/stocks sync
/stocks
如果在 GUI 中看到股票行情并且可以买卖,则基本设置已成功。随后您可以逐步启用波动增强、本地市场和损失惩罚等功能。
命令列表
玩家命令
| 命令 |
描述 |
/stocks |
打开股票交易 GUI |
/stocks help |
显示帮助信息 |
/stocks open |
打开股票 GUI |
/stocks quote <symbol> |
查看股票行情 |
/stocks buy <symbol> <shares> |
买入股票 |
/stocks sell <symbol> <shares> |
卖出股票 |
/stocks short <symbol> <shares> |
建立空头头寸 |
/stocks cover <id> [shares] |
平掉(回补)空头头寸 |
/stocks portfolio |
查看文本格式的投资组合 |
/stocks history <symbol> |
查看 24 小时价格走势历史 |
/stocks stats |
查看个人投资统计 |
/stocks watch add <symbol> |
添加到自选股 |
/stocks watch remove <symbol> |
从自选股移除 |
/stocks watch list |
查看自选股列表 |
| `/stocks alert <symbol> <above |
below> <price>` |
/stocks order buy <symbol> <shares> <price> [seconds] |
创建限价买单 |
/stocks order sell <symbol> <shares> <price> [seconds] |
创建限价卖单 |
/stocks order stop-loss <symbol> <shares> <price> [seconds] |
创建止损单 |
/stocks order take-profit <symbol> <shares> <price> [seconds] |
创建止盈单 |
/stocks order list |
查看挂单列表 |
/stocks order cancel <id> |
取消订单 |
/stocks rank winners |
查看顶级投资者 |
/stocks rank losers |
查看垫底投资者 |
/stocks index |
查看市场指数 |
/stocks pin <symbol> |
将股价钉选至 BossBar |
/stocks unpin |
移除 BossBar 钉选 |
/stocks report |
查看市场报告 |
/stocks competition list |
列出竞赛活动 |
/stocks competition join <id> |
加入竞赛 |
/stocks competition buy <id> <symbol> <shares> |
在竞赛中买入 |
/stocks competition sell <id> <symbol> <shares> |
在竞赛中卖出 |
/stocks certificate issue <symbol> <shares> |
将持仓转换为凭证物品 |
/stocks certificate list |
列出您的凭证 |
/stocks ipo list |
列出 IPO 发行 |
/stocks ipo subscribe <id> <shares> |
认购 IPO |
示例:
/stocks quote sh600519
/stocks buy sh600519 10
/stocks sell sh600519 5
/stocks short usTSLA 5
/stocks cover 1
/stocks portfolio
/stocks rank winners
管理员命令
| 命令 |
权限 |
描述 |
/stocks sync |
superstocks.admin |
强制同步行情 |
/stocks status |
superstocks.admin |
查看系统状态 |
/stocks pause |
superstocks.admin |
暂停所有交易 |
/stocks resume |
superstocks.admin |
恢复交易 |
/stocks penalty history <player> |
superstocks.admin |
查看玩家处罚历史 |
/stocks admin portfolio <player> |
superstocks.admin |
查看玩家持仓组合 |
/stocks admin give <player> <symbol> <shares> |
superstocks.admin |
向玩家授予持仓 |
/stocks admin remove <player> <symbol> <shares> |
superstocks.admin |
从玩家移除持仓 |
/stocks admin clear <player> |
superstocks.admin |
清除玩家所有持仓 |
/stocks admin panel |
superstocks.admin |
打开管理员 GUI |
/stocks admin audit [player] [action] |
superstocks.admin |
查询审计日志 |
/stocks competition create <name> <days> <capital> |
superstocks.admin |
创建竞赛 |
/stocks competition end <id> |
superstocks.admin |
结束竞赛并发放奖励 |
/stocks ipo create <symbol> <name> <market> <price> <total> <max> |
superstocks.admin |
创建 IPO(首次公开募股) |
/stocks ipo cancel <id> |
superstocks.admin |
取消 IPO |
/stocks reload |
superstocks.admin |
重载配置、语言、市场和服务 |
权限说明
| 权限 |
默认拥有者 |
描述 |
superstocks.use |
所有人 |
使用 GUI 和玩家命令 |
superstocks.admin |
OP |
使用管理员命令 |
superstocks.penalty.exempt |
OP |
免除亏损处罚 |
GUI 概览
主屏幕 — 市场条目、持仓按钮、赢家/输家排行榜、自选股列表、系统统计信息。
市场界面 — 显示股票名称、代码、当前价格、涨跌额、涨跌幅以及最后更新时间。支持对股票众多的市场进行分页浏览。
股票详情页 — 提供快速买入和快速卖出按钮(3 种预设数量)、24 小时价格走势迷你图以及价格历史摘要。
交易确认对话框 — 当预估交易总额超过配置阈值(默认为 1000)时弹出,防止意外进行大额交易。
自选股 — 一个个人页面,仅显示玩家通过 /stocks watch add 添加的股票。
持仓组合 — 显示所有当前持仓的成本基础、市值以及未实现盈亏。
管理面板 — 总持仓、活跃玩家数、总交易次数、上次同步时间、交易暂停状态以及 Vault 状态的概览。
所有 GUI 的尺寸、材质和槽位布局均可在 config.yml 中配置。预设交易金额默认为 [1, 10, 100],可根据你的经济体系规模进行调整——对于高货币值的服务器,建议设置为 [10, 100, 1000]。
行情提供商
默认:腾讯财经(无需 API 密钥)。
stock-provider:
active: tencent
refresh-seconds: 300
timeout-seconds: 8
log-success: true
推荐设置:
| 设置项 |
推荐值 |
备注 |
refresh-seconds |
300 - 600 |
不要设置过低——避免触发 API 频率限制 |
timeout-seconds |
8 - 15 |
如果网络不稳定,请增加此值 |
log-success |
true |
有助于监控同步健康状况 |
默认接口端点:
sources:
tencent:
display-name: "Tencent Finance"
endpoint: "https://qt.gtimg.cn/q={symbols}"
encoding: "GBK"
symbol-separator: ","
max-symbols-per-request: 80
user-agent: "SuperStocks/1.0"
已为东方财富 (Eastmoney)、同花顺 (THS)、雪球 (Xueqiu) 和新浪 (Sina) 预留了占位符条目。内置解析器仅处理腾讯的 v_symbol="...~..." 格式。如果切换数据源,请使用能输出相同格式的兼容代理。
真实股票市场
在 config.yml 的 markets 部分进行配置。
示例:
markets:
cn:
display-name: "A股"
icon: EMERALD
symbols:
- "sh600519"
- "sz000001"
hk:
display-name: "港股"
icon: GOLD_INGOT
symbols:
- "hk00700"
us:
display-name: "美股"
icon: DIAMOND
symbols:
- "usAAPL"
腾讯股票代码格式:
| 市场 |
格式 |
示例 |
| 上海 A 股 |
sh + 代码 |
sh600519 |
| 深圳 A 股 |
sz + 代码 |
sz000001 |
| 香港 |
hk + 代码 |
hk00700 |
| 美国 |
us + ticker |
usAAPL |
建议:
- 每个市场从 10-30 只股票开始。
- 股票过多会增加同步时间和 API 负载。
- 避免移除玩家已经持有的股票的代码——孤立的持仓将不会出现在排行榜或估值中。
本地自定义市场
SuperStocks 读取以下目录中的 .yml 文件:
plugins/SuperStocks/CustomMarkets/
每个文件定义一个本地虚拟市场。首次启动时会生成一个示例文件:
plugins/SuperStocks/CustomMarkets/example.yml
本地市场不调用外部 API。它们使用接近真实市场行为的随机游走模型:
new price = old price × (1 + drift% + random volatility%)
本地价格也经过 gameplay-volatility 处理,因此本地市场和真实市场共享相同的游戏内波动规则。
全局开关
custom-markets:
enabled: true
global-tick-seconds: 300
指导建议:
| 玩法风格 |
global-tick-seconds |
| 稳定型 |
600 - 1800 |
| 正常 |
300 - 600 |
| 快节奏 |
60 - 180 |
市场文件示例
market:
id: local_tech
display-name: "本地科技股"
icon: AMETHYST_SHARD
enabled: true
simulation:
tick-seconds: 300
tick-limit-percent: 15
regimes:
enabled: true
duration-seconds: 3600
stocks:
local_chip:
symbol: "lcCHIP"
name: "Block Chip Inc."
enabled: true
initial-price: 120.0
min-price: 10.0
max-price: 1000.0
drift-percent-per-tick: 0.03
volatility-percent: 2.0
本地股票参数
| 设置项 |
说明 |
建议 |
symbol |
股票代码 |
使用前缀以避免冲突,例如 lcCHIP |
name |
显示名称 |
在 GUI 中显示 |
initial-price |
起始价格 |
与服务器经济规模相匹配 |
min-price |
价格下限 |
保持在 0 以上 |
max-price |
价格上限 |
防止价格失控 |
drift-percent-per-tick |
长期趋势 |
通常为 -0.2 到 0.2 |
volatility-percent |
随机波动强度 |
稳定型 0.5-1.5,正常型 1.5-3.0,高风险型 3.0-8.0 |
提示:
- 本地市场非常适合用于服务器自建公司、城镇经济、活动股票或剧情驱动的经济体系。
- 对于希望长期呈上涨趋势的股票,给予较小的正数
drift-percent-per-tick(例如 0.02)。
- 对于高风险股票,提高
volatility-percent,但保持 min-price 和 max-price 作为安全护栏。
- 不要将
drift-percent-per-tick 设置得过高,否则价格会迅速偏离预期范围。
游戏内波动增强
真实股票通常每日小幅波动,这在 Minecraft 经济系统中往往显得微不足道。gameplay-volatility 将基础价格转换为更具戏剧性的游戏内价格。
处理顺序:
基础报价 → 价格乘数 → 随机偏移 → 游戏内显示与交易价格
配置:
gameplay-volatility:
price-multiplier:
enabled: false
multiplier: 1.0
random-adjustment:
enabled: false
min-percent: -3.0
max-percent: 3.0
refresh-seconds: 300
safety:
min-price: 0.01
max-price: 1000000000.0
价格乘数
price-multiplier:
enabled: true
multiplier: 5.0
游戏内价格 = 基础价格 × 乘数。
| 服务器类型 |
multiplier |
| 原版规模经济 |
1.0 - 5.0 |
| 普通经济 |
5.0 - 20.0 |
| 高通胀经济 |
20.0 - 100.0 |
如果不确定,请保持禁用状态,观察交易体验后再启用。
随机调整
random-adjustment:
enabled: true
min-percent: -5.0
max-percent: 5.0
refresh-seconds: 300
每只股票获得独立的随机偏移量(例如 -5% 至 +5%),每隔 refresh-seconds 重新生成一次。
| 风格 |
min-percent |
max-percent |
refresh-seconds |
| 稳定型 |
-2.0 |
2.0 |
600 - 1800 |
| 正常型 |
-5.0 |
5.0 |
300 - 600 |
| 激进型 |
-10.0 |
10.0 |
60 - 180 |
安全边界
safety:
min-price: 0.01
max-price: 1000000000.0
- 保持
min-price 为 0.01。
- 根据经济规模设置
max-price,以防止错误配置造成的损害。
推荐组合
普通生存经济服务器:
gameplay-volatility:
price-multiplier:
enabled: true
multiplier: 5.0
random-adjustment:
enabled: true
min-percent: -5.0
max-percent: 5.0
refresh-seconds: 300
快节奏投资服务器:
gameplay-volatility:
price-multiplier:
enabled: true
multiplier: 20.0
random-adjustment:
enabled: true
min-percent: -10.0
max-percent: 10.0
refresh-seconds: 120
自动订单、止损与止盈
SuperStocks 支持自动订单功能,允许玩家提前设定买卖条件。
orders:
enabled: true
max-open-per-player: 10
automation:
check-seconds: 30
订单类型:
| 类型 |
命令 |
说明 |
| 限价买入 |
/stocks order buy <symbol> <shares> <price> [seconds] |
当价格达到触发价时自动买入 |
| 限价卖出 |
/stocks order sell <symbol> <shares> <price> [seconds] |
当价格达到触发价时自动卖出 |
| 止损单 |
/stocks order stop-loss <symbol> <shares> <price> [seconds] |
当价格下跌至限制损失时自动卖出 |
| 止盈单 |
/stocks order take-profit <symbol> <shares> <price> [seconds] |
当价格上涨以锁定利润时自动卖出 |
辅助命令:
/stocks order list
/stocks order cancel <id>
机制说明:
- 限价买单会预先预留预估成本;若订单过期或被取消,资金将退还。
- 卖出/止损/止盈订单会检查可用持仓,以防止超卖。
- 订单每
automation.check-seconds 秒检查一次。
orders.max-open-per-player 限制每位玩家可持有的未成交订单数量。
建议:
- 普通服务器:
max-open-per-player: 5 - 10。
- 投资导向服务器:
10 - 20。
- 不要将
automation.check-seconds 设置为低于 10,以避免过度的数据库扫描。
价格提醒与自选股
玩家可以追踪感兴趣的股票,并在价格目标达成时收到通知。
自选股命令:
/stocks watch add <symbol>
/stocks watch remove <symbol>
/stocks watch list
提醒命令:
/stocks alert <symbol> above <price>
/stocks alert <symbol> below <price>
配置:
alerts:
enabled: true
主 GUI 中也设有自选股入口。自选股帮助玩家追踪关键股票;提醒功能可与限价/止损/止盈订单配合使用。
报价安全与熔断机制
公共服务器应保持这些选项开启,以保护经济系统免受 API 异常、玩家刷屏或错误配置的影响。
报价异常保护:
quote-safety:
reject-stale-quotes: true
max-quote-age-seconds: 900
reject-abnormal-change: true
max-change-percent-per-sync: 25.0
circuit-breaker:
enabled: true
stock-max-change-percent: 15.0
freeze-seconds: 600
| 设置项 |
说明 |
建议值 |
reject-stale-quotes |
拦截过期的报价交易 |
公共服务器建议启用 |
max-quote-age-seconds |
报价过期阈值 |
刷新间隔的 2-3 倍 |
reject-abnormal-change |
拒绝单次同步中的价格异常飙升 |
启用 |
max-change-percent-per-sync |
单次同步允许的最大变动幅度 |
普通服务器设为 20 - 30 |
circuit-breaker.enabled |
在游戏内价格出现异常波动时冻结交易 |
启用 |
freeze-seconds |
冻结持续时间 |
300 - 900 |
交易频率限制:
trading:
paused: false
cooldown-milliseconds: 1000
max-trades-per-minute: 20
max-shares-per-trade: 10000
max-position-value: 0.0
| 设置项 |
说明 |
建议值 |
paused |
全局交易暂停 |
维护期间切换此选项 |
cooldown-milliseconds |
玩家交易之间的最小间隔 |
500 - 2000 |
max-trades-per-minute |
每名玩家每分钟最大手动交易次数 |
10 - 30 |
max-shares-per-trade |
单次交易的最大股数 |
匹配你的经济规模 |
max-position-value |
每名玩家单只股票的最大市值(0 = 无限制) |
防止垄断 |
管理员命令:
/stocks pause
/stocks resume
/stocks status
手续费、短期税与分红
基础交易手续费:
economy:
transaction-tax-percent: 0.5
min-shares: 1
large-trade-threshold-shares: 1000
large-trade-extra-tax-percent: 0.2
建议:
transaction-tax-percent:普通服务器设为 0.2 - 1.0。
- 大额交易额外税费旨在抑制高频鲸鱼玩家的交易行为。
- 提高
min-shares 以匹配你的经济规模。
短期税:
economy:
short-term-tax:
enabled: false
minimum-holding-hours: 24
percent: 1.0
当卖出持仓时间少于最低期限的头寸时,会收取额外费用。鼓励长期持有。
分红:
dividends:
enabled: false
interval-hours: 168
yield-percent: 0.5
minimum-holding-hours: 24
| 设置项 |
说明 |
建议值 |
interval-hours |
发放间隔 |
168 = 每周一次 |
yield-percent |
支付的市场价值百分比 |
0.1 - 1.0 |
minimum-holding-hours |
符合资格的最小持仓时长 |
防止最后一刻买入套利 |
⚠️ 分红会持续向经济体注入资金。默认禁用。
亏损惩罚
loss-penalty 会在玩家投资组合亏损时触发后果。惩罚根据亏损百分比层级进行选择,然后作为 Vault 提现或控制台命令执行。
默认禁用:
loss-penalty:
enabled: false
亏损计算
使用当前游戏内价格:
成本基数 = 股数 × 平均成本
市值 = 股数 × 当前价格
亏损金额 = max(0, 成本基数 - 市值)
亏损百分比 = 亏损金额 ÷ 成本基数 × 100%
层级配置
loss-penalty:
check-interval-seconds: 600
player-cooldown-seconds: 3600
tiers:
light:
enabled: true
min-loss-percent: 5.0
max-loss-percent: 10.0
fixed-amount: 0.0
percent-of-loss: 0.5
percent-of-portfolio-value: 0.0
max-amount: 1000.0
插件会选择与当前亏损百分比匹配的最高 min-loss-percent 层级。
惩罚公式:
收费 = fixed-amount + 亏损额 × percent-of-loss% + 组合价值 × percent-of-portfolio-value%
层级建议:
| 层级 |
亏损 % |
percent-of-loss |
percent-of-portfolio-value |
max-amount |
| light |
5% - 10% |
0.5 - 1.0 |
0 - 0.2 |
玩家日均收入的 0.5-1 倍 |
| normal |
10% - 20% |
1.0 - 3.0 |
0 - 0.5 |
玩家日均收入的 1-2 倍 |
| severe |
20%+ |
2.0 - 6.0 |
0.2 - 1.0 |
玩家日均收入的 2-5 倍 |
Vault 提现
loss-penalty:
actions:
vault-withdraw:
enabled: false
never-negative-balance: true
建议:
- 在普通服务器上保持
never-negative-balance: true。
- 不要在公共生存服务器的第一天就启用重度惩罚。
- 先从仅通知开始,观察玩家亏损情况,然后逐步启用提现功能。
控制台命令
loss-penalty:
actions:
commands:
enabled: false
list:
- "effect give {player} minecraft:slowness 30 0"
可用变量:
| 变量 |
说明 |
{player} |
玩家名称 |
{uuid} |
玩家 UUID |
{tier} |
触发的层级 ID |
{loss} |
当前亏损金额 |
{loss_percent} |
当前亏损百分比 |
{portfolio_value} |
当前组合市值 |
{cost} |
当前成本基数 |
{vault_penalty} |
本轮 Vault 扣款金额 |
玩家通知
loss-penalty:
actions:
notify:
enabled: true
message: "&c您的投资组合下跌了 {loss} ({loss_percent}%),触发了 {tier} 层级的惩罚。扣款:{vault_penalty}。"
此消息位于 config.yml 中,您可以直接编辑它以符合您服务器的风格和需求。
做空
玩家借入股票进行高价卖出,然后在低价买回以归还。空头头寸需要缴纳保证金,如果价格上涨过多,将面临强制平仓。
short-selling:
enabled: true
max-shares-per-position: 10000
check-seconds: 120
interest-percent-per-day: 0.0 # 0 = 无利息
margin:
required-percent: 50 # 保证金 = 头寸价值 × 比率
liquidation-percent: 50 # 当亏损达到保证金 × 比率时自动平仓
命令:
/stocks short <symbol> <shares> # 开空仓
/stocks cover <id> [shares] # 平掉全部或部分空仓
机制:
- 开仓做空会冻结保证金;平仓后返还。
- 如果股价上涨至强平阈值,仓位将被强制平仓,保证金归零。
- 默认日利息为 0% —— 无隐性资金损耗。
- 支持部分平仓。
投资竞赛
创建季节性竞赛,参与者支付报名费获得等额虚拟资金,比拼收益率并赢取 Vault 奖励。
competition:
enabled: true
rewards:
- "1: 5000" # 第一名奖励
- "2: 2000" # 第二名
- "3: 1000" # 第三名
玩家命令:
/stocks competition list
/stocks competition join <id>
/stocks competition buy <id> <symbol> <shares>
/stocks competition sell <id> <symbol> <shares>
管理员命令:
/stocks competition create <name> <days> <start-capital>
/stocks competition end <id>
机制说明:
- 竞赛使用独立的虚拟投资组合 —— 真实持仓不受影响。
- 结束竞赛时,系统会自动按当前市场价格对所有参与者的持仓进行估值、排名并发放奖励。
- 请根据服务器经济规模调整奖励金额。
IPO 发行
管理员可为本地市场股票创建 IPO(首次公开募股)。玩家在发行窗口期内认购;发行结束后按比例分配股份。
玩家命令:
/stocks ipo list
/stocks ipo subscribe <id> <shares>
管理员命令:
/stocks ipo create <symbol> <name> <market> <price> <total-shares> <max-per-player>
/stocks ipo cancel <id>
机制说明:
- IPO 认购会预先从 Vault 扣除资金。分配完成后,多余资金将退还。
- 超额认购的 IPO 将按比例缩减分配额度;未分配的资金将予以退还。
- 已分配的份额直接存入玩家的投资组合中。
股票凭证
玩家可将持仓转换为可交易的凭证物品,从而实现玩家间交易、箱子商店或拍卖行交易。
/stocks certificate issue <symbol> <shares> # 转换为物品
/stocks certificate list # 查看你的凭证
在空中右键点击凭证物品即可将其兑换回你的投资组合中的份额。凭证可在玩家之间自由交易。
BossBar、指数与报告
BossBar 固定显示 —— 将某只股票的实时价格固定在屏幕顶部:
/stocks pin <symbol> # 固定显示
/stocks unpin # 移除
进度条颜色随价格方向变化(绿色表示上涨,红色表示下跌),进度条长度反映日内波动幅度。
市场指数 —— 查看各市场的平均价格:
/stocks index
市场报告 —— 生成文本形式的摘要报告:
/stocks report
管理面板与审计日志
管理 GUI —— 可视化概览总持仓、活跃玩家数量、交易记录、同步状态、交易暂停状态以及 Vault 健康度:
/stocks admin panel
审计日志 —— 查询操作历史:
/stocks admin audit [player] [action]
审计动作类型包括:BUY(买入)、SELL(卖出)、ORDER_CREATED(订单创建)、ORDER_EXECUTED(订单执行)、ADMIN_GIVE(管理员发放)、ADMIN_REMOVE(管理员移除)、ADMIN_CLEAR(管理员清空)、SHORT_OPEN(开仓做空)、SHORT_COVER(平仓做空)、SHORT_LIQUIDATED(做空强平)、COMPETITION_CREATE(创建竞赛)、COMPETITION_JOIN(加入竞赛)、IPO_CREATE(创建 IPO)、IPO_ALLOCATED(IPO 分配)、CERT_REDEEM(凭证兑换)等。
排行榜
两个排行榜:
| 榜单 |
命令 |
描述 |
| 赢家榜 |
/stocks rank winners |
按未实现利润排名(从高到低) |
| 输家榜 |
/stocks rank losers |
按未实现亏损排名(从高到低) |
排行榜依赖于缓存报价。未能成功同步的股票将被排除在该周期的估值之外。
语言设置
在 config.yml 中设置:
language: zh_CN
语言文件位于:
plugins/SuperStocks/Language/
内置语言列表:
| 代码 |
语言 |
zh_CN |
简体中文 |
zh_HK |
繁體中文(香港) |
zh_MO |
繁體中文(澳門) |
zh_TW |
繁體中文(台灣) |
en_US |
English |
ja_JP |
日本語 |
ko_KR |
한국어 |
ar_SA |
العربية |
de_DE |
Deutsch |
es_ES |
Español |
fr_FR |
Français |
pt_BR |
Português do Brasil |
ru_RU |
Русский |
缺失的键值在运行时将回退至 en_US。如需添加自定义语言,请复制任意现有语言文件,重命名并编辑文本内容,然后在 config.yml 中设置该语言代码,最后运行 /stocks reload 命令。
PlaceholderAPI
| 占位符 |
描述 |
%superstocks_cash% |
Vault 余额 |
%superstocks_portfolio_value% |
当前投资组合市值 |
%superstocks_total_value% |
现金 + 投资组合价值 |
%superstocks_profit% |
未实现盈亏 |
%superstocks_profit_percent% |
未实现收益率百分比 |
%superstocks_shares_<symbol>% |
持有的特定股票数量 |
示例:
%superstocks_profit_percent%
%superstocks_shares_usAAPL%
数据存储
SuperStocks 使用 SQLite 存储持仓和交易数据。
database:
file: "stocks.db"
默认位置:
plugins/SuperStocks/stocks.db
建议:
- 定期备份
stocks.db 文件。
- 服务器运行时请勿直接编辑数据库文件。
- 删除数据库将清除所有玩家的持仓记录和交易历史。
重载配置
/stocks reload
重载内容包括:
config.yml
- 当前语言文件
- 实时市场列表
- 本地自定义市场文件
- 报价提供者参数
- 游戏内波动率设置
- 亏损惩罚配置
- 交易费用及最低交易量限制
若修改了数据库文件路径,则需要完全重启服务器才能生效。
推荐配置
稳定生存服
适用于正常生存经济环境 —— 股票作为辅助活动。
gameplay-volatility:
price-multiplier:
enabled: false
random-adjustment:
enabled: true
min-percent: -2.0
max-percent: 2.0
refresh-seconds: 900
loss-penalty:
enabled: false
普通经济服
适用于股票为核心玩法的服务器。
gameplay-volatility:
price-multiplier:
enabled: true
multiplier: 5.0
random-adjustment:
enabled: true
min-percent: -5.0
max-percent: 5.0
refresh-seconds: 300
loss-penalty:
enabled: false
高风险投资服务器
适用于以交易、排名和风险机制为核心的服务器。
gameplay-volatility:
price-multiplier:
enabled: true
multiplier: 20.0
random-adjustment:
enabled: true
min-percent: -10.0
max-percent: 10.0
refresh-seconds: 120
loss-penalty:
enabled: true
check-interval-seconds: 300
player-cooldown-seconds: 3600
高风险配置应配合清晰的公告、规则或教程,以便玩家了解惩罚机制。
市场时间(可选)
将交易限制在现实市场时间内。默认禁用(支持 24/7 全天候交易)。
market-hours:
cn:
enabled: false
timezone: "Asia/Shanghai"
open: "09:30"
close: "15:00"
weekends: false
closed-action: "DENY"
closed-action:DENY(禁止所有交易)或 SELL_ONLY(仅在休市期间允许卖出)。
市场事件(可选)
随机发生的“突发新闻”事件,会导致本地市场价格剧烈波动。默认禁用。
market-events:
enabled: false
chance-percent-per-tick: 2.0
min-impact-percent: -5.0
max-impact-percent: 5.0
announce-threshold-percent: 3.0
当事件影响幅度超过阈值时,将向全服广播公告。
常见问题
无法交易某只股票?
该股票可能尚未同步报价。请尝试执行:
/stocks sync
/stocks quote <symbol>
如果仍然没有数据,请检查服务器对报价 API 的网络访问情况,并确认股票代码是否正确。
排行榜显示无数据?
排行榜要求玩家持有已缓存报价的头寸。本地股票至少需要一次模拟刻;真实股票需要先成功同步一次。
Vault 或 EssentialsX 经济系统不工作?
请确认:
- 已安装 Vault。
- 已安装基于 Vault 的经济插件(例如 EssentialsX Economy)。
- Vault 能够识别该经济提供者。
- 控制台中无经济插件加载错误。
切换语言后未生效?
请验证 config.yml 中的语言代码,例如:
language: en_US
然后运行:
/stocks reload
价格波动似乎过大?
如果启用了 random-adjustment,这是正常现象。如需降低波动,可缩小 min-percent / max-percent 的范围,或增加 refresh-seconds 的数值。
本地市场会影响真实股票报价吗?
不会。本地市场使用 CustomMarkets/ 目录下的独立配置,且从不调用外部 API。它们与真实报价一样,均经过相同的 gameplay-volatility 处理流程。
免责声明
SuperStocks 是一款用于 Minecraft 服务器的虚拟投资娱乐插件。它不提供、不构成也不暗示任何现实世界的投资建议。真实股票报价 API 可能受第三方稳定性、访问限制或字段变更的影响。请设置合理的同步间隔,并遵守适用的服务条款。
SuperStocks
A Minecraft virtual stock investment plugin for Paper/Purpur servers. Sync real stock quotes into your server or create fully simulated local markets. Players trade through chest GUIs or commands, with all transactions settled via Vault economy.
Designed for servers looking to add long-term economy gameplay, investment systems, leaderboard competition, virtual finance events, or high-risk/high-reward mechanics. It does not alter real stock data but can scale prices and volatility to fit your server's economy scale.
SuperStocks is for entertainment purposes only and does not constitute investment advice.
Features
- Real stock quotes via Tencent Finance (no API key required).
- A-share, HK, and US markets with 60 pre-configured stocks.
- Local virtual markets with configurable random-walk simulation.
- Bull/bear/neutral market regimes for local markets.
- Chest GUI trading with pagination, confirmation dialogs, and price sparklines.
- Commands for buy, sell, short, quote, portfolio, rankings, and more.
- Limit orders, stop-loss, and take-profit automated orders.
- Short selling with margin requirements and forced liquidation.
- Investment competitions with virtual capital, seasons, and Vault rewards.
- IPO offerings with subscription, proportional allocation, and refunds.
- Stock certificates as tradeable in-game items.
- BossBar real-time stock price pinning.
- Market composite index and periodic market reports.
- Admin GUI panel and audit log queries.
- Vault economy integration (EssentialsX Economy compatible).
- PlaceholderAPI support.
- SQLite storage for all holdings, trades, orders, and audit data.
- 13 built-in language files.
- Winner and loser leaderboards by unrealized P&L.
- Configurable loss penalty system with tiered charges.
- Circuit breaker and quote anomaly protection.
- Market hours restrictions (optional).
- Config migration and startup validation.
Requirements
| Item |
Requirement |
| Server |
Paper / Purpur compatible |
| Java |
Java 21 |
| Required |
Vault + a Vault economy plugin |
| Recommended |
EssentialsX Economy |
| Optional |
PlaceholderAPI |
| Database |
SQLite (auto-created) |
| Network |
Required for real stock quotes (Tencent API) |
Recommended environment:
- Minecraft 1.21.x Paper / Purpur
- Java 21
- Vault
- EssentialsX + EssentialsX Economy
- PlaceholderAPI (for scoreboards, menus, chat displays)
Installation
- Install
Vault.
- Install
EssentialsX Economy or another Vault-compatible economy plugin.
- Optionally install
PlaceholderAPI.
- Drop
SuperStocks.jar into your server's plugins folder.
- Start the server to generate default configuration files.
- Modify as needed (then
/stocks reload):
plugins/SuperStocks/config.yml
plugins/SuperStocks/Language/
plugins/SuperStocks/CustomMarkets/
After first startup you should see:
plugins/SuperStocks/config.yml
plugins/SuperStocks/stocks.db
plugins/SuperStocks/Language/zh_CN.yml
plugins/SuperStocks/CustomMarkets/example.yml
Quick Start
If you just want the plugin running:
- Confirm Vault economy is working.
- Keep default language:
language: zh_CN
- Keep default quote provider:
stock-provider:
active: tencent
-
High-risk features are already disabled by default — no changes needed.
-
In-game:
/stocks sync
/stocks
If you see stock quotes in the GUI and can buy/sell, the basic setup is working. You can then gradually enable volatility enhancement, local markets, and loss penalties.
Commands
Player Commands
| Command |
Description |
/stocks |
Open the stock trading GUI |
/stocks help |
Show help |
/stocks open |
Open the stock GUI |
/stocks quote <symbol> |
View stock quote |
/stocks buy <symbol> <shares> |
Buy shares |
/stocks sell <symbol> <shares> |
Sell shares |
/stocks short <symbol> <shares> |
Open a short position |
/stocks cover <id> [shares] |
Close (cover) a short position |
/stocks portfolio |
View text-based portfolio |
/stocks history <symbol> |
View 24h price history |
/stocks stats |
View personal investment statistics |
/stocks watch add <symbol> |
Add to watchlist |
/stocks watch remove <symbol> |
Remove from watchlist |
/stocks watch list |
View watchlist |
| `/stocks alert <symbol> <above |
below> <price>` |
/stocks order buy <symbol> <shares> <price> [seconds] |
Create limit buy order |
/stocks order sell <symbol> <shares> <price> [seconds] |
Create limit sell order |
/stocks order stop-loss <symbol> <shares> <price> [seconds] |
Create stop-loss order |
/stocks order take-profit <symbol> <shares> <price> [seconds] |
Create take-profit order |
/stocks order list |
View open orders |
/stocks order cancel <id> |
Cancel an order |
/stocks rank winners |
View top investors |
/stocks rank losers |
View bottom investors |
/stocks index |
View market indices |
/stocks pin <symbol> |
Pin stock price to BossBar |
/stocks unpin |
Remove BossBar pin |
/stocks report |
View market report |
/stocks competition list |
List competitions |
/stocks competition join <id> |
Join a competition |
/stocks competition buy <id> <symbol> <shares> |
Buy in competition |
/stocks competition sell <id> <symbol> <shares> |
Sell in competition |
/stocks certificate issue <symbol> <shares> |
Convert holdings to certificate item |
/stocks certificate list |
List your certificates |
/stocks ipo list |
List IPO offerings |
/stocks ipo subscribe <id> <shares> |
Subscribe to an IPO |
Examples:
/stocks quote sh600519
/stocks buy sh600519 10
/stocks sell sh600519 5
/stocks short usTSLA 5
/stocks cover 1
/stocks portfolio
/stocks rank winners
Admin Commands
| Command |
Permission |
Description |
/stocks sync |
superstocks.admin |
Force quote sync |
/stocks status |
superstocks.admin |
View system status |
/stocks pause |
superstocks.admin |
Pause all trading |
/stocks resume |
superstocks.admin |
Resume trading |
/stocks penalty history <player> |
superstocks.admin |
View player penalty history |
/stocks admin portfolio <player> |
superstocks.admin |
View player portfolio |
/stocks admin give <player> <symbol> <shares> |
superstocks.admin |
Grant holdings to player |
/stocks admin remove <player> <symbol> <shares> |
superstocks.admin |
Remove holdings from player |
/stocks admin clear <player> |
superstocks.admin |
Clear all player holdings |
/stocks admin panel |
superstocks.admin |
Open admin GUI |
/stocks admin audit [player] [action] |
superstocks.admin |
Query audit log |
/stocks competition create <name> <days> <capital> |
superstocks.admin |
Create a competition |
/stocks competition end <id> |
superstocks.admin |
End competition & distribute rewards |
/stocks ipo create <symbol> <name> <market> <price> <total> <max> |
superstocks.admin |
Create an IPO |
/stocks ipo cancel <id> |
superstocks.admin |
Cancel an IPO |
/stocks reload |
superstocks.admin |
Reload config, language, markets, services |
Permissions
| Permission |
Default |
Description |
superstocks.use |
Everyone |
Use GUI and player commands |
superstocks.admin |
OP |
Use admin commands |
superstocks.penalty.exempt |
OP |
Exempt from loss penalties |
GUI Overview
Main screen — Market entries, portfolio button, winners/losers leaderboards, watchlist, system stats.
Market screen — Stock list showing name, symbol, current price, change amount, change %, and last update time. Supports pagination for markets with many stocks.
Stock detail page — Quick-buy and quick-sell buttons (3 preset amounts), 24h price trend sparkline, and price history summary.
Trade confirmation dialog — Appears when the estimated trade gross exceeds the configured threshold (default 1000), preventing accidental large trades.
Watchlist — A personal page showing only the stocks the player has added via /stocks watch add.
Portfolio — Shows all current holdings with cost basis, market value, and unrealized profit.
Admin panel — Overview of total holdings, active players, total trades, last sync time, trading pause status, and Vault status.
All GUI sizes, materials, and slot layouts are configurable in config.yml. The preset trade amounts default to [1, 10, 100] and can be adjusted to fit your economy scale — for high-currency servers, consider [10, 100, 1000].
Quote Provider
Default: Tencent Finance (no API key needed).
stock-provider:
active: tencent
refresh-seconds: 300
timeout-seconds: 8
log-success: true
Recommendations:
| Setting |
Recommended |
Notes |
refresh-seconds |
300 - 600 |
Don't set too low — avoid API rate limiting |
timeout-seconds |
8 - 15 |
Increase if network is unstable |
log-success |
true |
Useful for monitoring sync health |
The default endpoint:
sources:
tencent:
display-name: "Tencent Finance"
endpoint: "https://qt.gtimg.cn/q={symbols}"
encoding: "GBK"
symbol-separator: ","
max-symbols-per-request: 80
user-agent: "SuperStocks/1.0"
Placeholder entries exist for Eastmoney, THS, Xueqiu, and Sina. The built-in parser only handles Tencent's v_symbol="...~..." format. If switching sources, use a compatible proxy that outputs the same format.
Real Stock Markets
Configured under markets in config.yml.
Example:
markets:
cn:
display-name: "A-Share"
icon: EMERALD
symbols:
- "sh600519"
- "sz000001"
hk:
display-name: "HK Stocks"
icon: GOLD_INGOT
symbols:
- "hk00700"
us:
display-name: "US Stocks"
icon: DIAMOND
symbols:
- "usAAPL"
Tencent symbol format:
| Market |
Format |
Example |
| Shanghai A-Share |
sh + code |
sh600519 |
| Shenzhen A-Share |
sz + code |
sz000001 |
| Hong Kong |
hk + code |
hk00700 |
| US |
us + ticker |
usAAPL |
Recommendations:
- Start with 10-30 stocks per market.
- Too many stocks increase sync time and API load.
- Avoid removing symbols that players already hold — orphaned holdings won't appear in rankings or valuations.
Local Custom Markets
SuperStocks reads .yml files from:
plugins/SuperStocks/CustomMarkets/
Each file defines one local virtual market. An example file is generated on first startup:
plugins/SuperStocks/CustomMarkets/example.yml
Local markets don't call external APIs. They use a random-walk model close to real market behavior:
new price = old price × (1 + drift% + random volatility%)
Local prices also pass through gameplay-volatility, so local and real markets share the same in-game volatility rules.
Global Switch
custom-markets:
enabled: true
global-tick-seconds: 300
Guidance:
| Playstyle |
global-tick-seconds |
| Stable |
600 - 1800 |
| Normal |
300 - 600 |
| Fast-paced |
60 - 180 |
Market File Example
market:
id: local_tech
display-name: "Local Tech Stocks"
icon: AMETHYST_SHARD
enabled: true
simulation:
tick-seconds: 300
tick-limit-percent: 15
regimes:
enabled: true
duration-seconds: 3600
stocks:
local_chip:
symbol: "lcCHIP"
name: "Block Chip Inc."
enabled: true
initial-price: 120.0
min-price: 10.0
max-price: 1000.0
drift-percent-per-tick: 0.03
volatility-percent: 2.0
Local Stock Parameters
| Setting |
Description |
Guidance |
symbol |
Stock code |
Use a prefix to avoid conflicts, e.g. lcCHIP |
name |
Display name |
Shown in GUI |
initial-price |
Starting price |
Match your server's economy scale |
min-price |
Price floor |
Keep above 0 |
max-price |
Price ceiling |
Prevents runaway prices |
drift-percent-per-tick |
Long-term trend |
Typically -0.2 to 0.2 |
volatility-percent |
Random swing strength |
Stable 0.5-1.5, normal 1.5-3.0, risky 3.0-8.0 |
Tips:
- Local markets are great for server-made companies, town economies, event stocks, or lore-driven economies.
- Give a small positive
drift-percent-per-tick (e.g. 0.02) for stocks you want to trend upward long-term.
- For high-risk stocks, raise
volatility-percent but keep min-price and max-price as guardrails.
- Don't set
drift-percent-per-tick too high or prices will quickly leave the intended range.
Gameplay Volatility Enhancement
Real stocks often have small daily moves that feel insignificant in Minecraft economies. gameplay-volatility transforms base prices into more dramatic in-game prices.
Processing order:
Base quote → Price multiplier → Random offset → In-game display & trading price
Configuration:
gameplay-volatility:
price-multiplier:
enabled: false
multiplier: 1.0
random-adjustment:
enabled: false
min-percent: -3.0
max-percent: 3.0
refresh-seconds: 300
safety:
min-price: 0.01
max-price: 1000000000.0
Price Multiplier
price-multiplier:
enabled: true
multiplier: 5.0
In-game price = base price × multiplier.
| Server Type |
multiplier |
| Vanilla-scale economy |
1.0 - 5.0 |
| Normal economy |
5.0 - 20.0 |
| High-inflation economy |
20.0 - 100.0 |
If unsure, keep disabled initially, observe the trading experience, then enable.
Random Adjustment
random-adjustment:
enabled: true
min-percent: -5.0
max-percent: 5.0
refresh-seconds: 300
Each stock gets an independent random offset (e.g. -5% to +5%), regenerated every refresh-seconds.
| Style |
min-percent |
max-percent |
refresh-seconds |
| Stable |
-2.0 |
2.0 |
600 - 1800 |
| Normal |
-5.0 |
5.0 |
300 - 600 |
| Aggressive |
-10.0 |
10.0 |
60 - 180 |
Safety Bounds
safety:
min-price: 0.01
max-price: 1000000000.0
- Keep
min-price at 0.01.
- Set
max-price to match your economy scale to prevent misconfiguration damage.
Recommended Combinations
Normal survival economy server:
gameplay-volatility:
price-multiplier:
enabled: true
multiplier: 5.0
random-adjustment:
enabled: true
min-percent: -5.0
max-percent: 5.0
refresh-seconds: 300
Fast-paced investment server:
gameplay-volatility:
price-multiplier:
enabled: true
multiplier: 20.0
random-adjustment:
enabled: true
min-percent: -10.0
max-percent: 10.0
refresh-seconds: 120
Automated Orders, Stop-Loss & Take-Profit
SuperStocks supports automated orders so players can set buy/sell conditions in advance.
orders:
enabled: true
max-open-per-player: 10
automation:
check-seconds: 30
Order types:
| Type |
Command |
Description |
| Limit Buy |
/stocks order buy <symbol> <shares> <price> [seconds] |
Auto-buy when price reaches trigger |
| Limit Sell |
/stocks order sell <symbol> <shares> <price> [seconds] |
Auto-sell when price reaches trigger |
| Stop-Loss |
/stocks order stop-loss <symbol> <shares> <price> [seconds] |
Auto-sell when price drops to limit losses |
| Take-Profit |
/stocks order take-profit <symbol> <shares> <price> [seconds] |
Auto-sell when price rises to lock in gains |
Utility commands:
/stocks order list
/stocks order cancel <id>
Mechanics:
- Limit buy orders reserve the estimated cost upfront; funds are returned if the order expires or is cancelled.
- Sell/stop/take-profit orders check available holdings to prevent over-selling.
- Orders are checked every
automation.check-seconds.
orders.max-open-per-player caps how many open orders each player can have.
Recommendations:
- Normal servers:
max-open-per-player: 5 - 10.
- Investment-focused servers:
10 - 20.
- Don't set
automation.check-seconds below 10 to avoid excessive database scanning.
Price Alerts & Watchlist
Players can track stocks of interest and receive notifications when price targets are hit.
Watchlist commands:
/stocks watch add <symbol>
/stocks watch remove <symbol>
/stocks watch list
Alert commands:
/stocks alert <symbol> above <price>
/stocks alert <symbol> below <price>
Configuration:
alerts:
enabled: true
The main GUI also has a watchlist entrance. Watchlists help players track key stocks; alerts pair well with limit/stop/take-profit orders.
Quote Safety & Circuit Breaker
Public servers should keep these enabled to protect the economy from API anomalies, player spam, or misconfiguration.
Quote anomaly protection:
quote-safety:
reject-stale-quotes: true
max-quote-age-seconds: 900
reject-abnormal-change: true
max-change-percent-per-sync: 25.0
circuit-breaker:
enabled: true
stock-max-change-percent: 15.0
freeze-seconds: 600
| Setting |
Description |
Guidance |
reject-stale-quotes |
Block trading with expired quotes |
Enable for public servers |
max-quote-age-seconds |
Quote expiry threshold |
2-3× your refresh interval |
reject-abnormal-change |
Reject single-sync price spikes |
Enable |
max-change-percent-per-sync |
Max allowed change per sync |
20 - 30 for normal servers |
circuit-breaker.enabled |
Freeze trading on abnormal in-game price swings |
Enable |
freeze-seconds |
Freeze duration |
300 - 900 |
Trading rate limits:
trading:
paused: false
cooldown-milliseconds: 1000
max-trades-per-minute: 20
max-shares-per-trade: 10000
max-position-value: 0.0
| Setting |
Description |
Guidance |
paused |
Global trading pause |
Toggle during maintenance |
cooldown-milliseconds |
Minimum interval between player trades |
500 - 2000 |
max-trades-per-minute |
Max manual trades per minute per player |
10 - 30 |
max-shares-per-trade |
Max shares per single trade |
Match your economy scale |
max-position-value |
Max market value per stock per player (0 = unlimited) |
Prevents monopolization |
Admin commands:
/stocks pause
/stocks resume
/stocks status
Fees, Short-Term Tax & Dividends
Base transaction fees:
economy:
transaction-tax-percent: 0.5
min-shares: 1
large-trade-threshold-shares: 1000
large-trade-extra-tax-percent: 0.2
Guidance:
transaction-tax-percent: 0.2 - 1.0 for normal servers.
- Large trade extra tax discourages high-frequency whale trades.
- Raise
min-shares to match your economy scale.
Short-term tax:
economy:
short-term-tax:
enabled: false
minimum-holding-hours: 24
percent: 1.0
Charges an extra fee when selling positions held for less than the minimum duration. Encourages long-term holding.
Dividends:
dividends:
enabled: false
interval-hours: 168
yield-percent: 0.5
minimum-holding-hours: 24
| Setting |
Description |
Guidance |
interval-hours |
Payout interval |
168 = weekly |
yield-percent |
% of market value paid out |
0.1 - 1.0 |
minimum-holding-hours |
Minimum holding period to qualify |
Prevents last-minute buying |
⚠️ Dividends continuously inject money into the economy. Disabled by default.
Loss Penalty
loss-penalty triggers consequences when a player's portfolio is losing money. Penalties are selected by loss-percentage tier, then applied as Vault withdrawals or console commands.
Disabled by default:
loss-penalty:
enabled: false
Loss Calculation
Uses current in-game prices:
Cost basis = shares × average cost
Market value = shares × current price
Loss amount = max(0, cost basis - market value)
Loss % = loss amount ÷ cost basis × 100%
Tier Configuration
loss-penalty:
check-interval-seconds: 600
player-cooldown-seconds: 3600
tiers:
light:
enabled: true
min-loss-percent: 5.0
max-loss-percent: 10.0
fixed-amount: 0.0
percent-of-loss: 0.5
percent-of-portfolio-value: 0.0
max-amount: 1000.0
The plugin selects the highest min-loss-percent tier that matches the current loss percentage.
Penalty formula:
Charge = fixed-amount + loss × percent-of-loss% + portfolio value × percent-of-portfolio-value%
Tier guidance:
| Tier |
Loss % |
percent-of-loss |
percent-of-portfolio-value |
max-amount |
| light |
5% - 10% |
0.5 - 1.0 |
0 - 0.2 |
0.5-1× daily player income |
| normal |
10% - 20% |
1.0 - 3.0 |
0 - 0.5 |
1-2× daily player income |
| severe |
20%+ |
2.0 - 6.0 |
0.2 - 1.0 |
2-5× daily player income |
Vault Withdrawal
loss-penalty:
actions:
vault-withdraw:
enabled: false
never-negative-balance: true
Recommendations:
- Keep
never-negative-balance: true on normal servers.
- Don't enable heavy penalties on a public survival server from day one.
- Start with notify-only, observe player losses, then gradually enable withdrawals.
Console Commands
loss-penalty:
actions:
commands:
enabled: false
list:
- "effect give {player} minecraft:slowness 30 0"
Available variables:
| Variable |
Description |
{player} |
Player name |
{uuid} |
Player UUID |
{tier} |
Triggered tier ID |
{loss} |
Current loss amount |
{loss_percent} |
Current loss percentage |
{portfolio_value} |
Current portfolio market value |
{cost} |
Current cost basis |
{vault_penalty} |
This round's Vault charge |
Player Notification
loss-penalty:
actions:
notify:
enabled: true
message: "&cYour portfolio is down {loss} ({loss_percent}%), triggering {tier} tier penalty. Charge: {vault_penalty}."
This message lives in config.yml so you can edit it directly for your server's style and language.
Short Selling
Players borrow shares to sell high, then buy back lower to return them. Short positions require a margin deposit and are subject to forced liquidation if the price rises too much.
short-selling:
enabled: true
max-shares-per-position: 10000
check-seconds: 120
interest-percent-per-day: 0.0 # 0 = no interest
margin:
required-percent: 50 # Margin = position value × rate
liquidation-percent: 50 # Auto-close when loss reaches margin × rate
Commands:
/stocks short <symbol> <shares> # Open a short
/stocks cover <id> [shares] # Close all or part of a short
Mechanics:
- Opening a short freezes the margin deposit; it's returned when you close.
- If the stock price rises to the liquidation threshold, the position is force-closed and the margin is lost.
- Default daily interest is 0% — no silent money drain.
- Partial covers are supported.
Investment Competitions
Create seasonal competitions where participants pay an entry fee for equal virtual capital, compete on returns, and win Vault rewards.
competition:
enabled: true
rewards:
- "1: 5000" # 1st place reward
- "2: 2000" # 2nd place
- "3: 1000" # 3rd place
Player commands:
/stocks competition list
/stocks competition join <id>
/stocks competition buy <id> <symbol> <shares>
/stocks competition sell <id> <symbol> <shares>
Admin commands:
/stocks competition create <name> <days> <start-capital>
/stocks competition end <id>
Mechanics:
- Competitions use separate virtual portfolios — real holdings are untouched.
- Ending a competition auto-valuates all entries at current market prices, ranks them, and distributes rewards.
- Adjust reward amounts to match your server's economy scale.
IPO Offerings
Admins can create IPOs for local market stocks. Players subscribe during the offering window; shares are allocated proportionally when it closes.
Player commands:
/stocks ipo list
/stocks ipo subscribe <id> <shares>
Admin commands:
/stocks ipo create <symbol> <name> <market> <price> <total-shares> <max-per-player>
/stocks ipo cancel <id>
Mechanics:
- IPO subscriptions pre-withdraw Vault funds. After allocation, excess is refunded.
- Oversubscribed IPOs scale down proportionally; unallocated funds are returned.
- Allocated shares go directly into player portfolios.
Stock Certificates
Players can convert holdings into tradeable certificate items, enabling peer-to-peer trading, chest shops, or auctions.
/stocks certificate issue <symbol> <shares> # Convert to item
/stocks certificate list # View your certificates
Right-click the certificate item in the air to redeem it back into your portfolio. Certificates can be freely traded between players.
BossBar, Index & Reports
BossBar pinning — Pin a stock's real-time price to the top of your screen:
/stocks pin <symbol> # Pin
/stocks unpin # Remove
The bar color follows price direction (green up, red down) and the progress bar reflects intraday volatility.
Market index — View average price per market:
/stocks index
Market report — Generate a text-based summary:
/stocks report
Admin Panel & Audit Log
Admin GUI — Visual overview of total holdings, active players, trades, sync status, trading pause state, and Vault health:
/stocks admin panel
Audit log — Query the operation history:
/stocks admin audit [player] [action]
Audit action types include: BUY, SELL, ORDER_CREATED, ORDER_EXECUTED, ADMIN_GIVE, ADMIN_REMOVE, ADMIN_CLEAR, SHORT_OPEN, SHORT_COVER, SHORT_LIQUIDATED, COMPETITION_CREATE, COMPETITION_JOIN, IPO_CREATE, IPO_ALLOCATED, CERT_REDEEM, and more.
Leaderboards
Two leaderboards:
| Board |
Command |
Description |
| Winners |
/stocks rank winners |
Ranked by unrealized profit (highest first) |
| Losers |
/stocks rank losers |
Ranked by unrealized loss (highest first) |
Leaderboards depend on cached quotes. Stocks without successful syncs are excluded from that cycle's valuation.
Languages
Set in config.yml:
language: zh_CN
Language files live in:
plugins/SuperStocks/Language/
Built-in languages:
| Code |
Language |
zh_CN |
简体中文 |
zh_HK |
繁體中文(香港) |
zh_MO |
繁體中文(澳門) |
zh_TW |
繁體中文(台灣) |
en_US |
English |
ja_JP |
日本語 |
ko_KR |
한국어 |
ar_SA |
العربية |
de_DE |
Deutsch |
es_ES |
Español |
fr_FR |
Français |
pt_BR |
Português do Brasil |
ru_RU |
Русский |
Missing keys fall back to en_US at runtime. To add a custom language, copy any existing file, rename it, edit the text, set it in config.yml, and run /stocks reload.
PlaceholderAPI
| Placeholder |
Description |
%superstocks_cash% |
Vault balance |
%superstocks_portfolio_value% |
Current portfolio market value |
%superstocks_total_value% |
Cash + portfolio value |
%superstocks_profit% |
Unrealized profit/loss |
%superstocks_profit_percent% |
Unrealized return percentage |
%superstocks_shares_<symbol>% |
Shares held of a specific stock |
Examples:
%superstocks_profit_percent%
%superstocks_shares_usAAPL%
Data Storage
SuperStocks uses SQLite to store holdings and trade data.
database:
file: "stocks.db"
Default location:
plugins/SuperStocks/stocks.db
Recommendations:
- Back up
stocks.db regularly.
- Do not edit the database directly while the server is running.
- Deleting the database will wipe all player holdings and trade history.
Reloading
/stocks reload
Reloads:
config.yml
- Current language file
- Real market lists
- Local custom market files
- Quote provider parameters
- Gameplay volatility settings
- Loss penalty configuration
- Trading fees and minimum trade amounts
Database file path changes require a full server restart.
Recommended Configurations
Stable Survival Server
For normal survival economy — stocks as a side activity.
gameplay-volatility:
price-multiplier:
enabled: false
random-adjustment:
enabled: true
min-percent: -2.0
max-percent: 2.0
refresh-seconds: 900
loss-penalty:
enabled: false
Normal Economy Server
For servers where stocks are a core feature.
gameplay-volatility:
price-multiplier:
enabled: true
multiplier: 5.0
random-adjustment:
enabled: true
min-percent: -5.0
max-percent: 5.0
refresh-seconds: 300
loss-penalty:
enabled: false
High-Risk Investment Server
For servers built around trading, rankings, and risk mechanics.
gameplay-volatility:
price-multiplier:
enabled: true
multiplier: 20.0
random-adjustment:
enabled: true
min-percent: -10.0
max-percent: 10.0
refresh-seconds: 120
loss-penalty:
enabled: true
check-interval-seconds: 300
player-cooldown-seconds: 3600
High-risk configurations should be paired with clear announcements, rules, or tutorials so players understand the penalty mechanics.
Market Hours (Optional)
Restrict trading to real market hours. Disabled by default (24/7 trading).
market-hours:
cn:
enabled: false
timezone: "Asia/Shanghai"
open: "09:30"
close: "15:00"
weekends: false
closed-action: "DENY"
closed-action: DENY (block all trading) or SELL_ONLY (allow selling only during closed hours).
Market Events (Optional)
Random "breaking news" events that cause price jumps in local markets. Disabled by default.
market-events:
enabled: false
chance-percent-per-tick: 2.0
min-impact-percent: -5.0
max-impact-percent: 5.0
announce-threshold-percent: 3.0
When an event's impact exceeds the threshold, a server-wide announcement is broadcast.
FAQ
Can't trade a stock?
The stock likely hasn't synced quotes yet. Try:
/stocks sync
/stocks quote <symbol>
If still no data, check your server's network access to the quote API and verify the symbol is correct.
Leaderboard shows no data?
Leaderboards require players to hold positions with cached quotes. Local stocks need at least one simulation tick; real stocks need a successful sync first.
Vault or EssentialsX Economy not working?
Confirm:
- Vault is installed.
- A Vault economy plugin (e.g. EssentialsX Economy) is installed.
- Vault recognizes the economy provider.
- No economy plugin loading errors in console.
Language didn't change after switching?
Verify the language code in config.yml, e.g.:
language: en_US
Then run:
/stocks reload
Prices seem too volatile?
This is expected if random-adjustment is enabled. To reduce it, narrow min-percent / max-percent or increase refresh-seconds.
Do local markets affect real stock quotes?
No. Local markets use independent configs in CustomMarkets/ and never call external APIs. They pass through the same gameplay-volatility processing as real quotes.
Disclaimer
SuperStocks is a virtual investment entertainment plugin for Minecraft servers. It does not provide, constitute, or imply any real-world investment advice. Real stock quote APIs may be subject to third-party stability, access restrictions, or field changes. Set reasonable sync intervals and comply with applicable terms of service.
评论 0
登录后参与评分
还没有评论,来抢沙发吧