Skill Trees

The skill tree module lives in packages/core/src/skill/tree.ts.

Data Model

Skills are stored flat in the skills table with a parent_id self-reference:

skills (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  parent_id TEXT REFERENCES skills(id),
  xp INTEGER NOT NULL DEFAULT 0,
  level INTEGER NOT NULL DEFAULT 0,
  user_id TEXT NOT NULL
)

Building the Tree

buildSkillTree(skills: Skill[]): SkillNode[] takes the flat list from the database and constructs a directed acyclic graph. Each node has a children array containing its direct descendants.

import { buildSkillTree } from "@grindxp/core/skill";

const tree = buildSkillTree(await skillRepo.list(userId));
// → SkillNode[] with nested children

Root nodes (skills without a parent) are the top-level entries.

XP Routing

When a quest is completed, collectSkillXp determines how XP is distributed:

const updates = collectSkillXp(quest.skillTags, xpEarned);
// → [{ skillId, xpDelta }, ...]

XP is awarded to each tagged skill directly. Parent skills do not automatically receive child XP; each node is independent. updateSkillXp then applies the updates and recalculates the level for each affected skill.

Skill Repository

import { createSkillRepository } from "@grindxp/core/vault";

const repo = createSkillRepository(db);

// Create a skill
await repo.create({ name: "Strength", parentId: "fitness-skill-id" });

// List all
const skills = await repo.list(userId);

// Build the tree
const tree = buildSkillTree(skills);

// Update XP after quest completion (called internally by quest repo)
await repo.addXp(skillId, xpDelta);

Configuration

Security

Game Mechanics

For Contributors

Project

Data Model

Building the Tree

XP Routing

Skill Repository

​Data Model

​Building the Tree

​XP Routing

​Skill Repository

Data Model

Building the Tree

XP Routing

Skill Repository