JVIPS — VIP Management System for Hytale

Want to help with translation? Send the file to: gorgueirajc@gmail.com

Jvips Doc

Feel free to join our Discord happy to help!

Help JPlugins grow, make a donation: PayPal

JVIPS is a complete and production-ready VIP management system for Hytale servers, built around secure vouchers, automatic expiration, persistent virtual chests, and server-side command execution.

It allows server owners to sell, distribute, or reward VIP access safely, with full integration to permission plugins such as LuckPerms, while maintaining strict validation and anti-abuse protections.

✨ Core Features

🎟️ Secure VIP Vouchers

Cryptographically bound to a specific player (UUID)
HMAC signature validation prevents tampering or duplication
Vouchers cannot be dropped, reused, or transferred
Consumed only after successful activation

🎯 Command Vouchers

Lightweight, single-use vouchers that only execute commands — no VIP status, no duration lifecycle. Perfect for quests, teleports, rewards, kits, or any server action triggered by an item.

Configured in a separate file (command_vouchers.json)
Supports any item ID — not limited to Jvips_Voucher
UUID-bound to the receiving player (non-transferable)
No HMAC — simplified system, no cryptographic overhead
No VIP lifecycle flow — works independently from VIP state
Works even with an active VIP — never blocked by existing VIP state
Drop-blocked just like VIP vouchers
Delivered via /vips givecmd <id> <player>
Supports command execution mode:
- player_side: true → executes as player
- player_side: false → executes as console

🛒 VIP Shop — Player Marketplace

A full player-to-player voucher marketplace built directly into the menu:

Players can list their TAB vouchers for sale with a custom price and currency
Other players can browse and purchase directly from the Shop tab in the menu
The sold voucher is re-issued to the buyer with a fresh UUID and a new HMAC signature — fully secure and tamper-proof
Listings expire automatically after a configurable number of days, returning vouchers to sellers
Tax system per currency — configurable seller fee taken from each sale
Max listings per player configurable (0 = unlimited)
Admins can list vouchers as the server (money goes to void) via /vips sellkey <vipId> <currency> <price> [--duration tempo]
Admins can remove any server listing via /vips unsellkey <slot>
Multi-currency support — configure as many currencies as needed (VaultUnlocked, HyVault)
Players can also list vouchers directly from their hand via /vips sellvoucher <currency> <price> — voucher must be in the active hotbar slot
Shop tab integrates seamlessly with both the HyUI and native menu backends
Voucher duration shown in the info panel — buyers see exactly how long the VIP lasts before confirming
Seller notification — seller receives a chat message when their voucher is sold (if online)
Filter panel — filter listings by price (ascending/descending) and by currency, directly from the Shop tab. All labels and button texts configurable via messages JSON, including per-currency button labels (shop.filter.currency.<id>)

🔄 Voucher Stacking (Global)

Extend active VIP time by using additional vouchers of the same type:

Global toggle in config.json with vipStack.enabled
Global limit in config.json with vipStack.maxStack (0 = unlimited)
Each stack adds voucher duration to current expiration
Works with voucher activation and admin commands
Stack count tracked per player and reflected in Top VIPs ranking

🖥️ Dual Menu Backend — Native & HyUI

Choose which UI system powers /vips menu via a single config.json field:

`customui.menuvip`	Behavior
`"native"`	Opens the native Hytale CustomUIPage menu
`"hyui"`	Opens the HyUI-based menu

Both backends share the same permission (jvips.use) and the same VIP data. Switch backends without touching player data.

🎯 VIP HUD — Per-Player Positioning

The VIP HUD overlay is fully repositionable by each player via /vips hudcfg:

Opens a live preview of the HUD at its current position on screen
Fine controls — move ±1 px per click (8 directions)
Coarse controls — move ±10 px per click (8 directions)
Position saved automatically on every click — no explicit save needed
Applies to the live HUD on the next server tick after closing
Per-player positions stored in data/hud-prefs/<uuid>.json

🔒 Voucher Chest Guard

