Authoring Abilities & Ability Mods

The filename (lowercased at decode) is the ability id, e.g. Arcane_Missiles.json decodes to arcane_missiles. AbilityCatalog folds every decoded instance and both ActiveAbilityService and PassiveAbilityTriggers read it directly for cast dispatch - the asset is the runtime ability, not just descriptive content. A pack file with the same id as a jar default overrides it entirely unless it uses Parent (see below).

Top-level groups

Every group, and every leaf inside every group, is registered appendInherited: a Parent-linked child that overrides only Cooldown.Ms still inherits Cost, Effects, Presentation, and every other leaf from the parent. The one exception is Effects itself - see EffectStep.

Identity

Cooldown

Cost (Java type CastCost)

XpRouting

Casting

Targeting

Presentation

A shared type used at multiple call sites - see Presentation below for the full field reference and both scopes it appears at.

PassiveTrigger

{
  "Identity": { "NameKey": "ability.arch_passive_clean_kill.name", "Icon": "Weapon_Arrow_Iron", "Passive": true },
  "XpRouting": { "Skills": ["$HELD"] },
  "Effects": [
    { "Type": "Heal", "Presentation": { "Sound": "SFX_Health_Potion_High_Drink" },
      "Heal": { "Amount": 8.0, "IntervalMs": 1000, "DurationMs": 0, "EntityEffect": "MMO_CleanseAura", "ViaLifesteal": false } }
  ],
  "PassiveTrigger": { "On": "on_kill", "Filter": "any", "RequiresWeaponSkill": "ARCHERY" }
}

Damage schools and Cause

Every damage-bearing step leaf (Damage, Dot, Zone, Beam, an OnHit sub-step, and NativeChain) carries an optional Cause string naming a DamageCause asset id. Six ids are the mod's damage schools: Fire and Ice are vanilla; Lightning, Water, Arcane, and Void are MMO-authored, each Parent-ing the vanilla Elemental cause. A non-school vanilla cause (Physical, Slashing, Bludgeoning, Poison, ...) is equally valid. An unset or unresolvable Cause falls back to Physical silently at runtime, but AbilityValidator errors an unresolvable one at /mmoconfig validate time.

"Damage": { "Amount": 45, "Cause": "Ice" }

The EffectStep union

Each Effects[] entry is {"Type": "<Kind>", "<Kind>": {...}, "Presentation": {...}?, "SummaryHidden": true?}. Type picks exactly one matching nested group. Damage, Projectile, Dash, Beam, and ArmNextHit each carry their own OnHit: EffectStep[] - a hit-triggered sub-chain, recursive over the same EffectStep type. SummaryHidden: true marks a step whose mechanic is already described by a sibling step (tooltip-only, never changes runtime behavior).

Amount-type fields are double unless noted; *Ms fields are long; unmarked fields are optional/nullable.

Worked step examples

A caster-centered AOE fire burst on hit, from the jar-shipped Fireball ability:

{ "Type": "Projectile",
  "Projectile": {
    "Asset": "MMO_Fireball",
    "Impact": { "Sound": "SFX_Staff_Flame_Fireball_Impact", "Particles": "Explosion_Medium" },
    "OnHit": [ { "Type": "Damage", "Damage": { "Amount": 40.0, "Radius": 4.0, "Cause": "Fire" } } ],
    "RaycastMode": false, "MaxDistance": 20.0, "Count": 1, "IntervalMs": 0
  } }

A summon step, from the jar-shipped Summon Wolf ability:

{ "Type": "Summon",
  "Summon": { "RoleId": "MMO_Summoned_Wolf", "DurationMs": 30000, "Count": 1, "Offset": { "Y": 1.0 } } }

Scaling

An optional nested group on Damage/Dot/Zone/Beam's per-hit/per-tick Amount. Snapshot once at cast/apply time, never re-evaluated per tick. Two composable sub-groups fold additively into one factor:

amount *= (1 + statMax * PerStat.PerPoint + skillLevel * PerSkillLevel.PerLevel)

