Files

160 lines
9.1 KiB
Markdown

# Levels, stats, titles, and equipment
Design update: the paragraphs below describe the current implementation. The
confirmed replacement-life rule is now character-owned progression, including
professions, weapon proficiency, spells/spell XP, stats, abilities, recipes, and
titles. Resurrection/world travel preserve these; replacement resets them. Only
cosmetic access is inherited. Account title inheritance below is legacy behavior
pending an explicit migration that preserves historical first claims. See
[lifecycle and ownership](LIFECYCLE-OWNERSHIP.md).
Levels belong to a character. Titles retain the existing account-bound interpretation
of player ownership: replacement lives inherit titles, while starting at level 1.
Dead characters retain historical stats and stay permanently dead. Survivor passage
preserves XP, allocations, pending rewards, titles, equipment, and the daily budget.
## Level rewards
Each level-up grants **10 allocatable stat points**, **5 maximum stamina**, and a
choice of **5 maximum health or 5 maximum mana**. Choices and points may be saved.
Increasing a maximum does not heal/refill the pool. The server accepts one primary
point per `allocate-stat` intent and one pending reward per `choose-vital` intent.
Overspending, derived-stat allocation, and actions after death/daily cap are rejected.
Initial tuning: level 1 start, 100 XP to level 2, thresholds increasing by 50 XP,
level 1000 cap. Gathering awards 10 XP, crafting 20, sentinel kills 50, boss killing
blow 500, modified by XP gain. Failed actions/nonlethal hits grant no XP. Threshold
overflow carries forward, including multiple level-ups. Activity tuning lives in
`server/content/balance.yaml` and a character's saved reward/XP curve follows it.
Legacy five-point characters receive five extra points and one pending vital choice
per earned level once. Migration preserves XP, deaths, and daily usage and is idempotent.
## Stats
| Allocatable primary | Derived stats |
| --- | --- |
| Constitution | Health points, endurance, resistance, health recovery |
| Intelligence | Magic damage, knowledge, spell points, mana points |
| Dexterity | Movement speed, ranged damage, critical chance, endurance, dodge chance, stamina recovery |
| Strength | Close-combat weapon damage, heavy-weapon damage, carrying capacity, endurance, defence |
| Wisdom | Knowledge, resistance, skill points, XP gain, mana recovery |
| Charisma | Buff effectiveness |
| Luck | Critical chance, drop rate, gathering rate, dodge chance |
Control character details and the player panel show **base / flat / percent / final**.
Primary base = configured base + allocated points. Derived base adds the contributions
of **final primary values** and level pool rewards. Each stat then uses:
`final = max(0, (base + sum(flat)) * max(0, 1 + sum(percent)/100))`
Health capacity has a floor of 50 for daily-limit safety. Critical/dodge chances cap
at 100%. Recovery rates are points per online simulation second. XP, drop, gathering,
and buff-effectiveness rates start at 100 (100%). Critical/dodge values are percentage
points. Critical damage uses `criticalMultiplier` in balance YAML.
Coefficients are provisional and editable through Control -> Content -> Stat formulas.
Constitution initially adds 5 health, 1 endurance, 0.5 resistance, and 0.02 health
recovery per point. Formula changes clamp current pools when maxima fall, without
healing or rewriting a dead life's stat record.
Current gameplay consumes health, movement, melee damage, defence, dodge, critical
chance, recovery, XP gain, drop rate, and gathering rate. Other listed stats are
calculated, inspectable, and available in requirements/effects. Dedicated spell,
ranged/heavy attack, skill-spending, timed-buff, stamina-cost, and encumbrance mechanics
await their later scope. Carry weight/capacity is advisory; stack units have weight 1.
## Control authoring
Administrators publish titles, equipment, and stat formulas in **Control -> Content**.
Publications require a reason and the current catalog version. Stale edits conflict;
identical request retries are idempotent. An immutable database audit records actor,
operation, target, reason, and version. World owners apply updates during their normal
control poll (about one second) and before joining, checkpointing before snapshots.
World records expose the applied version. Offline owners apply updates when resumed.
YAML seeds the catalog once. Later YAML edits do not overwrite published content.
Title/item definitions are append-only: use a new ID for a variation. Acquired items
and earned titles retain their original definition snapshots. Stat formulas are editable.
## Permanent titles
Requirements are ANDed positive integer thresholds. Metrics: level, kills, worldKills,
bossKills, worldsSurvived, gathering/crafting/combat skill XP, deaths, and any primary
or derived stat. worldKills resets on passage; deaths is 1 at death. Stat requirements
compare the final server-calculated value.
| Scope | Award policy |
| --- | --- |
| Personal | Every qualifying account earns the title once |
| World | First qualifying account to commit a claim in that world |
| Global | First qualifying account to commit across the shared database |
First claims start when the title is introduced; earlier achievements cannot be
reconstructed. Requirements evaluate on gameplay events, not editor publication.
Candidates follow event order; simultaneous milestones use stable character-ID order.
The world snapshot and title ledger commit atomically before effects become visible.
Every owned title is active once per ID forever. Flat and percentage modifiers may
be positive or negative and target any stat. Legacy damage/moveSpeed effects remain
compatible. Players cannot remove, trade, or lose titles if requirements cease
to hold. Content edits do not alter earned awards. Administrators have the audited
grant/revocation exception described below.
## Inventory and equipment
The 21 slots are helmet, mask, chest, shoulders, pants, boots, gloves, earrings,
necklace, ring1 through ring8, weapon, offhand, cape, and bag. Ring definitions use
category `ring`; players choose one of eight slots. Offhand definitions can represent
a shield or offhand weapon.
Definitions specify weight, level and optional stat/title requirements, plus signed
flat/percentage modifiers. Requirements exclude **all equipment effects**, preventing
self-enabling gear or mutually enabling pairs. Ineligible gear automatically returns
to the bag. Occupied slots must first be explicitly unequipped.
Equipment instances have unique IDs and snapshot their definitions. Equipping only
changes a slot assignment. Bags hold unequipped gear and resource/tool/consumable
stacks. Starting knives and crafted spears are gear; spear damage requires equipping.
Dropping moves one stack unit or one instance to a ground pile. Loot transfers whole
piles atomically. Death moves equipped/bag gear and stacks to the corpse. Passage
preserves IDs; duplicate item IDs within a world fail restoration. Legacy knife/spear
stacks migrate once, including corpses.
Control can set an equipment definition's per-sentinel-kill drop chance (0-100%). The
player's drop-rate multiplier applies, capped at a guaranteed drop. Zero disables
sentinel drops for that definition. Starting and crafted gear retains those existing
acquisition paths. Ordinary player intents cannot grant inventory.
## Administrator player changes
Open Control -> Characters -> a character -> Manage items and titles. An available
world owner and a living character or survivor are required. Each command records
the administrator, target, item/title value, reason, and completed/rejected result.
- Add items from published definitions or existing stackable items, 1-100 per command.
- Remove an exact equipment instance (including equipped gear) or a stack quantity.
- Add a title without achievement requirements, or restore a revoked original award.
- Revoke the account's active title and its effects. Normal gameplay cannot
re-award it until an administrator restores it.
Revocation keeps the original title ledger and first-world/first-ever claim reserved;
it does not release that claim to another player. Historical dead-life records stay
intact. Restoring a title keeps its original effects and provenance. Equipment that
loses a title prerequisite returns to the bag, rather than being deleted.
Changes are staged and committed atomically with the audit, stats, character record,
and survivor passage. Replays cannot duplicate grants, stale source worlds cannot
edit transferred characters, and admin inventory changes do not heal or reset the
daily budget. The player receives the change on the next committed snapshot.
## Verification and limits
Tests cover formulas, allocation, choices, migration, requirements, death/drop/loot,
passage, title claims, catalog publication/replay/conflicts, and checkpoint failures.
PostgreSQL integration tests require `TEST_DATABASE_URL`; SQLite tests run by default.
Browser tests cover player panels and Control authoring.
Tested capacity is unchanged. Existing checkpoint limits still apply: unacknowledged
actions may be lost on a crash; storage failure freezes further world snapshots.