Achievements

Overview

Achievements reward players for long-running play patterns - first kill of a monster type, a thousand mined blocks, reaching level 100, or claiming a server-first bragging right. The system tracks progress automatically from combat, gathering, crafting, questing, bounties, NPC dialogue, and level events, awards points on completion, and can trigger skill XP, boosts, currency, or console commands as rewards.

Players open the Achievements page with /mmoachievements (aliases: /mmoach, /achievements). The jar ships its achievements as 167 readable files across combat, gathering, crafting, leveling, quests, and misc categories (each split into subcategories), plus 5 point milestones. 6 of those files are per-skill ladders that stamp themselves out once per skill your server actually runs, so the earned total on a default install is well above the file count, and a server with extra skills gets their ladders for free.

Achievements can also ship in a content pack, and can be feature-gated so they only appear when a system like mastery is enabled.

Achievements land the moment you earn them. Progress is worked out inline as the event happens, so the unlock, its points and its rewards arrive on the same swing that finished it. There is no background pass to wait on and nothing to flush, which also means a crash or a restart can never lose the last few seconds of progress.

An achievement's requirements are honored. An achievement carries the same requirement block quests and shop offers do, and it is answered the same way, so a pack that gates its taming or mastery achievements behind those features has them stay hidden - not merely unearnable - on a server where the feature is off, with no content edits.

The Achievements UI

The page uses the standard three-column menu layout. The left nav mirrors the other menu pages; the middle panel shows the achievement list filtered by category and subcategory; the side panel shows your current points, milestone progress, and a summary of your lifetime statistics.

• Categories & subcategories tab along the top of the list
• Search and sort controls to narrow down the list
• Pinning - up to 5 achievements can be pinned. Pinned achievements appear in the side panel for quick progress checking
• Progress bars for single- and multi-criteria achievements; multi-criteria show one bar per criterion

Achievement Types

One achievement, as a file

A built-in achievement is one file, and this is the shape it is written in. The file name is the id, the folders under it are plain organization, and a file naming another as its Parent starts from that one and changes only what it mentions.

// Server/ZiggfreedCommon/Achievements/MMOSkillTree/Combat/Melee/Trork_Hunter.json
{
  "Name": "Trork_Hunter",
  "Text":    { "FlavorKey": "achievement.kills_trork.desc",
               "TextArgs": { "Flavor": ["@amount"] } },
  "Listing": { "Category": "combat", "Subcategory": "melee", "SortOrder": 6,
               "Chains": [ { "Id": "kills_trork", "Tier": 2 } ] },
  "Scoring": { "Points": 35 },
  "Criteria": {
    "kill-entity-trork": { "Kind": "KILL_ENTITY", "Target": "Trork",
                           "MatchMode": "CONTAINS", "Amount": 250 }
  },
  "Rewards": {
    "Claim": [
      { "Kind": "Mmo_Xp", "Params": { "Skill": "DEFENSE", "Amount": "2500" } }
    ]
  }
}

Each criterion is filed under its own key, and that key is what a player's progress is stored under. Adding, removing or reordering criteria therefore leaves every other tally exactly where it was, and re-authoring the file can never re-point somebody's progress onto a different step. A file naming a Parent merges Criteria per key, so a child can retune one step by naming its key and inherit the rest untouched. Pick keys that read as what the step is (kill-entity-trork) and treat a key, once players have progress under it, as permanent.

Single-criterion

One criterion is enough for most achievements: a trigger, a target, and how many.

// Server/ZiggfreedCommon/Achievements/MyPack/Combat/Trork_Slayer.json
{
  "Text":    { "TitleKey": "achievement.trork_slayer.title",
               "FlavorKey": "achievement.trork_slayer.desc" },
  "Listing": { "Category": "combat", "Subcategory": "melee" },
  "Scoring": { "Points": 10 },
  "Criteria": {
    "kill-trork": { "Kind": "KILL_ENTITY", "Target": "Trork",
                    "MatchMode": "CONTAINS", "Amount": 50 }
  },
  "Rewards": {
    "Claim": [
      { "Kind": "Mmo_Xp", "Params": { "Skill": "DEFENSE", "Amount": "500" } }
    ]
  }
}

Multi-criteria

Key several criteria under Criteria and every one has to finish before the achievement unlocks. Progress reads as one bar per criterion on the page.

