Vonix Server Utilities — Playtime & Event Crates

Release Line: 2.0.2 Virtual CratesServer-Authoritative

VSU includes a command-based virtual crate subsystem. Keys are held as persistent digital balances in SQLite, preventing physical item duplication bugs.

1. Virtual Keys Architecture

Rather than relying on physical custom items with NBT lore (which can be vulnerable to modded container duplication exploits), VSU uses virtual typed keys:

• Virtual key balances are tied directly to player UUIDs in config/vonix_server_utilities/data.db.
• Keys cannot be dropped, traded via illicit modded hoppers, or duplicated.
• Keys can be awarded via playtime milestones, vote listeners, or manual staff distribution.

---

2. Crate Commands

Command	Permission Node	Op Fallback	Description
/crate open <type>	vsu.command.crate	0	Open a virtual crate using one of your stored keys.
/crate prizes <type>	vsu.command.crate	0	View transparent percentage drop tables for that crate.
/crate key give <player> <type> [amount]	vsu.admin.crate	3	Award virtual keys to a player (e.g. for server events).

Example Operations

# Award 3 voting keys to Steve
/crate key give Steve vote 3

# Inspect drop rates for the event crate
/crate prizes event

# Player opens a vote crate
/crate open vote

---

3. Server-Authoritative Prize Dispatch

When a player opens a crate, the server executes a random roll against the configured prize table:

1. Roll Evaluation: The server generates a cryptographic roll and selects the winning entry according to its weight.
2. Command Dispatch: The reward command is dispatched directly from the server console thread.
3. Platform-Specific Adaptations:
   • Minecraft 1.18.2: Uses performCommand and TextComponent.
   • Minecraft 1.19.2 & 1.20.1: Uses performPrefixedCommand returning integer success codes.
   • Minecraft 1.21.1 NeoForge: Because performPrefixedCommand returns void in modern NeoForge, VSU hooks CommandResultCallback on the command source stack to verify successful prize claim or initiate an automatic key refund if inventory delivery fails.

---

4. Configuring Crate Drop Tables

Crates are defined with weighted tables. A prize with weight 50 in a pool of total weight 100 has an exact 50% probability.

Operators can inspect transparent percentages in-game with /crate prizes <type>, ensuring full compliance with server fairness standards.