"Damage": { "Amount": 20, "Cause": "Physical",
  "Scaling": { "PerSkillLevel": { "Skill": "SWORDS", "PerLevel": 0.02 } } }

Presentation (shared type)

The same Presentation shape appears at two scopes: the ability's top-level field (the cast moment, plays once per successful cast, skipped entirely for a passive ability) and each EffectStep's own Presentation (the step's own moment). Teleport.Arrive and Projectile.Impact are typed sub-moments of the same shape.

"Presentation": { "Sound": "SFX_Staff_Flame_Fireball_Launch", "Particles": "Fire_Charge_Soak1" }

Parent inheritance for ability variants

A pack file can set a top-level Parent pointing at any other ability id (jar default, another pack's ability, or the owner overlay). Every top-level group leaf is inherited unless the child restates it - the smallest possible variant overrides one field:

{ "Parent": "fireball", "Cooldown": { "Ms": 5000 }, "Cost": { "Stat": "MANA", "Amount": 20 } }

This is confirmed by AbilityAssetCodecTest: a child overriding only Cooldown.Ms still inherits Cost, Effects, Presentation, and every other leaf from the parent. Remember the one exception - Effects is whole-array-only (see EffectStep).

Precedence and reload

1. 1

   Jar defaults

   src/main/resources/Server/MMOSkillTree/Abilities/*.json - 91 files.
2. 2

   Pack content

   Server/MMOSkillTree/Abilities/<id>.json in any installed pack. A matching id fully replaces the default unless it uses Parent.
3. 3

   Owner overlay

   mods/mmoskilltree/ability-overrides.json folds last, per-leaf - the same overlay semantics as Parent. Shape: {"schemaVersion":1,"abilities":{"<id>":{...PascalCase AbilityAsset body...}}}.

ability-settings.json is the separate override config that gates the whole active-ability system on/off (AbilitySettingsConfig.enabled, the abilities feature-gate id) - it does not touch individual ability tuning, that is what ability-overrides.json is for.

/mmoability reload (admin) re-folds the catalog from live pack state plus a fresh disk re-read of ability-overrides.json. It does not force-rescan a brand-new zipped pack - that still needs a server restart.

Native-chain damage attribution

A NativeChain step's native re-caused Damage needs its own DamageCause leaf to attribute XP/masteries/rewards through the declaring ability instead of the held-weapon fallback. For jar-shipped abilities this is fully automatic (SchoolCauseGenerator pre-scans the jar defaults plus ability-overrides.json at startup and auto-registers MMO_Cause_<AbilityPascal> per ability).

{ "Parent": "PhysicalDamageCause", "Inherits": "PhysicalDamageCause" }

Then reference it: "NativeChain": { "Interaction": "...", "Cause": "MMO_Cause_My_Native_Ability" }. DamageCause assets decode before Interaction assets in Hytale's own load order, so no special pack ordering is needed.

paramKey resolution for modifiers

A mastery node or skill-tree reward that targets an ability (a FLAT/PERCENT/OVERRIDE/ADD_PARAM modifier keyed by a paramKey like damage or cooldownMs) only takes effect if that key resolves to a real field on the ability's authored step chain. AbilityValidator checks every authored paramKey against the engine's binding table and errors an unresolved one (surfaced by /mmoconfig validate) - an unresolved key would otherwise silently drop the modifier at cast time.

Minimal example

{
  "Identity": { "NameKey": "ability.my_spark.name", "DescKey": "ability.my_spark.desc", "Icon": "Ingredient_Lightning_Essence" },
  "Cooldown": { "Ms": 6000 },
  "Cost": { "Stat": "MANA", "Amount": 15 },
  "XpRouting": { "Skills": ["MAGIC"] },
  "Effects": [ { "Type": "Damage", "Damage": { "Amount": 18, "Cause": "Lightning" } } ]
}

Full example (jar default, real)

{
  "Name": "fireball",
  "Identity": { "NameKey": "ability.fireball.name", "DescKey": "ability.fireball.desc", "Icon": "Weapon_Staff_Crystal_Flame" },
  "Cooldown": { "Ms": 8000 },
  "Cost": { "Stat": "MANA", "Amount": 30 },
  "XpRouting": { "Skills": ["MAGIC"] },
  "Effects": [
    { "Type": "Projectile",
      "Projectile": {
        "Asset": "MMO_Fireball",
        "Impact": { "Sound": "SFX_Staff_Flame_Fireball_Impact", "Particles": "Explosion_Medium" },
        "OnHit": [ { "Type": "Damage", "Damage": { "Amount": 40.0, "Radius": 4.0, "Cause": "Fire" } } ],
        "RaycastMode": false, "MaxDistance": 20.0, "Count": 1, "IntervalMs": 0
      } }
  ],
  "Presentation": { "Sound": "SFX_Staff_Flame_Fireball_Launch", "Particles": "Fire_Charge_Soak1" }
}

Ability Mods Since 1.6.0

A grantable, player-facing improvement to an existing ability - a mastery-tree reward, a quest prize, or a shop offer that permanently buffs one specific ability rather than a whole skill.

Modifier grammar (7 shapes)

Shared with mastery-node modifiers (AbilityModifierJson) - see also Masteries for the mastery-node side of the same grammar. shape is required, uppercase, defaults to FLAT if omitted.

FLAT

Adds a flat amount to the target field.

{ "shape": "FLAT", "key": "damage", "value": 4 }

PERCENT

Adds a percent multiplier to the target field.

{ "shape": "PERCENT", "key": "damage", "value": 0.15 }

OVERRIDE

Replaces the target field outright.

{ "shape": "OVERRIDE", "key": "cooldownMs", "value": 4000 }

ADD_PARAM

Adds a brand-new numeric param the base ability did not have.

{ "shape": "ADD_PARAM", "key": "armorPenetration", "value": 0.2 }

CONDITIONAL

Wraps another modifier so it only applies when a condition passes.

{ "shape": "CONDITIONAL",
  "condition": { "selfHpMax": 0.5, "hostileOnly": true },
  "apply": { "shape": "PERCENT", "key": "damage", "value": 0.25 } }

condition fields: selfHpMin, selfHpMax, targetHpMin, targetHpMax, hostileOnly, onCritOnly, filter. apply is a nested modifier object of any other shape.

TRIGGER

Fires an event-keyed effect rather than modifying a field.

{ "shape": "TRIGGER", "triggerEvent": "on_kill", "payload": { "healPercent": "0.1" } }

ADD_STEP

Splices a whole authored step into the target ability's chain - the same schema as an Effects entry.

{ "shape": "ADD_STEP", "insertAnchor": "ON_HIT", "sourceId": "council_arcane_focus",
  "stepPayload": { "Type": "ApplyEffect", "ApplyEffect": { "EffectAsset": "MMO_Slam_Slow", "DurationMs": 2000 } } }

Every shape also accepts optional scoping fields: targetAbility, targetSkill, combatTarget.

Granting

Grant through the unified Reward model's ABILITY_MOD kind:

{ "type": "ABILITY_MOD", "modId": "council_arcane_focus" }

from a quest reward, a dialogue Reward action, or a shop entry - the same one-shot pipeline every other reward kind uses, including the offline-retry queue. /mmoability grantmod and /mmoability revokemod (admin) do the same by console command for testing.

Real example

{
  "Name": "Council_Arcane_Focus",
  "TargetAbility": "arcane_missiles",
  "NameKey": "abilitymod.council_arcane_focus.name",
  "DescKey": "abilitymod.council_arcane_focus.desc",
  "Modifiers": [
    { "shape": "FLAT", "key": "damage", "value": 4 },
    { "shape": "ADD_STEP", "insertAnchor": "ON_HIT", "sourceId": "council_arcane_focus",
      "stepPayload": { "Type": "ApplyEffect", "ApplyEffect": { "EffectAsset": "MMO_Slam_Slow", "DurationMs": 2000 } } }
  ]
}