🏷 MysticNameTags v1.1.5

🧩 Server Compatibility

• Target Server Version: >= 2026.1.0
• Tested against Hytale server builds 2026.1.x.
• Fully compatible with v1.1.4 configs and data (tags, settings, storage).

🔥 Major Additions

1️⃣ Stat-Powered Tag Requirements

Tags can now unlock based on server-side stats (kills, blocks, damage, etc.).

New fields in tags.json:

"requiredStatKey": "killed.goblin_miner",
"requiredStatValue": 100

• requiredStatKey – string key, e.g.:
  • killed.goblin_miner – per-mob kills
  • killed.Player – player kills
  • mined.hytale:stone – blocks mined
  • custom.damage_dealt – total damage dealt
• requiredStatValue – minimum value required (inclusive).

Behind the scenes, this is powered by the new PlayerStatManager:

• Pluggable backend using the same storageBackend setting as player tags:
  • FILE, SQLITE, MYSQL
• Tracks:
  • Total deaths: custom.deaths_total
  • Total kills: custom.kills_total
  • Per-entity kills: killed.<entityId>
  • Blocks broken/placed, damage dealt/taken, and more
• Includes session-only stats for future placeholder usage.

Example: goblin_slayer requires killed.goblin_miner >= 100.

2️⃣ Item-Based Tag Requirements & Tribute Unlocks

Tags can now require in-game items that are consumed on unlock.

New field in tags.json:

"requiredItems": [
  { "itemId": "blaze_shard", "amount": 16 }
]

Behavior:

• All listed items must be present in the player’s inventory.
• On successful unlock:
  • Required items are removed using core Hytale inventory APIs (ItemContainer, ItemStackTransaction).
• If the check fails or removal fails:
  • Unlock is aborted and inventory is left untouched.

This is handled via:

• IntegrationManager → ItemRequirementHandler
• Default implementation: HytaleInventoryItemRequirementHandler
  • Resolves a player’s main inventory container
  • Counts and removes items safely in stack-sized chunks

Example: ember_initiate requires a tribute of 16× Blaze Shard to unlock.

3️⃣ Smart Requirements Panel – Human-Readable Names

The tag UI hover panel has been upgraded to show clean, player-facing descriptions of all requirements.

When you hover the info icon:

• Permissions
  • Shows the raw permission node (if any).
• Playtime
  • e.g. Playtime Required: 60 minutes
• Owned Tags
  • Uses tag display names instead of IDs:
    • + [Wanderer]
    • - [Goblin Slayer]
• Stat Requirements
  • Shows the stat and value in a readable format:
    • Stat Required: kills.goblin_miner: 100+
• Item Requirements
  • Uses item display names derived from IDs (where available), e.g.:
    • - 16x Blaze Shard
• Purchase Cost
  • Shows the correct wording for cash vs coin vs disabled economy.
• Status Line
  • Makes it crystal clear why it’s locked:
    • Status: LOCKED (requirements not met)
    • Status: LOCKED (not purchased)
    • Status: AVAILABLE

The panel now mirrors exactly what the tag is gating on, without raw internal IDs leaking through.

4️⃣ Reliable Kill / Death Tracking via Native Death System

The internal death tracking has been rewritten to hook directly into Hytale’s DeathSystems.OnDeathSystem, similar to EcoTale’s quest system:

• Only runs when DeathComponent is actually added (i.e. on real deaths).
• Resolves killer via:
  • DeathComponent.getDeathInfo().getSource()
  • Fallback to NPC damageData.getMostDamagingAttacker() / getAnyAttacker() for mob deaths.
• Tracks:
  • Player deaths → custom.deaths_total
  • Player kills vs players/NPCs:
    • custom.kills_total
    • killed.<entityId>

Entity ID rules:

• Player victims → "Player"
• NPC victims → npc.getNPCTypeId().toLowerCase() (or role-based fallback)
• Unknown → "npc" / "unknown" as safe fallbacks

This ensures stat-based tags like Goblin Slayer and Dragon Soul unlock correctly and consistently.

5️⃣ Example Challenge & Progression Tags

To showcase the new systems, a sample tags.json snippet is provided (safe to modify or delete):

• wanderer – 1 hour playtime gate
• goblin_slayer – 100 goblin kills via killed.goblin_miner
• ember_initiate – 16× blaze_shard tribute
• avalon_knight – requires both Wanderer + Goblin Slayer
• dragon_soul – stat + playtime + permission mix
• primordial_founder – multi-layered “ultimate” tag using all systems
• supporter – example of onUnlockCommands combined with permission-based granting

These examples are purely configuration and can be removed or adapted for your server’s lore.

⚙ Improvements

• Unified requirement evaluation:
  • Playtime, stats, owned tags, items, permissions, and purchase cost now feed into a single lock status.
• Better economy/requirement messaging:
  • Clearer reasons when economy is disabled but a price is set.
• Safer integration bridging:
  • Item requirement & stat providers fail open where appropriate (so missing integrations don’t hard-brick tags).
• More defensive logging around stats, inventory, and death tracking to help diagnose edge cases.

🚀 Performance

• Death tracking runs only when a DeathComponent is added – no extra ticking systems.
• Stat writes reuse the existing multi-backend storage logic from MysticNameTags.
• Inventory checks operate in a single pass and only when:
  • Hovering a tag with item requirements, or
  • Actually attempting to unlock/purchase a tag.

No additional background tasks or loops were introduced.

🐛 Bug Fixes

• Fixed cases where deaths caused by certain damage types were not counted correctly.
• Fixed potential desync when unlocking tags that both cost currency and require items.
• Hardened against null/blank stat keys and malformed item requirements in tags.json.
• Improved resilience when stat or inventory integrations throw unexpected exceptions (stats will log and fall back safely).
• Fixed Console Commands not running correctly