Download

Weapon Skill Tags

Associate a weapon with a combat skill via a tag in its item JSON

Overview

Added in v1.0.3. When a player swings a weapon, MMO Skill Tree decides which combat skill earns the XP (Swords, Staves, Magic, Archery, and so on). It resolves the weapon to a skill in two steps:

  1. XP-map lookup (primary). The held item's ID is matched against the weapon patterns in xp-maps.json using longest-substring matching. This is the standard route and is covered on the XP Values page.
  2. Weapon skill tag (fallback). If no xp-map pattern matches the item ID, the resolver reads the item's MMO_Weapon_Type tag and routes XP to the first listed value that names a registered skill.

The tag exists for mod and content-pack authors who ship new weapons. It lets a weapon earn the right combat skill XP out of the box, without asking server admins to edit xp-maps.json. Every base-game Hytale weapon is already covered by the built-in xp-maps, so the tag matters specifically for custom weapons whose item IDs do not contain a pattern the xp-maps recognize - the xp-map lookup misses and the tag takes over.

Where the tag goes

Add an MMO_Weapon_Type entry to the top-level Tags object of the weapon's item JSON, alongside the standard Hytale Type / Family entries. The value is a JSON array of strings; at least one entry must be the ID of a registered skill (built-in or custom).

Hytale weapons keep their tags in an uppercase Tags block. Here is a real base-game staff (Weapon_Staff_Wood) - its item ID comes from the filename, and the Tags block sits alongside the other item fields (model, interactions, and icon are trimmed here for brevity):

{
  "TranslationProperties": {
    "Name": "server.items.Weapon_Staff_Wood.name"
  },
  "Categories": ["Items.Weapons"],
  "Quality": "Common",
  "ItemLevel": 40,
  "Tags": {
    "Type": ["Weapon"],
    "Family": ["Staff"]
  }
}

Base-game weapons don't need the tag

A weapon like Weapon_Staff_Wood already resolves to a skill through the default xp-maps (it maps to STAVES), so adding MMO_Weapon_Type to a base-game item changes nothing - the xp-map always wins. The shape above is shown so you can model your own weapon on it.

When you author your own weapon in a content pack, use the same format and add MMO_Weapon_Type to its Tags block. Because a custom item ID does not match any xp-map pattern, the tag is what routes it. Here a custom staff is routed to the STAVES skill:

{
  "TranslationProperties": {
    "Name": "mypack.items.Weapon_Voidcaller_Staff.name"
  },
  "Categories": ["Items.Weapons"],
  "Quality": "Epic",
  "ItemLevel": 60,
  "Tags": {
    "Type": ["Weapon"],
    "Family": ["Magic"],
    "MMO_Weapon_Type": ["STAVES"]
  }
}

Spelling and casing matter

  • The block is Tags with a capital T - the same block Hytale uses for Type and Family. A lowercase tags block is not read.
  • The key is MMO_Weapon_Type, case-sensitive and spelled exactly.
  • The value is an array of strings, even for a single skill: ["STAVES"].

Matching rules

  • Values are matched case-insensitively. ["Staves"], ["staves"], and ["STAVES"] all route to the same STAVES skill.
  • Array order is priority - first registered skill wins. Given ["UNKNOWN_SKILL", "BLUNT"], the resolver skips UNKNOWN_SKILL (not registered) and routes to BLUNT. Use this to declare a primary skill with fallbacks.
  • The value must be a registered skill ID - built-in (e.g. SWORDS, MAGIC, STAVES, ARCHERY) or custom (added via custom-skills.json). There is no combat-vs-gathering filter, so a pack could deliberately route a weapon to MINING for themed content.
  • The tag only fires when the xp-map lookup misses. If the item ID substring-matches a pattern in any skill's xp-map (e.g. the ID contains Weapon_Longsword_, which is in the SWORDS map), that wins and the tag is not consulted.
  • No match falls through to UNARMED - the same behavior as any unmapped, untagged weapon.

What the tag affects

The tag is routing only. Once a skill is chosen, the rest of the system treats the weapon exactly like any other weapon for that skill:

  • Damage-based combat XP (the damage_based and damage_plus_kill modes) routes 1:1 damage XP to the tagged skill. This is the primary win - modded weapons immediately earn XP for the right skill.
  • Weapon-gated tree rewards, lifesteal, and crit from the tagged skill fire under that skill.
  • Active ability cast predicates that require a specific weapon skill see the tagged skill (e.g. a STAVES-locked ability can be cast while holding a tag-routed STAVES weapon).
  • The View XP page's "Equipped Weapon Skill" line displays the tagged skill name and its combat-stat buffs.

Routing does not change XP amounts. In per_hit mode and for the kill-XP weapon-quality bonus (weaponXpScaling), a tag-routed weapon awards 0 XP / 0% bonus until you add an explicit item-ID entry to xp-maps.json for it. See Combat XP Modes for how each mode decides the XP amount.

Valid skill IDs

The tag value must be a registered skill ID. The built-in combat skills are SWORDS, DAGGERS, AXES, BLUNT, POLEARMS, STAVES, ARCHERY, ARTILLERY, MAGIC, and UNARMED. See the Combat skills reference for what each one covers. Skills you add through custom-skills.json are valid values too - use the exact custom skill ID.

Troubleshooting

If a tagged weapon is not earning the expected skill XP, check, in order:

  • Is the block named Tags (capital T)? A lowercase tags block is ignored by Hytale's item loader.
  • Is the key spelled exactly MMO_Weapon_Type? The lookup is case-sensitive.
  • Is the value a registered skill? An unknown skill ID is skipped. Verify the ID against the built-in list above or your custom-skills.json.
  • Is an xp-map pattern already claiming the item? The tag only fires when the xp-map lookup misses. If the item ID contains a known weapon pattern, that route wins - remove or adjust the conflicting xp-maps.json entry, or rely on it instead.
  • Did the pack load? Confirm the item asset is actually installed (the weapon appears in game with its custom name) so the tag is present at runtime.