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"
  }
}
FieldDefaultDescription
idthe dictionary keyTitle 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
categorygeneralGrouping in the title list. playtime has special behaviour (see below); trials and other values are just labels
icon—Glyph drawn in the title list
sortOrder100Ordering 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:

FormEffect
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 titleReward field 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; use titleReward (the Title reward type only writes a raw marker and does not unlock a registered title);
  • the /avq title unlock command;
  • 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.

CommandDescription
/avq title listList 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):

KeyDefaultDescription
EnabledtrueTurn the overhead title off completely
RenderRange80Distance in blocks within which titles are drawn
ShowOwnTagtrueShow 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 unlockSource starts with achievement:, 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.

Press ESC to close