SuperStocks

# 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 1. Install `Vault`. 2. Install `EssentialsX Economy` or another Vault-compatible economy plugin. 3. Optionally install `PlaceholderAPI`. 4. Drop `SuperStocks.jar` into your server's `plugins` folder. 5. Start the server to generate default configuration files. 6. Modify as needed (then `/stocks reload`): ```text plugins/SuperStocks/config.yml plugins/SuperStocks/Language/ plugins/SuperStocks/CustomMarkets/ ``` After first startup you should see: ```text 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: 1. Confirm Vault economy is working. 2. Keep default language: ```yaml language: zh_CN ``` 3. Keep default quote provider: ```yaml stock-provider: active: tencent ``` 4. High-risk features are already disabled by default — no changes needed. 5. In-game: ```text /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> ` | 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>` | Create price alert | | `/stocks order buy <symbol> <shares> <price> ` | Create limit buy order | | `/stocks order sell <symbol> <shares> <price> ` | Create limit sell order | | `/stocks order stop-loss <symbol> <shares> <price> ` | Create stop-loss order | | `/stocks order take-profit <symbol> <shares> <price> ` | 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