Concepts

Achievements and Rank

An Achievement is a milestone a Player reaches by using AgentsVille: a first NPC, a hundredth Message, a Party with a Lead. XP is what an Achievement is worth, and a Player's XP is the sum of the Achievements they hold. Rank is a Player's standing, set by their XP — Rank 1 to begin with, one more at each threshold. Both are about Players; an NPC's model slot is its Level, a different thing entirely.

Earned once, never lost

An Achievement is awarded the first time you meet it and kept from then on, even if what earned it is later deleted. Deleting the NPC behind "First NPC" does not take "First NPC" away.

Checked on request

Nothing is checked as it happens. POST /api/progress/check counts what you own — NPCs, Conversations, Messages you sent, Parties, Leads, finished Tasks, Tool calls, Skills, Memories, Groups, Sandboxes, Connectors — and awards every Achievement those counts meet. The web app calls it whenever the signed-in layout's loader runs, which happens after every chat turn and every mutation, so no route, tool or stream carries a hook of its own and progression cannot break a chat turn. See HTTP API.

The catalogue

Id	Title	Earns it	XP
`first-npc`	First NPC	Create an NPC.	50
`five-npcs`	Full House	Have five NPCs.	100
`first-message`	Hello There	Send your first Message.	25
`hundred-messages`	Chatterbox	Send 100 Messages.	150
`thousand-messages`	Town Crier	Send 1,000 Messages.	400
`ten-conversations`	Regular	Hold 10 Conversations.	75
`first-party`	Party Time	Start a Party.	100
`first-lead`	Crowned	Give a Party a Lead.	50
`ten-tasks`	Busy Board	Finish 10 Tasks.	150
`first-tool-call`	Handy	Have an NPC use a Tool.	75
`first-skill`	Teacher	Save a Skill.	100
`first-memory`	Remembered	Have an NPC keep a Memory.	50
`first-group`	Grouped	Make a Group.	75
`first-sandbox`	Workshop	Give an NPC a Sandbox.	100
`first-connector`	Connected	Connect a service.	100

Ids are stored against the Player, so an id is never reused for a different milestone: retiring an Achievement removes it from the catalogue rather than repurposing its id.

Rank

Rank n needs 50·n·(n−1) XP, so each Rank costs 100 more than the last:

Rank	XP required
1	0
2	100
3	300
4	600
5	1,000
6	1,500

Neither XP nor Rank is stored. Both are derived from the player_achievement rows every time they are read, so changing an Achievement's worth rescores every Player, and an Achievement removed from the catalogue simply stops counting toward anyone's total. See Database schema.

XP is never Usage

XP is not tokens, and tokens never become XP. Usage is recorded for visibility and never enforced; XP is earned by doing things in AgentsVille, not by spending. Reasoning hard on an expensive model earns nothing on its own — sending the Message that comes out of it might.

Shown in the pixel Skins, tracked in every Skin

Achievements and Rank are counted the same way regardless of Skin: Classic tracks them but stays a plain chat app and shows nothing for them. The pixel Skins surface the whole system — a Rank bar in the header that fills toward the next threshold, an Achievements place on the dashboard map listing every Achievement with its unlock state, and a toast the moment a check reports a newly unlocked Achievement, once per Achievement, never repeated for one you already hold, including one unlocked while you were in Classic.