don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
neon-sprawl/docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md

3.1 KiB
Raw Blame History

E2.M2 — XpAwardAndLevelEngine

Summary

Field Value
Module ID E2.M2
Epic Epic 2 — Classless Progression
Stage target Prototype
Status Planned (see dependency register)

Purpose

Central server-authoritative engine for classless skill progression: applying XP grants, resolving levels against data-driven curves, and emitting level-up events. Gathering and crafting integrate as callers for skill XP. Combat encounters advance gigs (gig XP), not SkillDef lines. Mission rewards may call this API for skill XP when the payout lists a skill grant. Callers are not hard dependencies for implementing the engine core (see Epic 2 Slice 2 vs Slice 3).

Responsibilities

  • Apply XpGrantEvent (or equivalent) per skill with validated skillId from E2.M1. Reject grants when sourceKind is not in the target SkillDef.allowedXpSourceKinds.
  • Resolve experience against LevelCurve / threshold tables.
  • Emit LevelUpEvent when thresholds are crossed.
  • Support data-driven curves; reload policy: Data reload and telemetry operations policy (boot load default; optional dev reload).

Key contracts

Contract Role
XpGrantEvent Structured XP award: skillId (must exist in registry), amount, sourceKind (must appear in that skill’s allowedXpSourceKinds), optional modifiers.
LevelCurve Thresholds or formula per skill or global policy.
LevelUpEvent Notification for UI, unlocks, and downstream systems.

Module dependencies

Dependents (by design)

  • E5.M1 — CombatRulesEngine: gig XP from combat (not SkillDef XP via E2.M2).
  • E3.M1 / E3.M2 — Gathering and crafting award XP when wired in Slice 3.
  • E7.M2 — RewardAndUnlockRouter routes quest rewards including XP through E2.M2.
  • E2.M3 / E2.M4 — Mastery and pacing layers build on level/XP state (pre-production).

Related implementation slices

  • Epic 2 Slice 2 — XP engine (E2.M2 core): implement contracts and tests without requiring Epic 3 or 5 modules.
  • Epic 2 Slice 3 — XP award integration: E3.M1 / E3.M2 call the skill XP API with sourceKind: activity (where allowed per skill); E7.M2 / mission rewards use mission_reward (etc.) as configured; combat resolves gig progression separately from E2.M2.

Risks and telemetry

  • Runaway leveling in one skill: diminishing returns per slice; monitor distribution via E9.M2 when available.
  • Telemetry: xp_grant, level_up, time-to-first-level-up once real activity fires.

Source anchors