{
  "Text":    { "TitleKey": "achievement.well_rounded_hunter.title" },
  "Listing": { "Category": "combat", "Subcategory": "melee" },
  "Scoring": { "Points": 25 },
  "Criteria": {
    "skeletons": { "Kind": "KILL_ENTITY", "Target": "Skeleton", "Amount": 50 },
    "trorks":    { "Kind": "KILL_ENTITY", "Target": "Trork",    "Amount": 50 },
    "wraiths":   { "Kind": "KILL_ENTITY", "Target": "Wraith",   "Amount": 50 }
  }
}

Because every tally is filed under its criterion's key, a fourth quarry can be added, or one of these three dropped, without disturbing the progress players already have on the others.

Meta

A meta-achievement unlocks the moment every child on its list is unlocked. Use it to gate a mastery-style capstone behind a group of smaller achievements.

{
  "Text":         { "TitleKey": "achievement.combat_master.title",
                    "FlavorKey": "achievement.combat_master.desc" },
  "Listing":      { "Category": "combat" },
  "Scoring":      { "Points": 150 },
  "MetaChildren": ["first_blood", "trork_slayer", "skeleton_hunter", "wraith_bane", "goblin_cleaver"],
  "Rewards": {
    "Claim": [
      { "Kind": "Mmo_Boost_Token", "Params": { "Skill": "SWORDS", "Multiplier": "2.5", "DurationMinutes": "30" } }
    ]
  }
}

Meta completions cascade - unlocking the last child triggers the meta unlock automatically.

The older flat shape

Every owner file and every pack authored before this format keeps working untouched: a flat file with id / displayName / triggerType / requiredAmount / rewards at the top level is still read in full, so nothing already written has to change.

{
  "id": "trork_slayer",
  "displayName": "Trork Slayer",
  "description": "Defeat 50 Trorks",
  "triggerType": "KILL_ENTITY",
  "target": "Trork",
  "matchMode": "CONTAINS",
  "requiredAmount": 50,
  "category": "combat",
  "subcategory": "melee",
  "points": 10,
  "rewards": [
    { "type": "XP", "skill": "DEFENSE", "amount": 500 }
  ]
}

Server-First

Mark an achievement server-first (Meta.mmoskilltree.ServerFirst, or "serverFirst": true on the older shape) to lock it to the first player on the server who clears it. The claim is recorded in mods/mmoskilltree/achievements/server-first-claims.json and all other players see the achievement as locked once someone has claimed it.

A player who finishes one after somebody else gets a quiet grey note rather than a fanfare, and their criteria stay met, so if the winner's claim is ever released the achievement is theirs on the next check with nothing to redo. That note is an authored file you can reword, recolour, silence or announce - see feedback moments.

Feat of Strength

Mark an achievement a feat (Meta.mmoskilltree.Feat) to give it a feat's listing treatment: its own earned-only shelf on the page, no pinning, and nothing shown until somebody earns it. Useful for retired event rewards or admin-granted commemorative unlocks.

Whether it counts toward the points total is a separate, explicit switch: "Scoring": { "CountsTowardTotal": false }, written beside the feat flag. Every feat shipped in the jar authors it, and so should a feat nobody can earn any more; leave it off and the feat scores like any other achievement, which is the right answer for one that is merely rare. On the older flat shape, "featOfStrength": truestill forces the exclusion by itself.

Trigger Types

Any objective trigger can drive an achievement, the same roster quests and bounties draw from.

The matchMode field controls how target is matched: EXACT, CONTAINS, or PREFIX. Leave it out and CONTAINS is used; write it anyway, so the file says what it means.

DEAL_DAMAGE counts damage, not hits. Each hit contributes the damage that actually landed, after the target's defenses, so a criterion authored "Amount": 50000 asks for fifty thousand damage rather than fifty thousand swings. Size these the way you would size a health bar, not a kill count.

Rewards

Achievements pay out through the same open reward vocabulary as quests, shop offers and bounty contracts. A reward names a kind and gives that kind its parameters, and the list of kinds is open: anything the mod, the shared library or a companion mod registers can be authored, and a kind nothing on this server provides is reported by /mmoconfig validate rather than silently dropped, because the mod that pays it out may simply not be installed yet.

The historical spellings (XP, BOOST_TOKEN, CURRENCY, COMMAND, ABILITY_MOD, and the flat { "type": ..., ... } form) are translated on the way in, so nothing already written has to be touched. Prefer Item over a Command running a give line: it is checked against the bag before the claim is allowed, and it waits for the player's next connect instead of being lost when there is no room.

