🏷 MysticNameTags v1.1.4

🧩 Server Compatibility

• Target Server Version: >= 2026.1.0
• Tested against Hytale server builds 2026.1.x.
• Backwards-safe within the supported API range.

🔥 Major Additions

1️⃣ Advanced Tag Requirement System

Tags now support layered unlock conditions, enabling rich progression flows.

New supported fields in tags.json:

• requiredPlaytimeMinutes
• requiredOwnedTags
• onUnlockCommands
• (plus existing permission, purchasable, price, category)

You can now build tags that require:

• Permission only
• Playtime only
• Owning other tags
• Purchase only
• Any combination of the above

Including full-gated tags like:

Permission + Playtime + Owned Tags + Purchase

2️⃣ On Unlock Console Commands

Tags can now run commands from console the first time a player unlocks them.

Example:

"onUnlockCommands": [
  "give <player> diamond 3",
  "broadcast &6<player> has unlocked the Primordial tag!"
]

• <player> is automatically replaced with the player’s name
• Commands only run once per player per tag
• Safe for:
  • Rank promotions
  • Item rewards
  • Crate/key grants
  • Global announcements
  • Custom server logic

3️⃣ Multi-Backend Storage (FILE / SQLite / MySQL)

MysticNameTags now supports multiple storage backends for player tag data.

New option in settings.json:

"storageBackend": "FILE" // FILE, SQLITE, MYSQL

Supported backends:

• FILE
  • Default, fully backwards compatible
  • Uses playerdata/*.json files
• SQLITE
  • Single local SQLite DB file
  • Config:

    "storageBackend": "SQLITE",
    "sqliteFile": "playerdata.db"
    

• MYSQL
  • External MySQL/MariaDB database
  • Config:

    "storageBackend": "MYSQL",
    "mysqlHost": "localhost",
    "mysqlPort": 3306,
    "mysqlDatabase": "mysticnametags",
    "mysqlUser": "root",
    "mysqlPassword": "password"
    

All getters provide sane fallbacks, and the system is safe for upgrades from older versions.

4️⃣ Language & UI Localization System

New language layer for translated messages and localized UI.

Core behavior:

• Language is configured via settings.json:

  "language": "en_US"
  

• Messages are stored under:
  • lang/<locale>/messages.json
• Default English keys are defined internally and:
  • Auto-write to lang/en_US/messages.json
  • Backfill missing keys on upgrades without overwriting existing values
• Selected locale:
  • Has its own messages.json
  • Missing keys are automatically backfilled from en_US

Localized UI Overrides

MysticNameTags can localize and customize UI layouts per locale:

• UI override path:
  • lang/<locale>/ui/mysticnametags/Dashboard.ui
  • lang/<locale>/ui/mysticnametags/Tags.ui
• On first load:
  • The plugin exports bundled .ui files to the locale folder
  • If a localized override exists, it is used instead of the bundled asset

This allows full customization of:

• Labels
• Captions
• Small text
• And even layout tweaks per locale

All while preserving a fallback to en_US if something is missing.

5️⃣ MiniMessage Support for Tags

MysticNameTags now supports MiniMessage formatting inside tag display values.

Supported:

• <gradient>
• <color>
• <bold>, <italic>, <underlined>
• <rainbow>
• Other standard MiniMessage tags

Legacy formats remain fully supported:

• & legacy color codes
• &#RRGGBB hex codes

⚠ Due to Hytale’s current API limitations, nameplate coloring is still restricted. Formatting applies primarily to UI and chat components.

6️⃣ Physical Economy: Coins & Markets

Expanded economy support to include physical currency via:

• Coins & Markets

MysticNameTags now supports:

• Standard ledger-based economies:
  • TheEconomy (recommended)
  • VaultUnlocked
  • EcoTale
  • EliteEssentials (fallback)
• Physical/item-based economies:
  • Coins & Markets (inventory/pouch-based coin system)

Config flags:

"economySystemEnabled": true,
"useCoinSystem": false,
"usePhysicalCoinEconomy": false

Economy checks remain on-demand only, triggered when:

• Opening /tags
• Purchasing a tag

No background loops. No ticking tasks. No polling.

⚙ Improvements

• Refined requirement evaluation order to minimize redundant checks.
• Cleaner unlock failure reasoning for complex requirements.
• Improved category fallback ("General" when missing/blank).
• Strengthened unlock tracking to prevent duplicate command execution.
• Centralized language key definitions for easier maintenance and upgrades.
• Automatic export of UI .ui files per locale for easy customization.
• Improved resilience when placeholder APIs (WiFlow / at.helpch) are present or missing:
  • Auto-detects at runtime
  • Toggles integration flags accordingly
  • Writes resulting state back to settings.json

🚀 Performance

• No new ticking loops introduced.
• No additional schedulers beyond existing integrations.
• Storage backend handling is lightweight and cached.
• Language loading:
  • Performed on startup / reload only
  • Uses in-memory maps at runtime

Tag evaluation and UI logic remain event-driven and low overhead.

🐛 Bug Fixes

• Fixed rare edge case where requiredOwnedTags could mis-evaluate with a cold cache.
• Fixed potential duplicate onUnlockCommands execution during rapid UI actions.
• Fixed minor inconsistencies when switching between storage backends.
• Improved error logging for language file and UI export failures.
• Ensured language and UI files always regenerate missing keys/overrides gracefully.

🔧 Configuration Notes

All new features are:

• Optional
• Backward compatible
• Auto-upgraded via:
  • settings.json defaults and backfill
  • lang/*/messages.json key injection
  • UI override export

Existing installations can update to v1.1.4 without manual file editing. New options will simply appear in config and lang files on first boot or reload.

MysticNameTags continues to prioritize:

Performance. Stability. Clean Integration. Modern UX.