80 lines
4.5 KiB
Markdown
80 lines
4.5 KiB
Markdown
# E2.M1 — SkillDefinitionRegistry
|
||
|
||
## Summary
|
||
|
||
| Field | Value |
|
||
|--------|--------|
|
||
| **Module ID** | E2.M1 |
|
||
| **Epic** | [Epic 2 — Classless progression](../epics/epic_02_classless_progression.md) |
|
||
| **Stage target** | Prototype |
|
||
| **Status** | Planned (see [dependency register](module_dependency_register.md)) |
|
||
|
||
## 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`](../../game-design/gigs.md)).
|
||
|
||
## Data contract (schema)
|
||
|
||
| Artifact | Path |
|
||
|----------|------|
|
||
| **JSON Schema** | [`content/schemas/skill-def.schema.json`](../../../content/schemas/skill-def.schema.json) |
|
||
| **Sample catalog** | [`content/skills/prototype_skills.json`](../../../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`](../../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](E2_M2_XpAwardAndLevelEngine.md) 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`](../../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](CT_M1_ContentValidationPipeline.md) 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](E2_M2_XpAwardAndLevelEngine.md) 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`](../../../content/schemas/skill-def.schema.json) in CI ([CT.M1](CT_M1_ContentValidationPipeline.md#ci-prototype) — [`scripts/validate_content.py`](../../../scripts/validate_content.py) in **PR gate**) 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
|
||
|
||
- Game design: [`docs/game-design/skills.md`](../../game-design/skills.md) — roster, **XP philosophy**, gig/skill boundary.
|
||
- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 2.
|
||
- [Module dependency register](module_dependency_register.md)
|