Custom Skills

Overview

Custom Skills let you define entirely new skills beyond the 20 built-in ones. Each custom skill has a unique ID, display name, category, and trigger types - all configurable through the admin UI or mods/mmoskilltree/custom-skills.json.

You can also disable built-in skills you don't want on your server, and set per-skill max levels to control progression.

Admin UI

The easiest way to manage custom skills is through the admin dashboard. Open /mmoadmin and click Custom Skills.

The page has three sections:

• Max Level Management - Set a default max level for all skills and override it per-skill. Skills with overrides are highlighted orange
• Built-in Skills - View all 20 built-in skills with their category and trigger types. Toggle any skill on/off
• Custom Skills - Create, edit, and delete custom skills with a visual form

Creating Custom Skills

Each custom skill has these fields:

Trigger Types

Trigger types determine which in-game events award XP to the skill. A custom skill can have multiple triggers.

Multiple triggers allow a single skill to level from different actions. For example, a "Survival" skill could trigger on Break Block, Kill Entity, and Take Damage.

XP Configuration

Custom skills have no default XP values - you must configure which blocks, items, or mobs award XP. Use the XP Maps editor in the admin dashboard or edit xp-maps.json directly.

A content pack shipping a skill (see Skills from a content pack below) ships that skill's own XP patterns too, as Server/MMOSkillTree/XpMaps/<Skill>.json beside its CustomSkills file - a pack-shipped skill with no XP map is defined but inert. mods/mmoskilltree/xp-maps.json stays the owner override that wins last.

// xp-maps.json - XP patterns for a custom "HERBALISM" skill
{
  "HERBALISM": {
    "Plant_": 15,
    "Flower_": 10,
    "Herb_Rare": 50,
    "Mushroom_": 20
  }
}

Pattern matching works the same as built-in skills: prefix patterns like Plant_ match any block starting with that prefix. Use -1 to explicitly disable a pattern.

Full Feature Integration

Custom skills integrate with all existing systems:

• Skill Trees - Add reward tiers through the Skill Tree editor. Custom skills support a "+" button to add new tiers since they have no built-in defaults. Combat rewards (Damage, Crit, Lifesteal, Parry) can target your custom skill ID - just enter the skill ID in the Target field
• Item Rewards - Configure command rewards at milestones, just like built-in skills
• XP Maps - Appears in the XP Maps admin editor alongside built-in skills
• Leaderboards - Custom skills appear in leaderboard rankings and category totals
• XP Tokens - Not automatically generated; tokens are only created for built-in implemented skills
• Item Requirements - Reference custom skills in level requirements (e.g., HERBALISM:5,MINING:10)
• Permissions - When skill permissions are enabled, custom skills follow the same permission pattern

Skills from a content pack Since 1.6.0

A content pack adds a whole skill by shipping one file per skill under Server/MMOSkillTree/CustomSkills/. The filename, uppercased, is the skill id (Smithing.json becomes SMITHING), and the skill folds into the roster the same way a built-in does: it shows on the skills page, earns XP, ranks on leaderboards, and can carry tree tiers and rewards.

// Server/MMOSkillTree/CustomSkills/Smithing.json  (filename -> SMITHING)
{
  "Display": {
    "Name": "Smithing",
    "Description": "Forge weapons and armor to gain experience",
    "DescriptionKey": null,
    "Icon": "Icons/ItemsGenerated/Ingredient_Bar_Iron.png"
  },
  "Placement": { "Category": "CRAFTING", "InsertAfter": "ENCHANTING" },
  "Triggers": ["CRAFT_ITEM"],
  "RequiresFeatures": ["stations"],
  "MaxLevel": null
}

• Display - Name and Description are last-resort fallbacks only. The translated name comes from the pack's own skill.<id> language key (and the description from skill.<id>.desc, or an explicit DescriptionKey), so a pack skill can be properly translated per language by shipping its own additive language file. Icon is a texture path.
• Placement - which tab the skill sits in (Gathering, Combat, Crafting, Misc) and which skill it slots in after within that tab.
• Triggers - the events that award XP, using the same names as the config file below. A skill with no triggers is still a real, listed skill; it just earns its XP from a companion mod or a command instead.
• RequiresFeatures - features that must be present for the skill to be available. When one is missing the skill is defined but hidden and earns nothing.
• MaxLevel - an optional per-skill cap; an owner cap in custom-skills.json still wins over it.

Precedence is the usual defaults, then pack, then owner: a pack skill joins the roster, and your own custom-skills.json entry with the same id still overrides it, so you can retune or rename anything a pack installs. /mmoconfig reload keeps pack skills in place, and /mmoconfig validate reports a pack skill that shadows a built-in id, names an unknown category or trigger, or has neither a name nor a language key.

Disabling Built-in Skills

Any of the 20 built-in skills can be disabled from the Custom Skills admin page. Disabled skills:

• Are hidden from all player-facing UI pages
• Stop awarding XP from any source
• Are excluded from leaderboards and total level calculations
• Are hidden from admin editors (XP Maps, Skill Tree, etc.)
• Player XP data is preserved - re-enabling a skill restores all progress

Per-Skill Max Levels

Control how far players can level each skill. The default max level is 200 for all skills. Override it per-skill to create different progression caps.

• Once a skill reaches its max level, no further XP is awarded
• Applies to both built-in and custom skills
• Configurable via the admin UI or custom-skills.json
• Need to cap individual players or groups below the configured max? See Level Cap Permissions - permission nodes can lower the cap per player and per skill.

Config File Reference

Custom skill definitions are stored in mods/mmoskilltree/custom-skills.json using the override-based config system.

{
  "schemaVersion": 1,
  "skills": [
    {
      "id": "HERBALISM",
      "displayName": "Herbalism",
      "category": "GATHERING",
      "description": "Gather and collect herbs",
      "descriptionKey": "skill.herbalism.desc",
      "iconPath": "Ingredient_Herb_Rare",
      "triggerTypes": ["BREAK_BLOCK"],
      "requiresFeatures": []
    },
    {
      "id": "BEAST_HUNTING",
      "displayName": "Beast Hunting",
      "category": "COMBAT",
      "description": "Track and hunt dangerous creatures",
      "triggerTypes": ["KILL_ENTITY", "DEAL_DAMAGE_PHYSICAL"]
    }
  ],
  "disabledBuiltinSkills": ["TAMING"],
  "defaultMaxLevel": 200,
  "maxLevels": {
    "HERBALISM": 150,
    "MINING": 300
  },
  "builtinRequiresFeatures": {
    "TAMING": ["taming"]
  }
}

Config Fields

Trigger Type Names for Config

When editing the JSON directly, use these trigger type names:

BREAK_BLOCK, PLACE_BLOCK, DEAL_DAMAGE_PHYSICAL,
TAKE_DAMAGE, FALL_DAMAGE, CRAFT_ITEM,
KILL_ENTITY, TAME_ENTITY, CATCH_FISH,
MOVEMENT_SPRINT, MOVEMENT_SWIM,
MOVEMENT_SAFE_LANDING, MOVEMENT_DANGEROUS_FALL_SURVIVED

Example: Adding a Custom Skill

1. Open /mmoadmin → Custom Skills
2. Enter an ID (e.g., HERBALISM) and display name
3. Select a category (Gathering) and trigger types (Break Block)
4. Click Save
5. Go to Edit XP Maps and select your new skill
6. Add XP patterns for the blocks that should award XP
7. Optionally add skill tree tiers via Edit Skill Tree
8. Optionally add item rewards via Edit Rewards

Changes are saved immediately to config files and take effect without a server restart.