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.<slots>
/vips sellvoucher <currency> <price>	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 <vip> <player> [--duration time]	Gives a VIP voucher directly to the player's Vouchers TAB	jvips.admin
/vips givecmd <id> <player>	Gives a Command Voucher	jvips.admin
/vips add <player> <vip> [--duration time]	Grants VIP directly (optional custom duration)	jvips.admin
/vips remove <player> <vip>	Removes VIP immediately	jvips.admin
/vips sellkey <vip> <currency> <price> [--duration time]	Lists a VIP voucher for sale as the server (admin shop)	jvips.admin
/vips unsellkey <slot>	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.<slots>	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

1. Put JVIPS.jar in your server mods folder.
2. Put the compatible HyUI jar in your server mods folder.
3. Start/restart server.
4. Configure config.json, vips.json, command_vouchers.json, and language files.
5. 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/<uuid>.json	Player VIP state and stack count
data/history/<uuid>.json	VIP event log (activations, expirations, removals)
data/chests/<uuid>.json	Virtual chest contents
data/tab-vouchers/<uuid>.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/<uuid>.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