Achievements & Titles

Status: Design Date: 2026-04-04

Track player milestones and award titles. Titles display after the player’s name in room descriptions, who list, and inspect. Achievements use the existing player-flags system — no new state types needed.

How It Works

Achievements are defined as a static list in the agent. Each achievement has a flag name, display title, and a condition. When an event fires (kill, death, level up, quest complete, room enter, boss kill), the system checks all achievements against the player’s current state. If the condition is met and the player doesn’t already have the flag, the flag is set and the player is notified.

No new types in sur/mud.hoon. Achievements are hardcoded in the agent as a list of conditions checked against existing player data.

Achievement Definitions

Combat

Progression

Exploration

Bosses

Quests

Misc

Title Display

Each player has an active title (the most recently earned achievement, or manually chosen). Titles appear after the player name:

Grendel the Veteran

In room descriptions:

Grendel the Veteran is here.

In who list:

Grendel the Veteran — Level 20 Warrior

In inspect/look player:

Grendel the Veteran — Level 20 Human Warrior PvP Kills: 7 Achievements: 12/25

Choosing a Title

title <name> — set your displayed title to any earned achievement title. title — show your current title and list all earned titles.

The active title is stored as a player flag: title:{flag-name}. Only one title flag at a time.

Check Points

Achievements are checked at these events:

Each check is a simple comparison against the character’s stats or flag set. No database queries — everything is on the session.

Notification

When an achievement is earned:

Achievement Unlocked: Centurion — Kill 100 mobs. Your title has been set to “Centurion”.

The title auto-sets to the newest achievement. The player can change it with title.

Implementation

Agent Code

A single arm ++ check-achievements that takes a character, player-flags set, and event type. Returns an updated flags set and a list of notification messages.

++  check-achievements
  |=  [c=character pflags=(set @tas) event=@tas]
  ^-  [(set @tas) (list @t)]

Called inline after kills, deaths, level-ups, quest completions, room enters.

No Type Changes

• Achievement flags stored in player-flags (already (map session-id (set @tas)))
• Active title stored as title:{flag} in player-flags
• No changes to character, player-session, or state-0

Import

Achievement definitions are hardcoded, not in area JSON. Boss kill achievements reference specific mob template IDs — the designer knows which mobs are bosses.

Frontend

• Achievement notification as a system message (already handled)
• Title shown in room occupants and who list (backend appends to name)
• title command response shows earned achievements list

Not Included

• Achievement points. No numeric score. Titles are the reward.
• Achievement UI panel. No dedicated frontend component. Use title command to see earned list.
• Per-world achievements. Achievements are world-specific (tied to player-flags which are per-session). Citizens keep them via flag persistence.
• Hidden achievements. All achievements are visible in the list. Could add a hidden flag later.