Voucher items are protected from being placed in external containers:

Moving a voucher to any chest other than the VIP Chest is automatically reversed
Dropping vouchers is also blocked (existing drop-block system)
VIP Chest (/vips chest) always allows voucher storage

⏱️ Custom Duration

Admins can issue vouchers or grant VIPs with a custom duration instead of the default from vips.json:

/vips givekey <vip> <player> --duration 1d2h10m
/vips givekeytab <vip> <player> --duration 1d2h10m
/vips add <player> <vip> --duration 30d
Supports d (days), h (hours), m (minutes), s (seconds)
Custom duration is embedded in VIP voucher HMAC signature (tamper-proof)
Voucher lore reflects custom duration

🧩 Vouchers TAB Activation

A dedicated, safe flow to activate VIP vouchers directly from the menu tab:

Admin command: /vips givekey <vip> <player> [--duration time] — always delivers to the TAB (no physical item)
Voucher is saved directly to TAB storage (per-player file)
2-click confirmation — first click selects and shows voucher info, second click confirms activation (prevents accidental activation)
Slot is consumed after successful activation
UI refreshes immediately after click (status, stacks, remaining time, slot content)

Dual-mode activation via config.json:

`activationMode`	Behavior
`"tab"`	Two-click confirmation activates the VIP directly (default)
`"inventory"`	First click moves the voucher to the player's physical hotbar; the player activates it by interacting or sells it via `/vips sellvoucher`

⏳ Automatic VIP Lifecycle

VIPs expire automatically without requiring player login
Configurable commands on activation and expiration
Sequential command execution (order guaranteed)
Background ticking system handles all timers
Unified sweep: reminders and expirations processed in a single efficient pass

📦 Virtual Chest (`/vips chest`)

A persistent, permission-based virtual chest using native Hytale container GUI.

Native GUI — Identical to a regular Hytale chest
Auto-save — Items saved automatically when chest is closed
Permission-based capacity — Chest size scales with VIP tier
Smart downgrade — Excess items are dropped at player's feet when capacity decreases
Persistent storage — Survives restarts and VIP expiration

Permission	Rows	Slots
`jvips.chest.9`	1	9
`jvips.chest.18`	2	18
`jvips.chest.27`	3	27
`jvips.chest.36`	4	36
`jvips.chest.45`	5	45
`jvips.chest.54`	6	54 (max)

📋 VIP History, Status & Top VIPs

/vips status — View active VIP with remaining time
/vips list <player> — View player VIP status (admin)
/vips history <player> — Activation/expiration history with timestamps
Top VIPs ranking in menu — ranks players by total activations (including stacks)
Paginated output for large histories

🔧 Smart Config Merge

Update plugin without losing customization:

New config properties are auto-added
Existing values are never overwritten
New message keys merged into language files
Arrays like command lists are never replaced
Runs on startup and /vips reload

🌍 Multi-Language Support

Fully configurable messages via JSON
Ships with en_US, pt_BR, and es_ES
Language selection via config.json

📢 VIP Broadcast System

Global EventTitle broadcast on VIP activation
Cooldown and grouping support
Plain-text optimized for Hytale UI stability
Fully customizable via language files

🔗 PlaceholderAPI Integration

Supports the official PlaceholderAPI for Hytale
Fallback compatibility with alternative PlaceholderAPI implementations
Available placeholders:

Placeholder	Description	Example Output
`%jvips_active%`	Whether the player has an active VIP	`true` / `false`
`%jvips_vip_id%`	ID of the active VIP tier	`thorium`
`%jvips_vip_display%`	Display name of the active VIP (falls back to ID)	`[THORIUM]`
`%jvips_remaining%`	Time remaining until VIP expires (human-readable)	`1d 5h 30m 45s`
`%jvips_expires_at%`	Exact expiration date/time (formatted per config)	`15/03/2026 14:30`
`%jvips_stack_count%`	Number of stacked VIP activations	`0`, `1`, `2`

🧾 Commands

Player Commands

