Title Configuration

Declare the worn prestige labels an Almanac milestone can pay out, and the text each one renders as.

A title is a short label a player equips and other players see beside their name. It is the plainest of the reward families an Almanac milestone can pay: no art, no stat, no behaviour — an entry is an id and the text it renders as.

Titles are cosmetic by construction. Nothing about a title may gate a stat, an item, or access to content; that is what lets one be granted by a milestone and kept in the player’s own hand-editable profile file rather than on the server.

File Location

title-config.yaml, at the root of a mod, declared in the mod manifest:

# <ModName>.yaml
title-config:

Both the client and the server load this file. The client needs it to draw a worn title; the server is the authority on which ids may be equipped, and refuses one that is not in the catalog.

Fields

Each entry under the top-level titles: key is one title.

Field	Type	Required	Description
`id`	string	yes	Stable identifier, namespaced to the declaring mod. A milestone’s reward names this, and a player’s profile records it, so renaming it drops the grant (see Ids and grants).
`display-name`	string	no	What the player reads. Omitted, the title renders as its title-cased id (`wanderer` → `Wanderer`). Translatable — see Localization.

Entry order is the order a wardrobe lists titles in, so it is worth authoring in the order they are earned.

Granting a title

Declaring a title says it exists, never that anyone has it. The grant comes from the milestone table:

# almanac-milestones-config.yaml
milestones:
  - id: first_steps
    name: TODO_NAME
    chapter: worlds
    metric: worlds
    threshold: 1
    reward:
      family: title
      id: wayfarer     # must match a `titles:` entry's id

See almanac-milestones-config.md for the milestone side. The two files are deliberately separate — a milestone can be re-tuned without touching the title it pays, and a title reworded without touching the milestone or any saved grant — but their ids have to agree: a granted id with no entry here renders as nothing.

A grant is recorded in the player’s per-user profile, so it carries across saves and seeds rather than dying with the world it was earned in.

Wearing one

A granted title is not worn until the player picks it, from the Titles chapter of the Almanac. The chapter lists the whole catalog in the order this file declares it; a title the player has no grant for shows as ???, and clicking the worn one again takes it off.

The worn title is recorded in the same per-user profile as the grants, so it follows the player to another machine and to another world. It is drawn in two places: above the wearer’s head, and on the player list’s row for them.

Two things follow from the id being what travels between clients, never the text:

Every viewer resolves it themselves. Two players in one session reading different locales each see the title in their own, out of their own copy of this file.
The server refuses an id it has no entry for, which is why it loads this file at all. A player carrying a title from a modded instance into one without that mod keeps the grant, and simply appears to wear nothing there.

Wearing a title the player never earned is not refused — the profile is hand-editable by design, and a title carries no power, so the check that matters is the one above.

Ids and grants

A profile records the ids a player has been granted, not their definitions. Two consequences:

An id that no loaded mod declares is kept, not dropped. The profile only ever grows, and the mod that declared it may come back; the title simply does not render while its mod is absent.
Renaming an id drops the grant for every player who earned it, by the rule above. Reword the display-name instead — that is what it is for.

A mod may only declare ids in its own namespace. id: my_title inside mod MyMod becomes MyMod:my_title; writing id: Creation:something inside MyMod is a load error.

Load errors

A malformed entry is skipped with an error rather than failing the mod — the cost is one unwearable reward, not an instance that will not start. An entry is refused when it:

declares an empty id,
declares an id in another mod’s namespace, or
reuses an id an earlier entry already declared.

An empty display-name is not an error; it reads the same as an omitted one.

Example

titles:
  - id: wayfarer

  - id: worlddelver
    display-name: World Delver

wayfarer renders as Wayfarer, the title-cased form of its id — which is what most entries rely on. worlddelver sets a display-name because its compound does not title-case into two words; it renders as that string in every locale that does not override it.

Last updated Sep 29, 2026