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 fieldDefaultDescription
broadcastUnlocktrueCopied 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

FieldDefaultDescription
id—Unique ID (pack:ach-...)
title / description—Localization keys
icon—Glyph, or an item/asset icon such as game:candle-wax
categorygeneralGrouping tab (general, hollowtrials, ossuary, duat, zenith, tutorial, ...)
sortOrder100Ordering inside the category
secretfalseHidden until unlocked; also suppresses the chat announcement (except Mythic and Archaic)
rarityCommonEnum 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
hideProgressfalseHide the N/M progress bar (progress is still tracked)
showRequiresProgressfalseFor requires achievements: show "x/y" of the required achievements
discoverablefalseThe 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
unlockSoundfile valueSound for this achievement only

Trigger

FieldDescription
triggerEventEvent type (see list below). Matched case-insensitively. An achievement without a triggerEvent (and without conditions) only unlocks through requires, collections or commands/actions
triggerCodeWhat 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)
triggerExtraExtra string the event must carry (difficulty, tier, quality). A trailing * makes it a prefix match
thresholdHow 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, leaderrank and reputation use the absolute value carried by the event (hours, rank flag, reputation) instead of counting events.
  • A generic death counter (no triggerCode) mirrors the profile's death count.
  • A bosskill threshold 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

EventFired by / code
killAny entity kill by the player. Code = entity code
pvpkill, pvpdeathPlayer killed / was killed by a player. Code = other player's UID
deathThe player died
questA quest was completed. Code = quest ID
collect, craft, harvest, trade, explore, tameQuest objectives / actions. Code = item, entity or area code; collect may carry an Extra
blockbreak, blockplaceCode = block code
travel, playtimeDistance walked (periodic) / playtime hours
loginPlayer joined; quantity = login streak
eat, drink, sleep, mount, interact, reroll, repair, transmog, duelGameplay / NPC interactions; code identifies the thing used
bosskillBoss defeat for each credited player. Code = boss key, Extra = achievement extra of the boss
bosskillgroupGroup boss kill
bossauraPlayers that stood near a boss kill without damaging it
trialkillEncounter boss kill (default achievementEventType of an encounter definition). Code = boss key, Extra = variant/tier (3...)
encounterEncounter completed. Code = encounter ID, Extra = difficulty ID; tags deathless (no deaths), group size and fight duration are attached
rune, runelevelRune lifecycle. Code = rune ID, Extra = attunement:type
bounty, bountypost, bountyfulfilledBounty contract completed (Code = server/player, Extra = kind) / posted / the author's contract was fulfilled
leaderrankThe player holds rank #1 of a leaderboard category (Code = category)
reputationReputation change; absolute value
petunlock, petfeed, petpet, petfriendshipCosmetic 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:

FieldDescription
requireSoloFail if more than one player took part
requireMinGroupSize / requireMaxGroupSizeGroup size bounds (0 = no bound)
requireMaxFightMinutesFight must be finished within N real minutes
requireTagsEvery listed tag must be present on the event
requireNoTagsNone 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

FieldDescription
requiresList of achievement IDs. The achievement unlocks automatically when all of them are unlocked (meta-achievement, no trigger needed)
prerequisiteOne achievement ID that must be unlocked before this one can progress
streakType / streakRequiredStreak 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 / availableUntilUnix time in seconds; outside the window the achievement does not progress
seasonalMonthsList of months 1..12 (UTC) in which the achievement can progress
repeatable + cooldownSecondsCan be earned again after the cooldown (default 86400); re-earning resets its state
isCommunityServer-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 fieldDefaultDescription
triggerEvent—Event type
triggerCode—Code filter, same matching as above (without the last-segment rule)
triggerExtra—Extra filter (trailing * = prefix)
threshold1Required 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 fieldDescription
thresholdProgress needed for this tier
rarityRarity of the tier (points and colour)
rewardsRewards granted immediately when the tier is reached
titleRewardTitle unlocked immediately when the tier is reached
labelLocalization 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"
typevalueNotes
Itemitem or block codeGives 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
Commandconsole commandRun as server console; {player} and {uid} are replaced
RuneCurrencyrune core ID, equipped (default) or allAdds quantity rune currency. A core not yet obtained banks the amount for later
ExperiencenumberAdded to the player's quest XP
Titletitle IDOnly 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" } ] }
    ]
  }
]
FieldDefaultDescription
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
bonusPoints50Points awarded on completion
rewards—Rewards granted at once on completion
titleReward—Title unlocked on completion
isSeal, sealIcon, sortOrderfalse, —, 100Seal 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 player
  • fireachievementevent <event> <code> [qty] — fire a custom trigger event

Admin commands (/avq ach; listing is give, everything that changes data is controlserver):

CommandPrivilegeDescription
/avq ach listgiveList registered achievements
/avq ach unlock <id> [player]controlserverUnlock 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]controlserverList "first to earn" claims, or free one
/avq ach testrewards [count] [player]controlserverTest: re-grant rewarded achievements as unclaimed
/avq achievement [player]giveOpen the achievement view
/avq seal listgiveList seals
/avq seal complete <sealId> [player]giveUnlock every achievement of a seal and complete it
/avq seal completeall [player]giveComplete 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.

Press ESC to close