Systems
Achievements
Achievement system with trigger events, thresholds, streaks, tiers, multi-condition and "requires" meta-achievements, community goals, seasonal windows, rewards, collections (seals) and a points leaderboard. Definitions live in config/achievements/*.json of any mod or quest pack (for example albase/config/achievements/hollowtrials.json, alzenith/.../moon.json); players see them in the profile / journal Achievements view. Titles are covered separately in Titles.
File Format
A file holds file-level defaults, a list of achievements and (optionally) a list of collections:
{
"broadcastUnlock": true,
"unlockSound": "alegacyvsquest:sounds/achievement",
"achievements": [
{
"id": "albase:ach-trial-challenge-speedkill",
"title": "albase:ach-trial-challenge-speedkill",
"description": "albase:ach-trial-challenge-speedkill-desc",
"icon": "⚡",
"category": "hollowtrials",
"sortOrder": 450,
"rarity": 3,
"triggerEvent": "trialkill",
"triggerCode": "*",
"triggerExtra": "3",
"requireTags": ["speedkill"],
"collectionId": "albase:seal-hollow",
"rewards": [
{ "type": "RuneCurrency", "value": "void-echo", "quantity": 30 }
]
}
],
"collections": []
}| File-level field | Default | Description |
|---|---|---|
broadcastUnlock | true | Copied onto every achievement of the file. If false, unlocks from this file are never announced in chat |
unlockSound | — | Sound for every achievement of the file that has none of its own. Falls back to the global sound (alegacyvsquest:sounds/achievement, configurable in the client core config Client.AchievementSound: Enabled, Volume 0.8) |
achievements | — | Achievement definitions. Entries without id are ignored; a later definition with the same ID replaces the earlier one |
collections | — | Collections / seals, see below |
Core fields
| Field | Default | Description |
|---|---|---|
id | — | Unique ID (pack:ach-...) |
title / description | — | Localization keys |
icon | — | Glyph, or an item/asset icon such as game:candle-wax |
category | general | Grouping tab (general, hollowtrials, ossuary, duat, zenith, tutorial, ...) |
sortOrder | 100 | Ordering inside the category |
secret | false | Hidden until unlocked; also suppresses the chat announcement (except Mythic and Archaic) |
rarity | Common | Enum name or index: Common(0), Uncommon(1), Rare(2), Epic(3), Legendary(4), Mythic(5), Archaic(6). Decides the points and the colour |
customPoints | — | Points override. Without it points depend on rarity: 5, 10, 25, 50, 100, 200, 400 |
hideProgress | false | Hide the N/M progress bar (progress is still tracked) |
showRequiresProgress | false | For requires achievements: show "x/y" of the required achievements |
discoverable | false | The achievement appears in the NearPlayer block's dropdown (discoverableAchievements), so a "walk into this radius" secret can be authored with no code |
collectionId | — | Informational back-reference to the collection. Membership is decided by the collection's own achievements list |
unlockSound | file value | Sound for this achievement only |
Trigger
| Field | Description |
|---|---|
triggerEvent | Event type (see list below). Matched case-insensitively. An achievement without a triggerEvent (and without conditions) only unlocks through requires, collections or commands/actions |
triggerCode | What the event must match. * matches anything. Comma-separated alternatives. A value matches the event code exactly, or its part after the domain (wolf matches game:wolf-male: exact wolf or wolf-...), or the last : segment (so duat-khetar-judge matches the boss key albase:duat:duat-khetar-judge-boss) |
triggerExtra | Extra string the event must carry (difficulty, tier, quality). A trailing * makes it a prefix match |
threshold | How many times the event must fire (counted by the event quantity). 0 / omitted = unlock on the first match |
Progress is stored per achievement and shown as N/M. Special cases:
playtime,leaderrankandreputationuse the absolute value carried by the event (hours, rank flag, reputation) instead of counting events.- A generic
deathcounter (notriggerCode) mirrors the profile's death count. - A
bosskillthreshold over boss target IDs (codes containing:) reads the profile's kill counter, so it also covers kills made before the achievement was added.
Trigger events
| Event | Fired by / code |
|---|---|
kill | Any entity kill by the player. Code = entity code |
pvpkill, pvpdeath | Player killed / was killed by a player. Code = other player's UID |
death | The player died |
quest | A quest was completed. Code = quest ID |
collect, craft, harvest, trade, explore, tame | Quest objectives / actions. Code = item, entity or area code; collect may carry an Extra |
blockbreak, blockplace | Code = block code |
travel, playtime | Distance walked (periodic) / playtime hours |
login | Player joined; quantity = login streak |
eat, drink, sleep, mount, interact, reroll, repair, transmog, duel | Gameplay / NPC interactions; code identifies the thing used |
bosskill | Boss defeat for each credited player. Code = boss key, Extra = achievement extra of the boss |
bosskillgroup | Group boss kill |
bossaura | Players that stood near a boss kill without damaging it |
trialkill | Encounter boss kill (default achievementEventType of an encounter definition). Code = boss key, Extra = variant/tier (3...) |
encounter | Encounter completed. Code = encounter ID, Extra = difficulty ID; tags deathless (no deaths), group size and fight duration are attached |
rune, runelevel | Rune lifecycle. Code = rune ID, Extra = attunement:type |
bounty, bountypost, bountyfulfilled | Bounty contract completed (Code = server/player, Extra = kind) / posted / the author's contract was fulfilled |
leaderrank | The player holds rank #1 of a leaderboard category (Code = category) |
reputation | Reputation change; absolute value |
petunlock, petfeed, petpet, petfriendship | Cosmetic pet events (fired by the pet mod) |
Any value is accepted for triggerEvent, so custom events can be fired from quest actions with fireachievementevent <event> <code> [qty]; encounters can also override the event name with achievementEventType.
Tags and challenge filters
Boss and encounter events carry extra data that can be required:
| Field | Description |
|---|---|
requireSolo | Fail if more than one player took part |
requireMinGroupSize / requireMaxGroupSize | Group size bounds (0 = no bound) |
requireMaxFightMinutes | Fight must be finished within N real minutes |
requireTags | Every listed tag must be present on the event |
requireNoTags | None of the listed tags may be present |
Tags attached to boss kills: clone, first-on-server, no-deaths, explosion-hit, bite-hit, illusion-hit. Encounters attach the IDs of the completed challenges (for example speedkill, deathless, nofood, nopotions, lowmaxhp, lowgear, perfectdodge in the Hollow Trials) and deathless for encounter.
Gating, repeating, time windows
| Field | Description |
|---|---|
requires | List of achievement IDs. The achievement unlocks automatically when all of them are unlocked (meta-achievement, no trigger needed) |
prerequisite | One achievement ID that must be unlocked before this one can progress |
streakType / streakRequired | Streak achievement. login counts consecutive UTC calendar days with a login (shown as progress, e.g. 12/30); other types use their own recorded streak. Pair with triggerEvent: "login" |
availableFrom / availableUntil | Unix time in seconds; outside the window the achievement does not progress |
seasonalMonths | List of months 1..12 (UTC) in which the achievement can progress |
repeatable + cooldownSeconds | Can be earned again after the cooldown (default 86400); re-earning resets its state |
isCommunity | Server-wide goal: progress is summed over all players; when the global threshold is reached it unlocks for every online player |
Multi-condition achievements
conditions is a list of independent counters; all must reach their threshold. An achievement with conditions and no top-level triggerEvent reacts to the events of its conditions.
"conditions": [
{ "triggerEvent": "kill", "triggerCode": "wolf", "threshold": 10 },
{ "triggerEvent": "collect", "triggerCode": "game:flint", "threshold": 5 }
]| Condition field | Default | Description |
|---|---|---|
triggerEvent | — | Event type |
triggerCode | — | Code filter, same matching as above (without the last-segment rule) |
triggerExtra | — | Extra filter (trailing * = prefix) |
threshold | 1 | Required count |
Challenge filters (requireSolo, tags, ...) are not evaluated inside conditions.
Tiers
tiers makes a multi-level counter: tiers are ordered by threshold, the first reached tier unlocks the achievement, every further tier gives its own points (by the tier's rarity, or customPoints) and rewards.
{
"id": "albase:ach-death-tiers",
"triggerEvent": "death",
"rarity": 1,
"tiers": [
{ "threshold": 100, "rarity": 1, "label": "albase:ach-death-tiers-tier-0" },
{ "threshold": 250, "rarity": 2, "label": "albase:ach-death-tiers-tier-1" }
]
}| Tier field | Description |
|---|---|
threshold | Progress needed for this tier |
rarity | Rarity of the tier (points and colour) |
rewards | Rewards granted immediately when the tier is reached |
titleReward | Title unlocked immediately when the tier is reached |
label | Localization key shown in the unlock notice instead of title |
Rewards
Rewards of an ordinary achievement are not given automatically: the player presses "claim" in the profile (needs a free slot for every Item reward). Tier, collection and milestone rewards follow the rules in their sections.
"rewards": [
{ "type": "Item", "value": "mypack:tutorial-token", "quantity": 1 },
{ "type": "RuneCurrency", "value": "bone-crown", "quantity": 25 },
{ "type": "Experience", "value": "500" },
{ "type": "Command", "value": "/toolskin grant {player} eclipseplate-abyss" }
],
"titleReward": "albase:title-slayer"type | value | Notes |
|---|---|---|
Item | item or block code | Gives quantity stacks; action items arrive configured. Optional firstValue + firstKey: the first player in the world to earn it for that key receives firstValue (a one-off variant) instead; /avq ach first [key] lists / frees claims |
Command | console command | Run as server console; {player} and {uid} are replaced |
RuneCurrency | rune core ID, equipped (default) or all | Adds quantity rune currency. A core not yet obtained banks the amount for later |
Experience | number | Added to the player's quest XP |
Title | title ID | Only writes a marker; use titleReward to unlock a registered title |
| any | — | label is a localization key used for display |
titleReward on an achievement unlocks the title when the player claims the rewards. An achievement counts as having a reward if it has rewards or titleReward.
Collections and seals
A collection groups achievements. A completed collection awards bonus points, rewards and a title. Collections with isSeal: true are drawn as seals in the profile.
"collections": [
{
"id": "albase:seal-hollow",
"title": "albase:seal-hollow",
"description": "albase:seal-hollow-desc",
"icon": "✦",
"sealIcon": "flame",
"isSeal": true,
"sortOrder": 3,
"bonusPoints": 500,
"titleReward": "albase:title-hollow-conqueror",
"achievements": ["albase:ach-trial-t1-ashen-crawler"],
"milestones": [
{ "percent": 70, "label": "albase:seal-milestone-pet-riftmote",
"icon": "alegacy_patches:textures/gui/petportraits/riftmote-default.webp",
"description": "albase:seal-milestone-pet-riftmote-desc",
"rewards": [ { "type": "Command", "value": "/pet unlock {player} riftmote" } ] }
]
}
]| Field | Default | Description |
|---|---|---|
id, title, description, icon | — | Identity and display |
achievements | — | Member achievement IDs; the collection completes when all are unlocked |
requiredTiers | — | Map achievementId -> minimum tier index (0-based) the member must reach |
bonusPoints | 50 | Points awarded on completion |
rewards | — | Rewards granted at once on completion |
titleReward | — | Title unlocked on completion |
isSeal, sealIcon, sortOrder | false, —, 100 | Seal presentation (sealIcon is a symbol / icon name) |
milestones | — | Partial-completion rewards |
Milestone fields: percent (completion percentage), rewards, label, icon (asset path or item:/block: code), description (localization key). When a percentage is reached, non-item rewards (commands, currency) are granted at once and item rewards wait in the seal's reward chest until the player takes them (needs free slots). Milestones that were added later are caught up on join.
Unlock notification and announcement
On unlock the player gets a rarity-coloured notification and sound. A chat announcement for everybody (and Discord, if linked) is sent when the file's broadcastUnlock is on and either the rarity is Mythic/Archaic (always) or the achievement is not secret and the core config option BroadcastAchievementUnlock is true (default false; alegacyvsquest/alegacy-vsquest-config.json). The announcement belongs to the chat notification filter row of the achievement event.
Actions and commands
Quest / dialogue actions:
unlockachievement <achId>— unlock for the playerfireachievementevent <event> <code> [qty]— fire a custom trigger event
Admin commands (/avq ach; listing is give, everything that changes data is controlserver):
| Command | Privilege | Description |
|---|---|---|
/avq ach list | give | List registered achievements |
/avq ach unlock <id> [player] | controlserver | Unlock for a player |
| `/avq ach reset <id\ | *> [player]` | controlserver |
| `/avq ach backfill [player\ | all]` | controlserver |
| `/avq ach recalc [player\ | all]` | controlserver |
/avq ach first [key] | controlserver | List "first to earn" claims, or free one |
/avq ach testrewards [count] [player] | controlserver | Test: re-grant rewarded achievements as unclaimed |
/avq achievement [player] | give | Open the achievement view |
/avq seal list | give | List seals |
/avq seal complete <sealId> [player] | give | Unlock every achievement of a seal and complete it |
/avq seal completeall [player] | give | Complete every seal |
Persistence and sync
State lives on the player and is synced to the database (achievements, progress, seals, showcase) — see Database Sync; it is re-synced on join. Points are shown in the leaderboard; the player can pin a showcase of achievements to the profile. Achievement data takes part in the account data transfer.