Authoring Mastery Tracks

A mastery track is one structured file with PascalCase fields at the top level - there is no Name/Payload wrapper. The filename, lowercased, is the runtime track id; Nodes is a map keyed by node id, in display order. It is the same schema wherever a track body appears: a pack file, a generator's Child, or an entry in the owner's mastery.json overlay.

{
  "Parent": "mastery_base",
  "Target": "skill:SWORDS",
  "Requires": { "Factors": [ { "Factor": "hytale:stat", "Param": "MMO_Level_SWORDS", "Min": 16 } ] },
  "Nodes": {
    "swp_t1": {
      "Tier": 1,
      "Cost": { "Currencies": { "mastery_point": 3 },
                "Items": [ { "Item": "Ingredient_Lightning_Essence", "Count": 1 } ] },
      "Modifiers": [ { "Shape": "PERCENT", "ParamKey": "damage", "Value": 0.08,
                       "TargetSkill": "SWORDS", "CombatTarget": "SWORDS" } ]
    }
  }
}

Track fields

Node fields

Each entry under a track's Nodes map:

Track and node gates

A track's or a node's Requires is the same gate block a quest, a shop entry, a board band or an NPC placement uses, so one spelling covers every kind of condition and a mastery gate can read anything the rest of the server can.

• A skill level is a bound on that skill's level reading: factor hytale:stat, param MMO_Level_<SKILL>.
• Another mastery node is factor mmoskilltree:mastery_node, param "<track>:<node>", minimum 1.
• AnyOf opens the node behind either of two earlier picks; AllOf and Not compose the rest.

"Requires": {
  "Factors": [ { "Factor": "hytale:stat", "Param": "MMO_Level_MINING", "Min": 40 } ],
  "AnyOf": [
    { "Factors": [ { "Factor": "mmoskilltree:mastery_node",
                     "Param": "fireball_mastery:fb_t2_radius", "Min": 1 } ] },
    { "Factors": [ { "Factor": "mmoskilltree:mastery_node",
                     "Param": "fireball_mastery:fb_t2_pierce", "Min": 1 } ] } ]
}

A locked track or node lists every requirement the player has not met, not just the first one, so a well-authored gate reads as a shopping list in game. The mastery audit domain (/mmoconfig validate) checks every ability id, skill id, paramKey and cross-node gate reference a track makes, so a dangling one is reported instead of silently inert.

Node StatSacrifice

A mastery-only cost component paid in a stat, sitting on the node BESIDE the Cost group: { "Stat": "HEALTH"|"STAMINA"|"MANA", "Mode": "permanent_max", "Amount": N }.

Costs & respec

Cost is the shared price group every other priced thing on the server speaks: Currencies, Items as [{Item, Count}], and Combine where Any charges exactly one route. Omitting Cost entirely defaults a node to free.

Respec refunds a percentage of everything spent on a track, walking node RefundPercent to track RefundPercent to the global respec.defaultRefundPercent in mods/mmoskilltree/mastery.json. A StatSacrifice's permanent_max reduction is restored in full on respec regardless of refund percent (the stat cap itself is not a currency to be partially refunded).

The modifier grammar

Modifiers entries are the same grammar an ability improvement uses (the grantable Mmo_Ability_Mod reward) - see Authoring Abilities for the shapes and the paramKey vocabulary for the 17 names a modifier's ParamKey has to resolve against, plus how a pack declares one of its own.

School-scoped modifiers

A damage or schoolResist value can be narrowed to one of the nine damage schools instead of a skill or an ability, so a node reads "+5% Fire damage" or "+4% Void resistance" rather than naming any particular attack. damage mirrors onto the attacker-side MMO_Bonus_<School>/MMO_BonusFlat_<School> pair (FLAT or PERCENT); schoolResist mirrors onto the victim-side MMO_SchoolResist_<School> channel (PERCENT only) - see Gear stats: per-school stats for the same channels gear reaches.

A school bonus is decided by the hit's damage school, not by which skill threw it, so a school track wants "Target": "global": a skill-scoped track only emits for abilities inside its own skill, and the abilities that carry one school are scattered across several skills.

+5% Fire damage on every hit of that school, whatever produced it:

{ "Shape": "PERCENT", "ParamKey": "damage", "School": "Fire", "Value": 0.05 }

+4% Void resistance, worn on the victim side:

{ "Shape": "PERCENT", "ParamKey": "schoolResist", "School": "Void", "Value": 0.04 }

The five shapes, one worked example each

FLAT - adds a flat amount to the target leaf (allowed on repeatable nodes):

{ "Shape": "FLAT", "ParamKey": "damage", "Value": 5, "TargetAbility": "sword_slash" }

PERCENT - multiplies the target leaf (allowed on repeatable nodes; the loot-multiplier convention):

{ "Shape": "PERCENT", "ParamKey": "lootMultiplier", "Value": 0.03, "TargetSkill": "MINING" }

SET - replaces the target leaf outright, or injects a cast parameter the base ability did not author (single-purchase only):

{ "Shape": "SET", "ParamKey": "cooldownMs", "Value": 4000, "TargetAbility": "dash" }

A conditioned modifier is any of the shapes above carrying a Condition (single-purchase only) - "+25% damage to targets under 30% health" is one PERCENT line:

{ "Shape": "PERCENT", "ParamKey": "damage", "Value": 0.25,
  "TargetAbility": "sword_slash",
  "Condition": { "TargetHp": { "Max": 0.3 } } }