Command	Description	Permission
`/vips menu`	Opens VIP menu (native or HyUI, configured in config.json)	`jvips.use`
`/vips status`	Shows your VIP status	`jvips.use`
`/vips chest`	Opens your VIP virtual chest	`jvips.chest.&amp;lt;slots&amp;gt;`
`/vips sellvoucher &amp;lt;currency&amp;gt; &amp;lt;price&amp;gt;`	Lists the voucher in your active hotbar slot on the VIP Shop	`jvips.use`
`/vips hudcfg`	Opens the VIP HUD position configurator	`jvips.use`

Admin Commands

Command	Description	Permission
`/vips givekey &amp;lt;vip&amp;gt; &amp;lt;player&amp;gt; [--duration time]`	Gives a VIP voucher directly to the player's Vouchers TAB	`jvips.admin`
`/vips givecmd &amp;lt;id&amp;gt; &amp;lt;player&amp;gt;`	Gives a Command Voucher	`jvips.admin`
`/vips add &amp;lt;player&amp;gt; &amp;lt;vip&amp;gt; [--duration time]`	Grants VIP directly (optional custom duration)	`jvips.admin`
`/vips remove &amp;lt;player&amp;gt; &amp;lt;vip&amp;gt;`	Removes VIP immediately	`jvips.admin`
`/vips sellkey &amp;lt;vip&amp;gt; &amp;lt;currency&amp;gt; &amp;lt;price&amp;gt; [--duration time]`	Lists a VIP voucher for sale as the server (admin shop)	`jvips.admin`
`/vips unsellkey &amp;lt;slot&amp;gt;`	Removes a server shop listing by global slot	`jvips.admin`
`/vips list [--player name] [--page N]`	Shows active VIPs	`jvips.admin`
`/vips history [--player name] [--page N]`	Shows full VIP history	`jvips.admin`
`/vips reload`	Reloads configuration and messages	`jvips.admin`

Duration Format

The --duration flag accepts a compact time string:

Example	Result
`30d`	30 days
`1d2h10m`	1 day, 2 hours, 10 minutes
`2h30m`	2 hours, 30 minutes
`10m`	10 minutes
`1d2h10m5s`	1 day, 2 hours, 10 min, 5 sec

🔐 Permissions

Permission	Description
`jvips.use`	Allows using vouchers and opening menu/status
`jvips.admin`	Allows all admin commands
`jvips.chest.&amp;lt;slots&amp;gt;`	Grants virtual chest access (9, 18, 27, 36, 45, or 54)

📁 Configuration

`config.json`

{
  "language": "en_US",
  "vipExpiry": {
    "sweepEverySeconds": 10
  },
  "vipStack": {
    "enabled": true,
    "maxStack": 3
  },
  "vipBroadcast": {
    "enabled": true,
    "cooldownSeconds": 30
  },
  "formatting": {
    "dateFormat": "dd/MM/yyyy",
    "hourFormat": "24h",
    "timezone": "America/Sao_Paulo"
  },
  "listSettings": {
    "entriesPerPage": 5
  },
  "logging": {
    "debug": false
  },
  "vouchers": {
    "activationMode": "tab"
  },
  "customui": {
    "menuvip": "native"
  }
}

The config.json also includes the shop section:

"shop": {
  "enabled": true,
  "economyProvider": "auto",
  "currencies": [
    { "id": "money", "displayName": "Money", "symbol": "$", "taxPercent": 5.0 },
    { "id": "gold",  "displayName": "Gold",  "symbol": "G", "taxPercent": 0.0 }
  ],
  "listing": {
    "expiryDays": 7,
    "maxPerPlayer": 3
  }
}

economyProvider: auto (detects VaultUnlocked or HyVault), vaultunlocked, or hyvault
taxPercent: percentage taken from the seller on each sale (0 = no tax)
expiryDays: days before a listing auto-expires and returns the voucher to the seller (0 = never)
maxPerPlayer: max active listings per player (0 = unlimited)

`vips.json`

