Files
aeternalis/docs/PROGRESSION.md
T

93 lines
4.6 KiB
Markdown

# Levels and permanent titles
Levels belong to a character. Titles belong to an account in this first pass,
so a new life inherits titles while starting at level 1 with no XP or stat
points. A dead character remains dead and keeps its historical progression.
Survivor passage preserves levels, XP, points, titles, and the daily time budget.
## Provisional level tuning
Edit `server/content/balance.yaml`. New characters start at level 1. Reaching
level 2 takes 100 XP; each following threshold costs 50 XP more. Every level
awards 5 banked stat points. The current safety cap is level 1000. All of these
values are configuration, not a settled stat or balance design.
Successful gathering gives 10 XP, crafting 20 XP, a sentinel kill 50 XP, and
the boss killing blow 500 XP. Nonlethal hits, failed actions, duplicate requests,
and actions after death give no XP. XP beyond a threshold carries into the next
level, including multiple level-ups from one reward. XP stops at the cap.
There is no stat allocation or client XP-grant API. Points remain banked until
the full stat system is designed. Character level curves and point grants are
stored with the character, so moving into differently tuned worlds cannot reset
or reprice earned progress. Activity XP rewards use the destination world's tuning.
## Title definitions
The YAML `titles` list is the initial authoring interface. Each entry needs a
stable `id`, `name`, `description`, `scope`, one or more `requirements`, and
`effects`. Requirements are ANDed and use positive integer `atLeast` thresholds.
| Requirement metric | Meaning |
| --- | --- |
| `level` | Current character level |
| `kills` | Lifetime sentinel kills for this character |
| `worldKills` | Sentinel kills since arriving in this world; resets on passage |
| `bossKills` | Boss killing blows for this character |
| `worldsSurvived` | Worlds survived when their boss dies, including offline survivors |
| `gathering`, `crafting`, `combat` | Existing character skill XP counters |
| `deaths` | 1 when this character dies, otherwise 0 |
| Scope | Award policy |
| --- | --- |
| `personal` | Any qualifying account can earn the title once |
| `world` | First qualifying account to commit the title claim in a world |
| `global` | First qualifying account to commit the title claim across the shared database |
“First ever” is determined by the first committed eligible transaction, starting
when the title is introduced. It cannot reconstruct an achievement predating
the title system. All production worlds must share the PostgreSQL database.
Within a world, candidates follow simulation event order. Simultaneous survivor
milestones break ties by character ID. An account already owning a title does
not earn it again or stack its effects by visiting another world.
The shipped starter examples are Wayfarer (level 2, +1 damage), First Hunter of
the World (first sentinel kill in a world, +2 damage), and The First Hunter
(first sentinel kill globally, +3 damage and -0.5 movement speed).
Effects are additive `damage` and `moveSpeed` values using existing game units.
Negative values are supported. Every owned title is active; effective damage
and movement speed cannot go below zero. There is no equip, remove, trade, or
revoke action. Future stat/effect hooks can extend this catalog without deciding
the final player stat list now.
```yaml
- id: burdened_survivor
name: Burdened Survivor
description: Survive a world after defeating at least ten sentinels.
scope: personal
requirements:
- { metric: worldsSurvived, atLeast: 1 }
- { metric: kills, atLeast: 10 }
effects: { damage: 4, moveSpeed: -1 }
```
Worlds persist their balance and title catalogs. YAML edits apply to new world
IDs; they do not hot-edit existing worlds or already-earned titles. Existing
worlds without progression are upgraded once with the starter defaults on
restore, with no retroactive XP or automatic historical first claims. New
definitions can match existing counters on the next qualifying gameplay event.
Treat published title IDs as permanent identities. Use a new ID for a distinct
award rather than repurposing an existing one.
## Verification and limits
Game tests cover successful-action XP, multi-level grants, caps, migration,
signed effects, death, daily limits, and survivor progress. Store tests cover
durable title claims, first-award races, retries/rollback, inheritance, and stale
source worlds. PostgreSQL integration tests require `TEST_DATABASE_URL`.
The tested world capacity is unchanged. This remains the existing checkpoint
persistence model: unacknowledged actions can be lost on a crash, and storage
failures freeze the owner before it can publish speculative progression.