TRIGGER - subscribes the player to an EXISTING passive ability's own PassiveTrigger group (event/filter/weapon/HP gates), rather than injecting a new effect (single-purchase only). TargetAbility names that passive ability's id - it must already exist in the ability catalog as a passive asset:

{
  "Shape": "TRIGGER",
  "TargetAbility": "bleed_on_hit_passive",
  "TriggerEvent": "HitDealt"
}

ADD_STEP - splices an extra piece of chain into the target ability's Body (single-purchase only). InsertAnchor is one of START, END or ON_HIT, matching the anchor nodes the target body authors, and StepPayload is the id of an interaction fragment your pack ships, not an inline block of steps:

{
  "Shape": "ADD_STEP",
  "TargetAbility": "sword_slash",
  "InsertAnchor": "ON_HIT",
  "StepPayload": "MyPack_Frag_Bleed_Pulse"
}

Reuse: Parent and Abstract

Reuse is native Parent inheritance, the same mechanism quests and abilities use. A file marked "Abstract": true is a shared base that never becomes a track of its own; a child names it with "Parent": "<id>", retunes any leaf, and inherits the rest. Nodes merges per node id, and inside a node every group merges per leaf, so a child can retune one price and keep the whole tree.

// Server/MMOSkillTree/Masteries/Mastery_Base.json
{ "Abstract": true, "RefundPercent": 50 }

// Server/MMOSkillTree/Masteries/Axes_Focus.json
{ "Parent": "mastery_base", "Target": "skill:AXES",
  "Nodes": { "axe_t1": { "Tier": 1, "Cost": { "Currencies": { "mastery_point": 3 } },
                         "Modifiers": [ { "Shape": "PERCENT", "ParamKey": "damage",
                                          "Value": 0.08, "TargetSkill": "AXES" } ] } } }

Generators: one file, many tracks

Server/MMOSkillTree/MasteryGenerators/<Id>.json writes a FAMILY of tracks - "the same track, once per skill" - exactly the way quest generators do. Substitution is textual and applies everywhere in Child: every string value, every object KEY (which is how each member gets its own node ids), and IdPattern. A value that is exactly one token keeps that token's type, so "Count": "{count}" lands as a number.

{
  "Base": "mastery_base",
  "IdPattern": "{skillLower}_mastery",
  "ForEach": [ { "Values": [
      { "skill": "SWORDS", "skillLower": "swords", "prefix": "swo" },
      { "skill": "AXES",   "skillLower": "axes",   "prefix": "axe" } ] } ],
  "Child": {
    "Target": "skill:{skill}",
    "Nodes": { "{prefix}_t1": { "Tier": 1,
                                "Modifiers": [ { "Shape": "PERCENT", "ParamKey": "damage",
                                                 "Value": 0.08, "TargetSkill": "{skill}" } ] } }
  }
}

An axis may name a Source some mod enumerates ("mmoskilltree:skills", with an optional "Filter": {"Category": "COMBAT"}) instead of listing Values, so a family grows with the skill roster. Each combination becomes an ordinary child of Base - the same decode a hand-written child gets - and an authored Masteries/ file of the same id always wins, which is how one member of a family is made special.

The owner overlay: mastery.json

A server owner retunes a shipped track from mods/mmoskilltree/mastery.json (schema v3): each entry under tracks is a partial body in this same schema, merged per leaf over the loaded track of that id, so one price can change and everything else stays the pack's.

{
  "schemaVersion": 3,
  "tracks": {
    "swords_mastery": {
      "Nodes": { "swo_t1_dmg": { "Cost": { "Currencies": { "mastery_point": 5 } } } }
    },
    "parked_track": { "Enabled": false }
  }
}

Minimal example

{
  "Target": "skill:MINING",
  "TitleKey": "mastery.simple_mastery.title",
  "Nodes": {
    "smp_t1": {
      "Tier": 1,
      "Cost": { "Currencies": { "mastery_point": 2 } },
      "Modifiers": [
        { "Shape": "PERCENT", "ParamKey": "lootMultiplier", "Value": 0.03, "TargetSkill": "MINING" }
      ]
    }
  }
}

Exhaustive example

A parked two-node track exercising most leaves, an Eternal capstone included:

{
  "Enabled": false,
  "Target": "skill:ACROBATICS",
  "RefundPercent": 50,
  "Requires": {
    "Factors": [ { "Factor": "hytale:stat", "Param": "MMO_Level_ACROBATICS", "Min": 5 } ]
  },
  "Nodes": {
    "acr_t1": {
      "Tier": 1,
      "Cost": {
        "Currencies": { "mastery_point": 2, "life_essence": 500 },
        "Items": [ { "Item": "Ingredient_Lightning_Essence", "Count": 1 } ]
      },
      "Modifiers": [
        { "Shape": "PERCENT", "ParamKey": "lootMultiplier", "Value": 0.03, "TargetSkill": "ACROBATICS" }
      ]
    },
    "acr_eternal": {
      "Tier": 9,
      "Prerequisites": ["acr_t1"],
      "MaxPurchases": -1,
      "CostScaling": { "Curve": "EXPONENTIAL", "Multiplier": 1.1 },
      "Cost": {
        "Currencies": { "life_essence": 200 },
        "Items": [ { "Item": "Ingredient_Lightning_Essence", "Count": 2 } ]
      },
      "Modifiers": [
        { "Shape": "PERCENT", "ParamKey": "lootMultiplier", "Value": 0.005, "TargetSkill": "ACROBATICS" }
      ]
    }
  }
}