Magic Item Vault

Features

Dual Storage Modes

• Local mode (default) — Offline JSON file storage, no API or Discord required. Works out of the box.
• Web mode — Cloud-synced vaults with a web dashboard, Discord linking, and cross-server transfers.
• Switch between modes at any time via config.json
• /miv import and /miv export commands for migrating vault data between modes (admin-only)

Item Vault

• Each player gets their own vault, separate per server
• Native chest-like UI with the vault's 3D model displayed in the container panel
• Items persist across server restarts and world resets
• Auto-save with smart debouncing to prevent data loss
• Built-in auto-sort support
• Configurable vault capacity (up to 63 slots)

Craftable Vault Block

• Craft the Magic Item Vault at a Workbench (Tinkering category)
• Recipe: 1x Shabby Chest + 5x Gold Bars + 5x Silver Bars
• Place it in the world and press F to open — just like a regular chest
• Custom 3D model with open/close animations (HEAVY WIP)
• Rotatable in 4 directions (N/E/S/W)

Cross-Server Item Transfers (Web Mode)

• Server owners can whitelist other MIV servers to enable item transfers
• Transfers require a bidirectional whitelist — both servers must approve each other
• Transfer items between servers via drag-and-drop on the web dashboard
• Blacklisted items are blocked from transferring to servers that don't allow them
• Full audit logging of all transfers (who, what, from where, to where)

Web Dashboard (Web Mode)

• Full-featured web interface at miv.hytaletravelers.com
• View all your vaults across every server you've played on
• Browse items with search, sort (by name, quantity, rarity), and filtering
• Item detail modal showing ID, quantity, durability, rarity, slot, and metadata
• Drag-and-drop item transfers between whitelisted servers
• Servers grouped by transfer relationships in the sidebar
• Live server online/offline status indicators
• Auto-refresh keeps your vault view up to date (3-second polling)
• Item icons served from the cloud API with caching

Discord Account Linking (Web Mode)

• Link your in-game account to Discord via OAuth on the web interface
• Generate a link code on the website and use /miv link <code> in-game
• One-time setup — stays linked across sessions
• One player per Discord account, one Discord account per player
• In local mode, /miv link is not needed and tells the player so

Server Management (Web Mode Dashboard)

• Register servers and receive an API key
• Configure vault capacity per server (1-63 slots)
• Manage server whitelist — control which servers can send/receive item transfers
• Manage item blacklist — block specific items from being stored in vaults
• Regenerate API keys if compromised
• View server online status (based on last heartbeat)

Commands

Command	Description
/miv vault	Open your vault (also: /miv open, /miv chest, /miv storage)
/miv link <code>	Link your Discord account (web mode only)
/miv status	Check vault system status and configuration info
/miv import	Import vault data from web API to local storage (admin-only)
/miv export	Export vault data from local storage to web API (admin-only)
/miv help	Show all available commands
/miv reload	Reload plugin configuration (admin)
/miv info	Show plugin information (admin)

Configuration

The plugin generates a config.json with inline help for every setting:

• storageMode — "local" (default) or "web"
• vaultCapacity — Number of vault slots (default: 63, used in local mode; web mode fetches from API)
• allowCommandOpen — Allow /miv vault command, or restrict to vault block interaction only
• API settings — apiBaseUrl, apiKey, serverIp (required for web mode; optional in local mode for import/export)
• Server Whitelist — Control which other servers can transfer items to/from yours (web mode)
• Item Blacklist — Prevent specific items from being stored or transferred (web mode)
• Debug Mode — Enable detailed logging for troubleshooting

Icon Sync (Web Mode)

• Item icons are automatically uploaded from the game to the cloud API
• Icons display on the web dashboard next to each item
• Searches base game and mod directories for icon assets
• Pre-loads known icons on startup to minimize uploads

Audit Logging (Web Mode)

• All vault actions are logged: deposits, withdrawals, transfers, linking, server registration
• Each log entry includes timestamp, action type, user, server, item details
• Stored server-side for accountability and debugging

Safety and Reliability

• All vault data saved on window close and player disconnect
• Dirty tracking prevents unnecessary saves/API calls
• Graceful error handling with descriptive in-game messages
• Clickable links in all chat messages for easy navigation
• Detailed status system with setup help and troubleshooting guidance
• Thread-safe session management with read/write locks
• Server IP validation on every API request (web mode)

---

Setup (Server Owners)

Local Mode (Default — No Setup Required)

1. Drop the plugin into your server's mods/ folder
2. Start the server — a default config.json will be created
3. (Optional) Adjust vaultCapacity in config.json
4. Players can immediately craft and use vault blocks

Web Mode

1. Drop the plugin into your server's mods/ folder
2. Start the server — a default config.json will be created
3. Set "storageMode": "web" in config.json
4. Go to miv.hytaletravelers.com and log in with Discord
5. Register your server and copy the API key
6. Paste the API key and set your serverIp in config.json
7. Use /miv reload or restart the server
8. (Optional) Whitelist other MIV servers to enable cross-server transfers

Migrating Between Modes

• To import web vault data into local: set storageMode to "local", keep apiKey and serverIp configured, then use /miv import in-game
• To export local vault data to web: same config, then use /miv export in-game

Setup (Players)

Local Mode

1. Craft or find a Magic Item Vault block and press F to open your vault
2. That's it — no linking or registration needed

Web Mode

1. Visit miv.hytaletravelers.com and log in with Discord
2. Generate a link code
3. In-game, use /miv link <code>
4. Craft or find a Magic Item Vault block and press F to open your vault