Systems
Titles
Unlockable player titles. A player equips one unlocked title in their profile; it is shown in the profile, in the chat/leaderboard views and above the player's head in the nametag. Definitions live in config/titles/*.json of any mod or quest pack (for example albase/config/titles/duat.json, playtime.json, alzenith/config/titles/moon.json); files from several packs are merged and the last loaded definition of an ID wins.
File Format
A flat dictionary: the key is the title ID, the value is the definition. If id is omitted the key is used.
{
"albase:title-duat-conqueror": {
"titleKey": "albase:title-duat-conqueror",
"category": "trials",
"icon": "✦",
"sortOrder": 110,
"unlockSource": "seal",
"colorHex": "#e6b800"
}
}| Field | Default | Description |
|---|---|---|
id | the dictionary key | Title ID |
titleKey | — | Localization key of the displayed title text. If missing or unresolved, the raw ID is shown |
descriptionKey | — | Localization key of the "how to earn it" text shown in the profile |
category | general | Grouping in the title list. playtime has special behaviour (see below); trials and other values are just labels |
icon | — | Glyph drawn in the title list |
sortOrder | 100 | Ordering inside the category |
unlockSource | — | Describes what grants the title (see below) |
colorHex | — | Color of the title chip, the profile avatar ring and the nametag (for example #B45309) |
Unlock sources
Two unlockSource forms are evaluated by the framework itself:
| Form | Effect |
|---|---|
playtime:<hours> | Unlocked once the player has that many hours of playtime. Only applies to titles whose category is playtime |
achievement:<id> | Unlocked at the moment the player unlocks that achievement (not when the reward is claimed) |
Every other value (for example seal) is informational: it is a label for the profile and does not grant the title automatically. Such titles are granted explicitly:
- the
titleRewardfield of an achievement (granted when the player claims the achievement's reward), of an achievement tier (granted immediately when the tier is reached), or of an achievement collection/seal (granted when the collection is completed); - a reward entry
{ "type": "Title", ... }in an achievement is not the way to do this; usetitleReward(theTitlereward type only writes a raw marker and does not unlock a registered title); - the
/avq title unlockcommand; - another mod through the title API.
Unlocking a title that is not registered is silently ignored.
Playtime titles
Titles of category: "playtime" with unlockSource: "playtime:N" form a rank ladder (see albase/config/titles/playtime.json: 0, 25, 80, 200, 500, 1000, 1500, 2000, 2500 hours). On join and then once a minute while online, the player gets every rank they qualify for and the highest one is equipped automatically. Auto-equipping is skipped when the player currently has a title from another category equipped, so custom choices are never overwritten. A player with a playtime title equipped is moved up the ladder as hours accumulate.
Commands
All need the give privilege.
| Command | Description |
|---|---|
/avq title list | List all registered titles |
/avq title unlock <id> [playerName] | Unlock a title |
/avq title equip <id> [playerName] | Equip a title (unlocks it first if needed) |
/avq title refresh [playerName] | Re-run the playtime auto-unlock/equip |
Nametag display
The overhead title is drawn by a client system that watches nearby players and refreshes the vanilla nametag texture (twice a second). It can be tuned or disabled in the client core config (alegacyvsquest/alegacy-vsquest-config.json, section Client.PlayerTitleTag):
| Key | Default | Description |
|---|---|---|
Enabled | true | Turn the overhead title off completely |
RenderRange | 80 | Distance in blocks within which titles are drawn |
ShowOwnTag | true | Show the title over your own character |
Persistence and sync
- Unlocked and equipped titles are stored on the player and survive death and relogs. Unlocking adds an entry to the profile event feed (except for titles whose
unlockSourcestarts withachievement:, which are assumed to already appear through the achievement). - Unlocks and equips are synced to the database (
/vsquest/profile/{uid}/titles/{title_id}and.../equip) — see Database Sync. - Titles are included in the account data transfer.
Title API (C#)
ITitleApi, exposed by the title system, lets other mods work with titles: GetEquippedTitleId (by player or UID), GetTitleText, GetEquippedTitleText, GetTitleColor, EquipTitle (does nothing if the title is not unlocked; an empty ID unequips), UnlockTitle (idempotent, ignores unregistered IDs), IsUnlocked, GetAllTitles, GetUnlockedTitleIds. The system also raises a server event when a player changes their equipped title. See C# API.