Files
aeternalis/docs/PROGRESSION.md
T

4.6 KiB

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.

- 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.