One balance across your whole network
Vixels, payments, history and premium shops—shared between every server.
Players keep one UUID-based Vixels wallet wherever they play. Velocity protects every balance change while Paper provides the commands, menus, shops and placeholders players interact with.
Everything included with Vixels
Network-wide wallet
One balance follows each UUID across your lobby, games, racing servers and every linked backend.
Safe player payments
Players send Vixels with a confirmation step, payment preferences, notifications and a persistent transfer history.
Transaction history
Browse paginated earnings, spending and transfers instead of guessing where a balance changed.
Global leaderboard
Show the richest players across the network through commands, menus and cached placeholders.
Premium GUI shop
Category tabs, pagination, confirmations, permissions and staff preview are included on Paper.
Real purchase rules
Persistent stock, one-time limits, daily limits and cooldowns are checked with the debit—not after it.
Receipts and recovery
Orders keep an auditable state so uncertain fulfillment can be reviewed or refunded safely.
RaceX integration
Racing rewards, claims, shops, cosmetics and tournament results can use stable Vixels transactions.
PlaceholderAPI support
Display balances, status, leaderboard positions and recent transactions without blocking the server thread.
Quick setup with a hosted database
Use managed hosting from Victus Cloud
You do not need to run a database server yourself. Ask Victus Cloud—or your current hosting provider—for a managed MariaDB/MySQL database, then enter those details on Velocity.
Get a hosted MariaDB/MySQL database
Install the Velocity authority
VictusCurrency-Velocity-1.1.0.jar in the Velocity plugins folder and add the hosted database details.Install the Paper plugin
VictusCurrency-Paper-1.1.0.jar on every linked Paper backend. Paper never receives database credentials.Remove old duplicate JARs
VictusCurrencyPaper or VictusCurrency-Paper.jar copies so only one canonical Paper plugin loads.Connect each backend securely
Start Velocity, then Paper
/vstatus. Continue only when the authority reports ONLINE.bridge:
server-id: racing # exact Velocity registered-server name
secret: "unique-long-secret-for-only-this-backend"
handshake-retry-seconds: 10
status-interval-seconds: 30Player wallet and payments
/vixels [player]View your wallet or another known player's balance.
/vtransactions [player] [page]Browse paginated transaction history.
/vtop [page]View the network-wide Vixels leaderboard.
/vpay <player> <amount>Prepare a payment to an online player.
/vpay confirm <token>Confirm the pending payment after checking the recipient and amount.
/vpay cancelCancel your pending payment.
/vpay toggle · /vnotify toggleControl incoming payments and transaction notifications.
/vpay history [page]Review previous player-to-player transfers.
Payments stay predictable
Recipient preferences are checked when the payment is confirmed. Repeating the same protected request returns its original result instead of charging twice.
Premium category shop
Categories and pages
Organize products into configurable tabs with icons, order, selected styling and deterministic pagination.
Confirmation screens
Players see exactly what they are buying before the authority approves the debit.
Stock
Finite stock decreases in the same transaction as the wallet debit and order creation.
Purchase limits
One-time and daily limits persist through restarts and server changes.
Cooldowns
Product cooldowns are enforced centrally, not through a temporary Paper cache.
Permissions and visibility
Hide products, require permissions and let staff preview the catalog before players see it.
/coinshopOpen the player shop GUI.
victuscurrency.shop.use
/vshop buy <product-id>Purchase a configured product through the authority.
victuscurrency.shop.buy
/vshop preview [product|page]Preview products and pages as staff.
victuscurrency.shop.preview
/vshop validate · /vshop reloadValidate the catalog before opening it, then reload safe shop presentation changes.
victuscurrency.shop.admin
/vshop orders [filters]Review fulfilled, uncertain, rejected and refunded shop orders.
victuscurrency.shop.orders
Integrations and displays
Scoreboards, TAB and holograms
Cached placeholders never query the database on the main thread. Missing or stale values show Unavailable, not a misleading zero.
%victuscurrency_balance%%victuscurrency_balance_formatted%%victuscurrency_top_1_name%%victuscurrency_top_1_balance%%victuscurrency_status%Racing rewards and purchases
Race rewards, claims, tournament wins, shops, cosmetics, battle-pass actions and refunds can use stable event IDs and durable Vixels receipts.
- ✓Stable event IDs prevent duplicate rewards
- ✓Shop fulfillment can be reconciled after a restart
- ✓Wallet display uses the same cached authority data
Admin tools and quick fixes
/vstatusCheck the Paper lifecycle and authority connection.
victuscurrency.status
/vixelsadmin healthCheck authority, database and catalog health.
victuscurrency.admin.health
/vixelsadmin add|remove|set ...Perform an audited balance adjustment with a stable request UUID and reason.
victuscurrency.admin.balance
/vixelsadmin refund ...Refund a transaction using a new stable request UUID and reason.
victuscurrency.admin.refund
Authority stays offline
Confirm the Velocity plugin is enabled, its hosted database credentials work, the Paper server ID exactly matches Velocity and the backend secret matches on both sides.
Shop will not open
Run /vshop validate. Fix invalid product IDs, categories, materials, commands or catalog-policy mismatches before reloading.
Placeholder says Unavailable
Wait for the signed handshake and cache refresh. Check /vstatus instead of treating an unavailable value as a zero balance.
Duplicate plugin warning
Keep only the current canonical Paper JAR. Remove old copies with alternate VictusCurrencyPaper names before restarting.
How the safe authority flow works
Player command or Paper GUI
↓ signed request
Velocity validates identity, permissions, policy and duplicate requests
↓ transaction
Hosted MariaDB / MySQL stores wallet, ledger and shop order
↑ response and cache update
Paper shows the result, fulfills the product and records the receiptNo database secrets on backends
Each Paper server signs requests with its own bridge secret. It displays cached balances and runs approved fulfillment, but cannot approve money from cache.
Async integrations
The API module exposes an asynchronous CurrencyService and immutable wallet, transaction and shop models. Never block the Paper or Velocity event thread while waiting for a result.