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 213 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.

The daily and weekly quest ladders score points like the other achievements: the daily one (Daily Chores to Daily Legend) counts daily quests such as The Temple's Due and contracts from the Daily board, and the weekly one (First Week to Old Regular) weekly quests and contracts from the Weekly board. Gathering has an Excavation ladder for soil dug, from Excavator at 500 blocks through Ditch Digger and Master Excavator to Legendary Excavator at 100,000; Gathering Master asks for Master Excavator and Legendary Gatherer for Legendary Excavator. Daggers, Polearms, Staves, Axes, Blunt, Unarmed, Archery, Artillery and Magic each have a three-rung ladder for XP earned in that skill, up to a million, counting only XP earned from 1.7.0 on.

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 and its points arrive on the same swing that finished it, along with anything it hands over at once, such as a title; the rest, such as its XP, waits on its page until you collect 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.

Boss ladders

Combat's Bosses group has a ladder for each of Update 7's big fights, at 1, 10 and 50 wins. Feastmaster Down, Feastmaster Hunter and Feastmaster Slayer count your wins against the Feastmaster, the boss deep in the goblin Deepworks: its fight shows a boss bar, so a win counts for everyone who took part. Grizzly Down, Grizzly Hunter and Grizzly Slayer count the Voidtaken Grizzlies you bring down, and with Kweebec Nightmare installed, Warden Down, Warden Hunter and Warden Slayer count the Blight Warden the same way. Each rung pays Defense XP to collect, and the top rung of each gives a title: The Feastbreaker, The Voidhunter or The Wardenbreaker. Feastmaster Down also opens the Bounty Pack's weekly Feastmaster contract (see Bounty Board).

The Gobliterator, the goblins' war machine at the bottom of the Deepworks, has two achievements of its own. Gobliterator Down is for a win with Hard Mode off, and Gobliterator Down: Hard for a win after you switch on Hard Mode at the button in its arena. They pay 1,000 and 5,000 Defense XP to collect, for everyone who took a real part in the fight, and a hard win counts only for the hard one.

The Achievements tab

Achievements live on the Achievements tab of the Objective Book, in the same menu as your skills and quests. /mmoachievements opens it there. The header shows how many you have earned, your points and the next points milestone, and the tab has three views:

• Overview - any rewards waiting to be collected, the next milestone with a marker for each rung along its bar, a tile for each category with its progress, and three short lists: what you pinned, what you earned lately and what you nearly have. A category you are still working through wears a ring showing how far along you are, and its tile marks what you earned there since you last opened it. A category whose calendar event is running says On now on its tile.
• Browse - pick a tile, or a category from the dropdown, and its achievements are grouped by subcategory. Filter by In progress, Earned, Waiting or Feats, sort by default, A to Z or closest first, or search. A ladder shows only the rung you are climbing unless you search, and a long section shows 40 rows, then a button for more.
• Statistics - your lifetime numbers, in sections the installed mods add (see Statistics). The view is hidden when nothing fills it.

Pick an achievement and its page opens beside the list: where it is filed, its points, what it asks and how far along you are, any tiers of its ladder, its rewards and whether each is collected, and a few more from the same group. You collect its rewards and pin it from there.

• Pinning - up to 5 achievements can be pinned, from an achievement's own page. Pin shows only on one you are still working toward, or one already pinned so you can take it off. Pinned achievements have their own list on the Overview
• Seasonal achievements sit under the Seasons category, one group per event named in your language, and while its season runs, an achievement's row and page say how many days are left

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.

The races the jar ships are all feats of strength: each skill's First Master (First Mining Master and the rest, for the first to reach level 100 in that skill), All-Rounder, Expert in Everything and Master of All (the first to reach level 50, 75 and 100 in every skill) and First Contract (the first to complete a bounty). Once won, each sits on the Feats shelf with no points, and the points total never counts it. Each pays a title the moment it is won: First Master for every skill's race, then All-Rounder, Expert in Everything, Master of All and First on the Board. Its XP and any boost token wait on its page to be collected.

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 Collect 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.

Titles

Some achievements pay a title, such as the server-first races above or Combat Master's The Blooded. A title you earn shows beside your name in menus and on Records once you choose it: pick the Titles tile at the Adventurer's Guide, or the tile under Title on the menu's Settings tab. The picker counts how many you have earned of the ones you can see ("2 of 5"), lists the titles still to earn with the achievement or quest that gives each, and tells you when one is waiting for you to collect an achievement's or a quest's rewards. Press a line to open that achievement or quest in your book. While you show no title, the next one you earn shows itself, unless you took yours off with Show none. Some titles stay secret until you earn them.

If you won a feat or earned an achievement before it came with a title, such as being the first to take a skill to level 100 before titles came in, the title is yours the next time you log in. A title that comes with collecting the achievement's rewards waits until you collect them. Everything else about titles, from secret titles and titles in chat to offline grants and the two title factors, is on ZiggfreedCommon: Titles.

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. The first, at 500 points, pays 1500 Defense XP; the four from 3000 to 24000 each pay an XP boost token and a Skill Lamp with 3 picks, up to a 3x All Skills boost and a lamp worth 300,000 XP in each of three skills at 24000. A milestone's XP and its lamp wait on the achievements page until you collect them; a boost token arrives the moment you cross the total.

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 book 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 name, its tile's picture and the order its subcategories read in. Since 1.7.0 it can also give the category a colour (Accent, the strip on its tile) and tie it to a calendar event (Event, or SubcategoryEvents when each group is an event of its own), so its tile says On now while the event runs. Declare one and your own achievements have a home in the book. Every field is on Authoring Achievements: a category.

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, every player has lifetime statistics. Since 1.7.1 they are kept in the shared library's one stat record, the same numbers Records ranks: the library counts what every server has (kills, blocks broken and placed, crafting, pickups, conversations, boss fights, deaths and playtime), and MMO Skill Tree adds its own (damage, XP, distances and the rest). Everything the old Statistics counted moved across the first time each player logged in, and Blocks Placed, which never went up before, counts now. The counters update on the world thread as the same moments quests and achievements react to reach the server (a block broken, a mob killed, an item crafted or picked up, a block placed). 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.

Players read them in the Statistics view of the Achievements tab, beside Overview and Browse. This mod adds sections for combat, gathering, movement, leveling, stations and playtime; a section shows once one of its numbers is above zero, and the stations section only with RPG Stations installed and a Disenchanting Table on the server. A row shows its total and its top entry ("Most: Trork x120"), and opens its full breakdown in place, up to 100 lines ranked by count, so Back keeps your place. The Almanac adds a Seasons section of its own while it lists a season: a row per season with how many times you took part, opening your tallies for it and a button to its Almanac page.

File Layout

The built-in achievements are readable files, shipped in the jar at Server/ZiggfreedCommon/Achievements/MMOSkillTree/<Area>/<Name>.json - 213 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.