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

4.4 KiB
Raw Blame History

E2.M1 — SkillDefinitionRegistry

Summary

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

Purpose

Central catalog for non-combat skill metadata: stable IDs, categories, allowed XP sources, and unlock prerequisites. All prototype activities reference skills by SkillDef.id validated against this registry. Combat role progression is not a SkillDef—use gig progression (docs/game-design/gigs.md).

Data contract (schema)

Artifact Path
JSON Schema content/schemas/skill-def.schema.json
Sample catalog content/skills/prototype_skills.json

SkillDef fields (prototype):

Field Rule
id Lowercase snake_case, immutable after ship. Used in saves, recipes, quests, XpGrantEvent.skillId, telemetry. Never rename to “fix” a skill—add a new id and migrate content if a skill splits.
category One of gather | process | make | tech — aligned with docs/game-design/skills.md roster buckets (not gigs).
displayName Player-facing string; may change without migrating progression data.
allowedXpSourceKinds Non-empty set of grant channels E2.M2 may apply to this skill. Combat encounters must not use skill XP—those award gig XP; mission_reward covers explicit mission/contract skill payouts.

allowedXpSourceKinds values:

Kind Meaning
activity Primary loop (e.g. gather node complete, recipe craft complete, skill-based world interaction)—callers set XpGrantEvent.sourceKind to match.
mission_reward Quest/contract hand-in or other scripted payout (docs/game-design/progression.md Mission rewards vs combat XP).
trainer NPC or teaching beat.
book_or_item Book, chip, training consumable, or similar one-shot grant.

Add new enum values only with a schema version / migration note in CT.M1 when CI enforces catalogs.

Responsibilities

  • Load and validate SkillDef from data; expose SkillCategory and UnlockRequirement for gating.
  • Reject unknown skillId or XP grants whose sourceKind is not listed on the target skill’s allowedXpSourceKinds (enforced in E2.M2 at grant time).

Key contracts

Contract Role
SkillDef Per-skill metadata: id, category, displayName, allowedXpSourceKinds (+ future unlock fields).
SkillCategory gather | process | make | tech for UX and balance.
UnlockRequirement Prerequisites before XP or use counts apply.

Acceptance criteria (E2.M1 / Slice 1)

  • Every loaded SkillDef validates against skill-def.schema.json in CI (CT.M1) or at server boot.
  • Duplicate id in a catalog fails validation.
  • Roster freeze for prototype: when Slice 1 locks three skills, their id values are treated as stable—downstream content (recipes, quests) may reference them; changing an id requires a migration or new row.
  • Document for designers: each new skill row must declare allowedXpSourceKinds so engineers know which systems may grant XP (gather/craft hooks vs E7.M2 mission rewards only, etc.).

Module dependencies

  • None

Dependents (by design)

  • E2.M2 — XpAwardAndLevelEngine (primary): validates grants against allowedXpSourceKinds.

Related implementation slices

Epic 2 Slice 1 — skill registry and prototype non-combat skills; invalid references fail at load or in CI.

Source anchors