Rewards sit in one Rewards group with two buckets, the same group quests and point milestones use. Auto rewards land the instant the achievement is earned, wherever the player is. Claim rewards wait on the achievement's detail page behind the Claim button, which is where anything needing bag room belongs: one room check runs before the claim charges, and a claim with no room stays waiting instead of being lost. Claim is the default: put a reward there unless you specifically want it to arrive unannounced in the field. Each bucket is one leaf, so a file naming a Parent that re-authors Claim replaces the inherited claim list whole and keeps the inherited Auto untouched.

An achievement may also carry its own server-wide announcement (an Announce block naming a title key and a body key), because its words are per-achievement rather than one template; how that banner is drawn, and the unlock toast and jingle every achievement shares, are one authored file you can reword, recolour or silence - see feedback moments.

Points, Milestones & Categories

Every achievement is worth its points value unless its Scoring block says CountsTowardTotal: false, and crossing a cumulative total pays a milestone. Five milestones ship, handing out a Defense XP token at 500 and escalating to a 3x All Skills boost at 24000.

A milestone is a file at Server/ZiggfreedCommon/AchievementMilestones/<Namespace>/<Name>.json, and its threshold is its identity, not its file name - so a file re-authoring 3000 replaces the shipped 3000 rung outright rather than adding a second one beside it. A milestone pays through the same two-bucket Rewards group an achievement does: Auto lands the instant the total is crossed, Claim waits on the achievements page.

// Server/ZiggfreedCommon/AchievementMilestones/MyPack/Points_3000.json
{
  "Threshold": 3000,
  "TitleKey": "achievement.milestone.3000.title",
  "Rewards": {
    "Auto":  [ { "Kind": "Mmo_Xp", "Params": { "Skill": "ALL", "Amount": "1500" } } ],
    "Claim": [ { "Kind": "Item", "Params": { "Item": "Ingredient_Bar_Iron", "Count": "5" } } ]
  }
}

The categories the page groups by are content too, at Server/ZiggfreedCommon/AchievementCategories/<Namespace>/<Category>.json. The file name is the category word content writes, lower-cased, and the file decides its sort order, its heading key, its fallback icon and the order its subcategories read in. Declare one and your own achievements have a home on the page.

A server owner still has the last word on the points ladder through mods/mmoskilltree/achievements/point-milestones.json, which stays exactly as it was:

{
  "schemaVersion": 1,
  "milestones": [
    { "threshold": 500,   "displayName": "Bronze Achiever",   "rewards": [ ... ] },
    { "threshold": 3000,  "displayName": "Silver Achiever",   "rewards": [ ... ] },
    { "threshold": 7500,  "displayName": "Gold Achiever",     "rewards": [ ... ] },
    { "threshold": 14000, "displayName": "Platinum Achiever", "rewards": [ ... ] },
    { "threshold": 24000, "displayName": "Diamond Achiever",  "rewards": [ ... ] }
  ]
}

Statistics

Alongside achievements, the plugin maintains per-player lifetime statistics. The counters update on the world thread as the same moments quests and achievements react to reach the mod (a block broken, a mob killed, an item crafted or picked up, a block placed), and show on the Achievements side panel with top-3 breakdowns per category. Because XP, statistics and progress all hang off those same moments, what quests do not see, statistics do not count either: a self-placed block broken again produces no moment, so it counts nothing anywhere, and a kill made by a player's turret or summoned ally is credited to that player.

File Layout

The built-in achievements are readable files, shipped in the jar at Server/ZiggfreedCommon/Achievements/MMOSkillTree/<Area>/<Name>.json - 167 of them, with the 6 per-skill ladders stamped out once per skill your server runs. Open any of them to see exactly how a shipped achievement is written, and copy one as the starting point for your own.

For a quick single-achievement tweak with no pack, drop a file with the same id into mods/mmoskilltree/achievements/. Yours wins for that id and nothing else moves: creating an owner file does not hide the built-in set, so extending the shipped achievements and replacing one of them are the same simple move.

Admin Commands

The MMO's own achievement admin subcommands run under /mmoconfig achievement. The | delimiter separates fields inside --args.

The admin dashboard also has an Achievements panel that wraps these operations in a UI.

The shared library's achievement verbs

Achievements run on the shared library's one achievement engine, and the same verbs are reachable as /zigprogress achievement list|status|give|claim|reset - give hands one over outright, claim is the peer of quest claim and takes --achievement=<id|all>, and reset takes the same argument and clears the record, meta cascade included. The MMO's /mmoachadmin reset --player=<name> is an alias over /zigprogress achievement reset that additionally releases the server-first claims that player won, which only this mod can do; the shared spelling wipes the record but leaves the claim recorded. See ZiggfreedCommon commands for the full verb list and permission nodes.