{
  "security": {
    "hmacSecret": "YOUR_LONG_RANDOM_SECRET_HERE"
  },
  "vips": {
    "thorium": {
      "displayName": "[THORIUM]",
      "durationSeconds": 2592000,
      "voucher": {
        "itemId": "Jvips_Voucher",
        "name": "[THORIUM] Voucher #{voucherIdShort}",
        "lore": [
          "Activates: [THORIUM]",
          "Duration: {durationHuman}",
          "Bound to: {player}",
          "Right click to activate"
        ]
      },
      "commandsOnActivate": [
        "lp user {player} parent add thorium"
      ],
      "commandsOnExpire": [
        "lp user {player} parent remove thorium"
      ]
    }
  }
}

`command_vouchers.json`

{
  "hunterquest": {
    "displayName": "Hunter Quest",
    "voucher": {
      "itemId": "Jvips_Voucher2",
      "name": "Quest Hunt Voucher #{voucherIdShort}",
      "lore": [
        "Quest: [HUNTER]",
        "Bound to: {player}",
        "Right click to start"
      ]
    },
    "commandsOnActivate": [
      { "command": "tp {player} hunterquest", "player_side": false },
      { "command": "tellraw {player} [JVIPS] You started the Hunter Quest!", "player_side": true }
    ]
  }
}

🧩 Dependencies

HyUI is required for the HyUI menu backend (menuvip: "hyui"). Not needed if using "native".
Use a compatible HyUI server build (recommended: HyUI-0.9.3 or later).
Keep HyUI as a separate server mod (JVIPS uses it as dependency, not bundled).
PlaceholderAPI (optional) — enables %jvips_*% placeholders for other plugins.

📥 Installation

Put JVIPS.jar in your server mods folder.
Put the compatible HyUI jar in your server mods folder.
Start/restart server.
Configure config.json, vips.json, command_vouchers.json, and language files.
Configure permissions (jvips.use, jvips.admin, jvips.chest.*).

⚠️ Known Behavior

Opening /vips menu may present a short visual delay on some clients. After extensive profiling, this was confirmed to be a client-side rendering cost (HyUI framework initialization and image loading), not a server-side or plugin performance issue. Server-side data is served from in-memory cache with near-zero latency. This is a HyUI/client limitation and not something the plugin can fully eliminate.

📦 Data Storage

JVIPS uses per-player file storage for optimal performance. Each player's data is stored in its own file, eliminating write amplification — saving one player never rewrites other players' data.

Directory / File	Description
`data/players/&amp;lt;uuid&amp;gt;.json`	Player VIP state and stack count
`data/history/&amp;lt;uuid&amp;gt;.json`	VIP event log (activations, expirations, removals)
`data/chests/&amp;lt;uuid&amp;gt;.json`	Virtual chest contents
`data/tab-vouchers/&amp;lt;uuid&amp;gt;.json`	VIP vouchers delivered directly to menu TAB
`data/vouchers.json`	VIP voucher issuance and usage records (global)
`data/shop-listings.json`	Active and historical Shop listings (player + admin)
`data/hud-prefs/&amp;lt;uuid&amp;gt;.json`	Per-player VIP HUD screen position (X/Y)

Automatic migration: Servers upgrading from older versions (monolithic players.json, history.json, etc.) will have their data automatically migrated to the per-player format on first startup. Original files are backed up as .bak.

All files use atomic writes (.tmp + move) to prevent corruption on crash.

🔒 Security & Anti-Abuse

✅ Implemented

HMAC signature validation on VIP vouchers
UUID-bound vouchers (VIP and Command)
Server-side validation only
Sequential command execution
Voucher drop-blocking system
Voucher chest guard — blocks vouchers from being placed in external containers (only VIP Chest allowed)
Atomic file writes for persistent data
Custom duration included in HMAC signature
In-memory caching with disk-backed persistence

🔜 Planned

Cooldown per player for activation attempts
Max active vouchers per player
Admin audit log
Webhook support
SQLite storage backend (optional)

📜 License

MIT License