Almanac Milestones Configuration

Author milestone → reward rules for The Almanac — collection thresholds that grant cosmetic, title, lore, or waypoint rewards (never power).

The Almanac is the game’s horizontal collection track: a book of everything a player has caught, felled, and found. Milestones are the payoff layer over it — a rule that says “when this chapter’s count reaches this threshold, grant this reward.” Rewards are deliberately limited to the four non-power families (cosmetic, title, lore, waypoint); the engine rejects any other family at load, so a milestone can never hand out combat power or a gate skip.

Per-player progress (which milestones a player has reached, which rewards they hold) is saved on the player and synced to their client, which shows a banner when a milestone is reached and a running “milestones reached / rewards earned” tally in the Almanac panel.

Note: the cosmetic / title / lore / waypoint reward systems are not built yet. Until they ship, a granted reward is recorded on the player but has no in-world effect — the banner and the earned tally are the visible payoff for now.

File Location

almanac-milestones-config: almanac-milestones-config.yaml

Then create the file it points to, relative to your mod’s folder.

Fields

The file has one top-level milestones: list. Each entry:

Field	Required	Description
`id`	yes	Unique id within your mod. Namespaced to `<mod>:<id>` internally; this is what a player’s “reached” set records. See Id rules below.
`name`	no	Display name for the “milestone reached” banner. Defaults to `id`.
`chapter`	yes	Which chapter’s progress to watch (counted milestones), or a grouping tag (event milestones). Currently `waters` or `discoveries`.
`metric`	yes	The count within that chapter (see the table below), or the literal `event` for a one-shot milestone — see Counted vs. event milestones.
`threshold`	counted only	The count at which the milestone is reached (must be ≥ 1). Required for a counted milestone; must be omitted for `metric: event`.
`reward`	yes	A `{ family, id }` map — see Rewards below.

Counted vs. event milestones

A milestone is reached one of two ways, selected by metric:

Counted (metric: species, worlds, …) — reached when the chapter’s running count crosses threshold. This is the ordinary form.
Event (metric: event, no threshold) — a one-shot beat reached the first time a named event fires for that player: reaching a world, felling a boss, clearing the game. The event’s id is the milestone’s own id — nothing fires it by name except a site that grants that id. Two things grant one:
- the engine, for events it owns — e.g. a world’s arrival-milestone in the world registry names the event milestone granted on first arrival; and
- a Lua progression script, via player:grant_milestone_event("<Mod>:<id>") (see the Lua entity API) — e.g. from a boss’s server-on-death hook.
A re-fire (a re-visit, a re-kill) is a no-op — an event milestone is reached at most once. Its chapter is only a display grouping; it is never evaluated as a count.

Id rules

Two rules are enforced at load; a milestone breaking either is logged and skipped:

Your own namespace only. Writing a bare id: first_catch is the normal form and becomes <YourMod>:first_catch. You may write the namespace out in full (id: YourMod:first_catch), but you may not declare an id under another mod’s namespace — id: Creation:first_catch in your mod is rejected. Ids elsewhere in a config that reference content may still be cross-mod; this rule applies to declaring one.
No duplicates. An id already declared by an earlier-loading milestone is refused. Two milestones sharing an id would both evaluate and both pay out while the player’s reached set recorded only one, so the second is never useful.

Metrics

A counted chapter/metric pair the engine does not count yet is loaded with a warning and can never be reached, so keep to the supported pairs (metric: event is exempt — it is not counted):

Chapter	Metric	Counts
`waters`	`species`	Distinct fish species recorded
`waters`	`shiny`	Distinct shiny species recorded
`waters`	`waters`	Distinct water types the player has landed a catch from
`discoveries`	`worlds`	Worlds this player has personally set foot in

Rewards

reward.family must be one of — anything else is rejected at load:

cosmetic — a skin, dye, gear/rod appearance, banner, or decor.
title — a name flourish.
lore — an unlocked codex / world-texture entry.
waypoint — a fast-travel attunement or map reveal.

reward.id is the id of the reward in its family’s registry (namespaced to your mod internally). Since the reward systems aren’t built yet, this is a forward reference — pick a stable id now.

Example

milestones:
  - id: first_steps
    name: First Steps
    chapter: discoveries
    metric: worlds
    threshold: 1
    reward:
      family: title
      id: wanderer

  - id: reef_regular
    name: Reef Regular
    chapter: waters
    metric: species
    threshold: 5
    reward:
      family: cosmetic
      id: reef_rod

  # A one-shot event milestone — no threshold. Granted when its event fires; here, a world's
  # `arrival-milestone: reached_desolation` in the world registry grants it on first arrival.
  - id: reached_desolation
    name: Desolation
    chapter: discoveries
    metric: event
    reward:
      family: title
      id: desolate

Last updated Aug 27, 2026