@reldens/skills 0.46.0 → 0.48.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/.claude/architecture.md +472 -0
  2. package/.claude/class-hierarchy.md +982 -0
  3. package/.claude/event-system-architecture.md +475 -0
  4. package/.claude/level-progression.md +1259 -0
  5. package/.claude/skill-execution-flow.md +979 -0
  6. package/.claude/testing-guide.md +356 -0
  7. package/.claude/testing-patterns.md +1096 -0
  8. package/CLAUDE.md +164 -29
  9. package/lib/class-path.js +13 -10
  10. package/lib/client/receiver.js +1 -3
  11. package/lib/levels-set.js +24 -17
  12. package/lib/server/sender.js +1 -1
  13. package/lib/skill.js +19 -16
  14. package/lib/types/attack.js +28 -11
  15. package/lib/types/effect.js +10 -4
  16. package/lib/types/physical-attack.js +2 -2
  17. package/lib/types/physical-effect.js +2 -2
  18. package/lib/types/physical-properties-validator.js +1 -1
  19. package/lib/types/physical-skill-runner.js +5 -5
  20. package/package.json +9 -3
  21. package/tests/fixtures/levels/base-levels.js +89 -0
  22. package/tests/fixtures/mocks/mock-client.js +44 -0
  23. package/tests/fixtures/mocks/mock-owner.js +60 -0
  24. package/tests/fixtures/mocks/mock-target.js +50 -0
  25. package/tests/fixtures/skills/base-skills.js +80 -0
  26. package/tests/run-tests.js +88 -0
  27. package/tests/unit/client/test-receiver.js +249 -0
  28. package/tests/unit/server/test-sender.js +527 -0
  29. package/tests/unit/test-class-path.js +1239 -0
  30. package/tests/unit/test-level.js +176 -0
  31. package/tests/unit/test-levels-set.js +1227 -0
  32. package/tests/unit/test-server.js +266 -0
  33. package/tests/unit/test-skill.js +1302 -0
  34. package/tests/unit/types/test-attack.js +1195 -0
  35. package/tests/unit/types/test-effect.js +587 -0
  36. package/tests/unit/types/test-physical-attack.js +564 -0
  37. package/tests/unit/types/test-physical-effect.js +769 -0
  38. package/tests/unit/types/test-physical-properties-validator.js +203 -0
  39. package/tests/unit/types/test-physical-skill-runner.js +348 -0
  40. package/tests/utils/test-helpers.js +122 -0
@@ -0,0 +1,1259 @@
1
+ # LEVEL PROGRESSION SYSTEM
2
+ ## Complete Guide to Levels, Experience, and Class Paths
3
+
4
+ ---
5
+
6
+ ## OVERVIEW
7
+
8
+ The @reldens/skills package provides a sophisticated level progression system with automatic leveling, experience management, modifier application, and skill unlocking. This document covers the complete flow from level creation to class path progression.
9
+
10
+ ---
11
+
12
+ ## ARCHITECTURE
13
+
14
+ ### Core Classes
15
+
16
+ ```
17
+ Level (lib/level.js)
18
+ ↓
19
+ LevelsSet (lib/levels-set.js)
20
+ ↓
21
+ ClassPath (lib/class-path.js)
22
+ ↓
23
+ SkillsServer (lib/server.js)
24
+ ```
25
+
26
+ ### Hierarchy:
27
+ - **Level**: Single level with modifiers and XP requirement
28
+ - **LevelsSet**: Level collection with experience tracking and progression
29
+ - **ClassPath**: LevelsSet + skill trees + label management
30
+ - **SkillsServer**: ClassPath + server-client synchronization
31
+
32
+ ---
33
+
34
+ ## LEVEL CLASS
35
+
36
+ **File:** `lib/level.js:9-33`
37
+
38
+ ### Purpose
39
+
40
+ Represents a single level in a progression system with associated modifiers and requirements.
41
+
42
+ ### Properties
43
+
44
+ ```javascript
45
+ {
46
+ key: 5, // Level number (integer)
47
+ label: 'Expert', // Display name for this level
48
+ requiredExperience: 1000, // XP needed to reach this level
49
+ modifiers: [ // Modifiers applied at this level
50
+ hpModifier,
51
+ attackModifier
52
+ ]
53
+ }
54
+ ```
55
+
56
+ ### Constructor
57
+
58
+ ```javascript
59
+ constructor(props)
60
+ {
61
+ this.key = sc.get(props, 'key', false);
62
+ this.label = sc.get(props, 'label', this.key);
63
+ this.requiredExperience = sc.get(props, 'requiredExperience', 0);
64
+ this.modifiers = sc.get(props, 'modifiers', []);
65
+ }
66
+ ```
67
+
68
+ ### Key Points
69
+
70
+ - `key` must be an integer (level number)
71
+ - `label` defaults to key if not provided
72
+ - `requiredExperience` is cumulative (total XP needed, not delta)
73
+ - `modifiers` is an array of @reldens/modifiers Modifier instances
74
+ - Level instances are immutable once created
75
+
76
+ ### Example
77
+
78
+ ```javascript
79
+ import {Level} from '@reldens/skills';
80
+ import {Modifier} from '@reldens/modifiers';
81
+
82
+ let level5 = new Level({
83
+ key: 5,
84
+ label: 'Expert Warrior',
85
+ requiredExperience: 1000,
86
+ modifiers: [
87
+ new Modifier({
88
+ key: 'level-5-hp',
89
+ propertyKey: 'stats.hp',
90
+ operation: '+',
91
+ value: 50
92
+ }),
93
+ new Modifier({
94
+ key: 'level-5-attack',
95
+ propertyKey: 'stats.atk',
96
+ operation: '+',
97
+ value: 10
98
+ })
99
+ ]
100
+ });
101
+ ```
102
+
103
+ ---
104
+
105
+ ## LEVELSSET CLASS
106
+
107
+ **File:** `lib/levels-set.js:11-298`
108
+
109
+ ### Purpose
110
+
111
+ Manages level progression, experience tracking, automatic leveling, and modifier application.
112
+
113
+ ### Properties
114
+
115
+ ```javascript
116
+ {
117
+ owner: playerEntity, // Entity with getPosition() method
118
+ key: 'warrior-progression', // LevelsSet identifier
119
+ levels: { // Object of Level instances
120
+ 1: level1,
121
+ 5: level5,
122
+ 10: level10
123
+ },
124
+ currentLevel: 1, // Current level number
125
+ currentExp: 0, // Current experience points
126
+ autoFillRanges: true, // Auto-generate intermediate levels
127
+ autoFillExperienceMultiplier: 1.5, // XP multiplier for auto-filled levels
128
+ increaseLevelsWithExperience: true, // Auto level-up when XP threshold reached
129
+ setRequiredExperienceLimit: false // Cap XP at max level
130
+ }
131
+ ```
132
+
133
+ ### Initialization
134
+
135
+ **Method:** `init(props)` - File: `lib/levels-set.js:32-59`
136
+
137
+ ```javascript
138
+ let levelsSet = new LevelsSet();
139
+ await levelsSet.init({
140
+ owner: playerEntity,
141
+ key: 'warrior-levels',
142
+ levels: {
143
+ 1: new Level({key: 1, requiredExperience: 0}),
144
+ 5: new Level({key: 5, requiredExperience: 1000}),
145
+ 10: new Level({key: 10, requiredExperience: 5000})
146
+ },
147
+ currentLevel: 1,
148
+ currentExp: 0,
149
+ autoFillRanges: true
150
+ });
151
+ ```
152
+
153
+ **Initialization Flow:**
154
+
155
+ ```
156
+ 1. Fire INIT_LEVEL_SET_START event
157
+ 2. Set owner reference
158
+ 3. Set key, events, currentLevel, currentExp
159
+ 4. Call setLevels(props.levels)
160
+ → Auto-fill level ranges if enabled
161
+ → Sort levels by required experience
162
+ 5. Apply current level modifiers
163
+ 6. Fire INIT_LEVEL_SET_END event
164
+ ```
165
+
166
+ ### Auto-Fill Level Ranges
167
+
168
+ **Method:** `autoFillLevelRanges(levels)` - File: `lib/levels-set.js:96-160`
169
+
170
+ **Purpose:** Automatically generate intermediate levels between defined levels.
171
+
172
+ **Example:**
173
+ ```javascript
174
+ // Input levels:
175
+ {
176
+ 1: Level(key: 1, requiredExp: 0),
177
+ 10: Level(key: 10, requiredExp: 5000)
178
+ }
179
+
180
+ // With autoFillRanges: true
181
+ // Generates levels 2, 3, 4, 5, 6, 7, 8, 9
182
+
183
+ // Output:
184
+ {
185
+ 1: Level(key: 1, requiredExp: 0),
186
+ 2: Level(key: 2, requiredExp: 0 * 1.5 = 0),
187
+ 3: Level(key: 3, requiredExp: 0 * 1.5 = 0),
188
+ // ...
189
+ 9: Level(key: 9, requiredExp: calculated),
190
+ 10: Level(key: 10, requiredExp: 5000)
191
+ }
192
+ ```
193
+
194
+ **Algorithm:**
195
+
196
+ ```
197
+ For each gap between defined levels:
198
+ 1. Identify startLevel and endLevel
199
+ 2. Calculate totalGap = endLevel.requiredExp - startLevel.requiredExp
200
+ 3. Calculate numberOfLevels = (endLevel.key - startLevel.key - 1)
201
+ 4. For each intermediate level:
202
+ → Calculate baseIncrease = totalGap / (numberOfLevels + 1)
203
+ → Apply multiplier: expIncrease = baseIncrease * autoFillExperienceMultiplier^levelOffset
204
+ → Create new Level instance
205
+ → Fire GENERATED_LEVELS event
206
+ 5. Add all levels to levels object
207
+ ```
208
+
209
+ **Key Points:**
210
+ - Only fills gaps, doesn't modify defined levels
211
+ - Uses exponential growth with `autoFillExperienceMultiplier`
212
+ - Empty modifiers array for auto-generated levels
213
+ - Label defaults to level key number
214
+
215
+ ---
216
+
217
+ ### Experience Management
218
+
219
+ #### Adding Experience
220
+
221
+ **Method:** `addExperience(number)` - File: `lib/levels-set.js:162-224`
222
+
223
+ ```javascript
224
+ // Add 500 XP
225
+ await levelsSet.addExperience(500);
226
+ ```
227
+
228
+ **Flow:**
229
+
230
+ ```
231
+ 1. Calculate newTotalExp = currentExp + number
232
+ 2. Apply experience limit if setRequiredExperienceLimit enabled
233
+ → Cap at max level required experience
234
+ 3. Set currentExp = newTotalExp
235
+ 4. If increaseLevelsWithExperience enabled:
236
+ → Get next level data
237
+ → While currentExp >= nextLevel.requiredExperience:
238
+ → Level up
239
+ → Get next level data
240
+ 5. Fire LEVEL_EXPERIENCE_ADDED event with:
241
+ → this, number, newTotalExp, currentLevelIndex, nextLevelIndex,
242
+ nextLevelKey, nextLevel, nextLevelExp, isLevelUp
243
+ 6. Return newTotalExp
244
+ ```
245
+
246
+ **Parameters:**
247
+ - `number` (required): Amount of XP to add
248
+ - Returns: New total experience
249
+
250
+ **Events Fired:**
251
+ - `LEVEL_EXPERIENCE_ADDED` (always)
252
+ - `LEVEL_UP` (if level increased)
253
+
254
+ **Example:**
255
+ ```javascript
256
+ let levelsSet = new LevelsSet();
257
+ await levelsSet.init({
258
+ owner: player,
259
+ levels: {
260
+ 1: new Level({key: 1, requiredExperience: 0}),
261
+ 2: new Level({key: 2, requiredExperience: 100}),
262
+ 3: new Level({key: 3, requiredExperience: 300})
263
+ },
264
+ currentLevel: 1,
265
+ currentExp: 0,
266
+ increaseLevelsWithExperience: true
267
+ });
268
+
269
+ // Add 250 XP - will level up from 1 to 3
270
+ await levelsSet.addExperience(250);
271
+
272
+ console.log(levelsSet.currentLevel); // 3
273
+ console.log(levelsSet.currentExp); // 250
274
+ ```
275
+
276
+ #### Getting Next Level Experience
277
+
278
+ **Method:** `getNextLevelExperience()` - File: `lib/levels-set.js:226-245`
279
+
280
+ ```javascript
281
+ let nextLevelXP = levelsSet.getNextLevelExperience();
282
+ console.log(`Need ${nextLevelXP} XP for next level`);
283
+ ```
284
+
285
+ **Returns:**
286
+ - Next level's required experience
287
+ - `null` if at max level
288
+
289
+ **Example:**
290
+ ```javascript
291
+ let levelsSet = new LevelsSet();
292
+ await levelsSet.init({
293
+ levels: {
294
+ 1: new Level({key: 1, requiredExperience: 0}),
295
+ 2: new Level({key: 2, requiredExperience: 100})
296
+ },
297
+ currentLevel: 1,
298
+ currentExp: 50
299
+ });
300
+
301
+ let nextLevelXP = levelsSet.getNextLevelExperience(); // 100
302
+ let remaining = nextLevelXP - levelsSet.currentExp; // 50
303
+ ```
304
+
305
+ ---
306
+
307
+ ### Level Up / Level Down
308
+
309
+ #### Level Up
310
+
311
+ **Method:** `levelUp()` - File: `lib/levels-set.js:247-257`
312
+
313
+ ```javascript
314
+ await levelsSet.levelUp();
315
+ ```
316
+
317
+ **Flow:**
318
+
319
+ ```
320
+ 1. Fire LEVEL_UP event (params: this)
321
+ 2. Increment currentLevel
322
+ 3. Call applyLevelModifiers()
323
+ ```
324
+
325
+ **Important:**
326
+ - Does NOT check if next level exists
327
+ - Does NOT validate XP requirements
328
+ - Caller must ensure level up is valid
329
+ - Usually called from addExperience() when XP threshold reached
330
+
331
+ #### Level Down
332
+
333
+ **Method:** `levelDown()` - File: `lib/levels-set.js:259-269`
334
+
335
+ ```javascript
336
+ await levelsSet.levelDown();
337
+ ```
338
+
339
+ **Flow:**
340
+
341
+ ```
342
+ 1. Fire LEVEL_DOWN event (params: this)
343
+ 2. Decrement currentLevel
344
+ 3. Call applyLevelModifiers()
345
+ ```
346
+
347
+ **Important:**
348
+ - Does NOT check if previous level exists
349
+ - Caller must ensure level down is valid
350
+ - Use case: Death penalty, level drain effects
351
+
352
+ ---
353
+
354
+ ### Modifier Application
355
+
356
+ **Method:** `applyLevelModifiers()` - File: `lib/levels-set.js:271-289`
357
+
358
+ **Purpose:** Apply current level modifiers and revert old level modifiers.
359
+
360
+ **Flow:**
361
+
362
+ ```
363
+ 1. Fire LEVEL_APPLY_MODIFIERS event (params: this)
364
+ 2. Get previous level from previousLevel property
365
+ 3. Get current level from levels[currentLevel]
366
+ 4. If previousLevel exists and has modifiers:
367
+ → Revert each modifier from owner
368
+ → sc.revertModifier(owner, modifier)
369
+ 5. If currentLevel exists and has modifiers:
370
+ → Apply each modifier to owner
371
+ → sc.applyModifier(owner, modifier)
372
+ 6. Update previousLevel = currentLevel
373
+ ```
374
+
375
+ **Example:**
376
+ ```javascript
377
+ // Level 1 modifiers: +50 HP
378
+ // Level 2 modifiers: +100 HP
379
+
380
+ // Player at level 1: HP = base(100) + modifier(50) = 150
381
+
382
+ await levelsSet.levelUp(); // Goes to level 2
383
+
384
+ // After applyLevelModifiers():
385
+ // 1. Revert level 1 modifier: HP = 150 - 50 = 100
386
+ // 2. Apply level 2 modifier: HP = 100 + 100 = 200
387
+ ```
388
+
389
+ **Important:**
390
+ - Modifiers are applied through @reldens/modifiers system
391
+ - Uses `sc.applyModifier()` and `sc.revertModifier()` from @reldens/utils
392
+ - Owner must have properties referenced by modifiers
393
+ - If level has no modifiers, this step is skipped
394
+
395
+ ---
396
+
397
+ ### Event System
398
+
399
+ **Events Fired by LevelsSet:**
400
+
401
+ | Event | When | Parameters |
402
+ |-------|------|------------|
403
+ | `INIT_LEVEL_SET_START` | Before initialization | (this) |
404
+ | `INIT_LEVEL_SET_END` | After initialization | (this) |
405
+ | `SET_LEVELS` | After levels are set | (this, levels) |
406
+ | `GENERATED_LEVELS` | After auto-filling range | (this, startLevel, endLevel, generatedLevels) |
407
+ | `LEVEL_UP` | After level increases | (this) |
408
+ | `LEVEL_DOWN` | After level decreases | (this) |
409
+ | `LEVEL_APPLY_MODIFIERS` | Before modifier changes | (this) |
410
+ | `LEVEL_EXPERIENCE_ADDED` | After XP added | (this, number, newTotal, currentIdx, nextIdx, nextKey, nextLevel, nextExp, isLevelUp) |
411
+
412
+ **Listening to Events:**
413
+
414
+ ```javascript
415
+ levelsSet.listenEvent(SkillsEvents.LEVEL_UP, async (levelsSet) => {
416
+ console.log('Leveled up!', levelsSet.currentLevel);
417
+ // Show animation, play sound, award achievement
418
+ }, 'my-level-up-listener');
419
+
420
+ levelsSet.listenEvent(SkillsEvents.LEVEL_EXPERIENCE_ADDED, async (
421
+ levelsSet,
422
+ xpAdded,
423
+ newTotal,
424
+ currentIdx,
425
+ nextIdx,
426
+ nextKey,
427
+ nextLevel,
428
+ nextLevelXP,
429
+ isLevelUp
430
+ ) => {
431
+ console.log(`Gained ${xpAdded} XP (total: ${newTotal})`);
432
+ if(isLevelUp){
433
+ console.log('LEVEL UP!');
434
+ } else {
435
+ console.log(`Next level at ${nextLevelXP} XP`);
436
+ }
437
+ }, 'xp-gain-listener');
438
+ ```
439
+
440
+ ---
441
+
442
+ ## CLASSPATH CLASS
443
+
444
+ **File:** `lib/class-path.js:11-315`
445
+
446
+ ### Purpose
447
+
448
+ Extends LevelsSet to provide class-based progression with skill trees and dynamic labels.
449
+
450
+ ### Additional Properties
451
+
452
+ ```javascript
453
+ {
454
+ // Inherited from LevelsSet:
455
+ owner, key, levels, currentLevel, currentExp, ...
456
+
457
+ // ClassPath-specific:
458
+ label: 'Warrior', // Base display name
459
+ currentLabel: 'Warrior', // Active label (changes with level)
460
+ labelsByLevel: { // Level-specific labels
461
+ 1: 'Novice Warrior',
462
+ 5: 'Veteran Warrior',
463
+ 10: 'Master Warrior'
464
+ },
465
+ skillsByLevel: { // Skill instances by level
466
+ 1: [swordSkill],
467
+ 5: [shieldSkill, bashSkill],
468
+ 10: [whirlwindSkill]
469
+ },
470
+ skillsByLevelKeys: { // Skill keys by level (for serialization)
471
+ 1: ['sword-attack'],
472
+ 5: ['shield-block', 'bash'],
473
+ 10: ['whirlwind']
474
+ },
475
+ currentSkills: { // Currently available skills
476
+ 'sword-attack': swordSkill,
477
+ 'shield-block': shieldSkill
478
+ },
479
+ affectedProperty: 'hp' // Property affected by class skills
480
+ }
481
+ ```
482
+
483
+ ### Initialization
484
+
485
+ **Method:** `init(props)` - File: `lib/class-path.js:46-80`
486
+
487
+ ```javascript
488
+ let classPath = new ClassPath();
489
+ await classPath.init({
490
+ owner: playerEntity,
491
+ key: 'warrior',
492
+ label: 'Warrior',
493
+ labelsByLevel: {
494
+ 1: 'Novice Warrior',
495
+ 10: 'Master Warrior'
496
+ },
497
+ levels: {
498
+ 1: new Level({key: 1, requiredExperience: 0}),
499
+ 10: new Level({key: 10, requiredExperience: 5000})
500
+ },
501
+ skillsByLevel: {
502
+ 1: [swordSkill],
503
+ 10: [masterSkill]
504
+ },
505
+ currentLevel: 1,
506
+ currentExp: 0
507
+ });
508
+ ```
509
+
510
+ **Initialization Flow:**
511
+
512
+ ```
513
+ 1. Call parent LevelsSet.init()
514
+ → Sets up levels, XP, modifiers
515
+ 2. Set label and currentLabel
516
+ 3. Set labelsByLevel
517
+ 4. Set skillsByLevel and skillsByLevelKeys
518
+ 5. Set affectedProperty
519
+ 6. Call setOwnerSkills()
520
+ → Populates currentSkills with skills up to current level
521
+ 7. Fire INIT_CLASS_PATH_END event
522
+ ```
523
+
524
+ ---
525
+
526
+ ### Skill Management
527
+
528
+ #### Setting Owner Skills
529
+
530
+ **Method:** `setOwnerSkills(skills)` - File: `lib/class-path.js:82-123`
531
+
532
+ **Purpose:** Initialize currentSkills based on current level or provided skills.
533
+
534
+ **Flow:**
535
+
536
+ ```
537
+ 1. If skills parameter provided:
538
+ → Use provided skills directly
539
+ 2. Else if skillsByLevel defined:
540
+ → Collect all skills from levels <= currentLevel
541
+ → Build currentSkills object by skill key
542
+ 3. Fire SET_SKILLS event (params: this, skills)
543
+ 4. Return currentSkills
544
+ ```
545
+
546
+ **Example:**
547
+ ```javascript
548
+ let classPath = new ClassPath();
549
+ await classPath.init({
550
+ owner: player,
551
+ skillsByLevel: {
552
+ 1: [skill1, skill2],
553
+ 5: [skill3],
554
+ 10: [skill4]
555
+ },
556
+ currentLevel: 5
557
+ });
558
+
559
+ // currentSkills contains: skill1, skill2, skill3
560
+ // skill4 not available (requires level 10)
561
+ ```
562
+
563
+ #### Adding Skills
564
+
565
+ **Method:** `addSkills(skills)` - File: `lib/class-path.js:125-145`
566
+
567
+ ```javascript
568
+ await classPath.addSkills([newSkill1, newSkill2]);
569
+ ```
570
+
571
+ **Flow:**
572
+
573
+ ```
574
+ 1. Fire ADD_SKILLS_BEFORE event (params: this, skills)
575
+ 2. For each skill in skills array:
576
+ → Add to currentSkills by skill.key
577
+ 3. Fire ADD_SKILLS_AFTER event (params: this, skills)
578
+ 4. Return currentSkills
579
+ ```
580
+
581
+ **Use Cases:**
582
+ - Level up unlocked new skills
583
+ - Learned skill from trainer
584
+ - Equipped item grants temporary skill
585
+
586
+ #### Removing Skills
587
+
588
+ **Method:** `removeSkills(skills)` - File: `lib/class-path.js:147-170`
589
+
590
+ ```javascript
591
+ await classPath.removeSkills([oldSkill1, oldSkill2]);
592
+ ```
593
+
594
+ **Flow:**
595
+
596
+ ```
597
+ 1. Fire REMOVE_SKILLS_BEFORE event (params: this, skills)
598
+ 2. For each skill in skills array:
599
+ → Delete from currentSkills by skill.key
600
+ 3. Fire REMOVE_SKILLS_AFTER event (params: this, skills)
601
+ 4. Return currentSkills
602
+ ```
603
+
604
+ **Use Cases:**
605
+ - Skill forgotten or replaced
606
+ - Temporary skill expired
607
+ - Unequipped item removed skill
608
+
609
+ ---
610
+
611
+ ### Label Management
612
+
613
+ **Labels change dynamically based on level progression.**
614
+
615
+ **Method:** `updateLabelByLevel()` - File: `lib/class-path.js:172-182`
616
+
617
+ ```javascript
618
+ // Called automatically during levelUp()
619
+ classPath.updateLabelByLevel();
620
+ ```
621
+
622
+ **Flow:**
623
+
624
+ ```
625
+ 1. Check if labelsByLevel has entry for currentLevel
626
+ 2. If yes:
627
+ → Set currentLabel = labelsByLevel[currentLevel]
628
+ 3. Else:
629
+ → Keep currentLabel unchanged
630
+ ```
631
+
632
+ **Example:**
633
+ ```javascript
634
+ let classPath = new ClassPath();
635
+ await classPath.init({
636
+ label: 'Warrior',
637
+ labelsByLevel: {
638
+ 1: 'Novice Warrior',
639
+ 5: 'Veteran Warrior',
640
+ 10: 'Master Warrior'
641
+ },
642
+ currentLevel: 1
643
+ });
644
+
645
+ console.log(classPath.currentLabel); // 'Novice Warrior'
646
+
647
+ await classPath.levelUp(); // Level 2
648
+ console.log(classPath.currentLabel); // 'Novice Warrior' (no label for level 2)
649
+
650
+ // Add XP to reach level 5
651
+ await classPath.addExperience(1000);
652
+ console.log(classPath.currentLabel); // 'Veteran Warrior'
653
+ ```
654
+
655
+ ---
656
+
657
+ ### Level Up Override
658
+
659
+ **Method:** `levelUp()` - File: `lib/class-path.js:184-207`
660
+
661
+ **ClassPath extends LevelsSet.levelUp() to add skill unlocking and label updates.**
662
+
663
+ **Flow:**
664
+
665
+ ```
666
+ 1. Call parent LevelsSet.levelUp()
667
+ → Fires LEVEL_UP event
668
+ → Increments currentLevel
669
+ → Applies level modifiers
670
+ 2. Update label based on new level
671
+ → updateLabelByLevel()
672
+ 3. Check if new skills available at this level
673
+ → If skillsByLevel[currentLevel] exists:
674
+ → addSkills(skillsByLevel[currentLevel])
675
+ → Fires ADD_SKILLS_BEFORE
676
+ → Adds skills to currentSkills
677
+ → Fires ADD_SKILLS_AFTER
678
+ ```
679
+
680
+ **Example:**
681
+ ```javascript
682
+ let classPath = new ClassPath();
683
+ await classPath.init({
684
+ owner: player,
685
+ labelsByLevel: {
686
+ 1: 'Novice',
687
+ 5: 'Expert'
688
+ },
689
+ skillsByLevel: {
690
+ 1: [basicSkill],
691
+ 5: [advancedSkill]
692
+ },
693
+ levels: {
694
+ 1: new Level({key: 1, requiredExperience: 0}),
695
+ 5: new Level({key: 5, requiredExperience: 1000})
696
+ },
697
+ currentLevel: 4,
698
+ currentExp: 999
699
+ });
700
+
701
+ // Add 1 XP to trigger level up
702
+ await classPath.addExperience(1);
703
+
704
+ // Results:
705
+ // - currentLevel = 5
706
+ // - currentLabel = 'Expert'
707
+ // - currentSkills includes advancedSkill
708
+ // - Level 5 modifiers applied
709
+ ```
710
+
711
+ ---
712
+
713
+ ### Event System
714
+
715
+ **Events Fired by ClassPath:**
716
+
717
+ All LevelsSet events PLUS:
718
+
719
+ | Event | When | Parameters |
720
+ |-------|------|------------|
721
+ | `INIT_CLASS_PATH_END` | After ClassPath initialization | (this) |
722
+ | `SET_SKILLS` | After owner skills set | (this, skills) |
723
+ | `ADD_SKILLS_BEFORE` | Before adding skills | (this, skills) |
724
+ | `ADD_SKILLS_AFTER` | After adding skills | (this, skills) |
725
+ | `REMOVE_SKILLS_BEFORE` | Before removing skills | (this, skills) |
726
+ | `REMOVE_SKILLS_AFTER` | After removing skills | (this, skills) |
727
+
728
+ **Example:**
729
+ ```javascript
730
+ classPath.listenEvent(SkillsEvents.INIT_CLASS_PATH_END, async (classPath) => {
731
+ console.log('Class path initialized:', classPath.key);
732
+ console.log('Starting skills:', Object.keys(classPath.currentSkills));
733
+ }, 'init-listener');
734
+
735
+ classPath.listenEvent(SkillsEvents.ADD_SKILLS_AFTER, async (classPath, skills) => {
736
+ console.log('New skills unlocked:');
737
+ skills.forEach(skill => {
738
+ console.log(`- ${skill.key}`);
739
+ });
740
+ }, 'skill-unlock-listener');
741
+ ```
742
+
743
+ ---
744
+
745
+ ## SKILLSSERVER CLASS
746
+
747
+ **File:** `lib/server.js:11-85`
748
+
749
+ ### Purpose
750
+
751
+ Server-side wrapper for ClassPath with automatic client synchronization via Sender.
752
+
753
+ ### Properties
754
+
755
+ ```javascript
756
+ {
757
+ // All ClassPath properties...
758
+
759
+ // SkillsServer-specific:
760
+ client: roomClient, // Client object with send() and broadcast()
761
+ sender: senderInstance // Sender instance for message broadcasting
762
+ }
763
+ ```
764
+
765
+ ### Initialization
766
+
767
+ **Constructor:** `constructor(props)` - File: `lib/server.js:18-50`
768
+
769
+ ```javascript
770
+ import {SkillsServer} from '@reldens/skills/lib/server.js';
771
+
772
+ let skillsServer = new SkillsServer({
773
+ owner: playerEntity,
774
+ client: roomClient, // Must have send() and broadcast() methods
775
+ key: 'warrior',
776
+ label: 'Warrior',
777
+ levels: {
778
+ 1: level1,
779
+ 5: level5
780
+ },
781
+ skillsByLevel: {
782
+ 1: [skill1],
783
+ 5: [skill2]
784
+ },
785
+ currentLevel: 1,
786
+ currentExp: 0
787
+ });
788
+ ```
789
+
790
+ **Initialization Flow:**
791
+
792
+ ```
793
+ 1. Validate client has send() method
794
+ → If missing: throw error
795
+ 2. Validate client has broadcast() method
796
+ → If missing: throw error
797
+ 3. Call parent ClassPath.init()
798
+ → Initializes levels, skills, XP
799
+ 4. Create Sender instance
800
+ → Pass this (ClassPath) and client
801
+ 5. Call sender.registerListeners()
802
+ → Sets up event listeners for client sync
803
+ ```
804
+
805
+ **Client Validation:**
806
+ ```javascript
807
+ // Client must implement:
808
+ class RoomClient {
809
+ send(message) {
810
+ // Send to this client only
811
+ }
812
+
813
+ broadcast(message) {
814
+ // Send to all clients in room
815
+ }
816
+ }
817
+ ```
818
+
819
+ ---
820
+
821
+ ### Server-Client Synchronization
822
+
823
+ **SkillsServer automatically broadcasts level/skill changes to clients via Sender.**
824
+
825
+ **Registered Events (via Sender):**
826
+
827
+ | Event | Message Action | Behavior | Data Sent |
828
+ |-------|---------------|----------|-----------|
829
+ | `INIT_CLASS_PATH_END` | `ACTION_INIT_CLASS_PATH_END` | SEND | level, label, XP, skills |
830
+ | `LEVEL_UP` | `ACTION_LEVEL_UP` | SEND | level, label, skills, nextXP |
831
+ | `LEVEL_EXPERIENCE_ADDED` | `ACTION_LEVEL_EXPERIENCE_ADDED` | SEND | current XP |
832
+ | `SKILL_BEFORE_CAST` | `ACTION_SKILL_BEFORE_CAST` | BROADCAST | skill key, owner |
833
+ | `SKILL_ATTACK_APPLY_DAMAGE` | `ACTION_SKILL_ATTACK_APPLY_DAMAGE` | BROADCAST | damage, target, skill |
834
+
835
+ **Message Format:**
836
+ ```javascript
837
+ {
838
+ act: 'rski.Lu', // Action constant (LEVEL_UP)
839
+ owner: 'player-123',
840
+ data: {
841
+ lvl: 5, // Current level
842
+ lab: 'Expert Warrior', // Current label
843
+ ne: 2000, // Next level XP
844
+ skl: ['sword', 'shield'] // Skill keys
845
+ }
846
+ }
847
+ ```
848
+
849
+ **Example Usage:**
850
+ ```javascript
851
+ // Server side
852
+ let skillsServer = new SkillsServer({
853
+ owner: player,
854
+ client: roomClient,
855
+ key: 'warrior',
856
+ levels: levels,
857
+ skillsByLevel: skillsByLevel
858
+ });
859
+
860
+ // When player gains XP:
861
+ await skillsServer.addExperience(500);
862
+
863
+ // Automatically sends message to client:
864
+ // {
865
+ // act: 'rski.Ea',
866
+ // owner: player.id,
867
+ // data: {exp: 500}
868
+ // }
869
+
870
+ // If leveled up, also sends:
871
+ // {
872
+ // act: 'rski.Lu',
873
+ // owner: player.id,
874
+ // data: {lvl: 2, lab: 'Novice', ne: 200, skl: ['skill1', 'skill2']}
875
+ // }
876
+ ```
877
+
878
+ ---
879
+
880
+ ## COMPLETE PROGRESSION FLOW
881
+
882
+ ### Example: Player Progression from Level 1 to 10
883
+
884
+ ```javascript
885
+ import {SkillsServer} from '@reldens/skills/lib/server.js';
886
+ import {Level} from '@reldens/skills/lib/level.js';
887
+ import {Modifier} from '@reldens/modifiers';
888
+
889
+ // 1. Define levels with modifiers
890
+ let levels = {
891
+ 1: new Level({
892
+ key: 1,
893
+ label: 'Novice',
894
+ requiredExperience: 0,
895
+ modifiers: [
896
+ new Modifier({key: 'hp-1', propertyKey: 'stats.hp', operation: '+', value: 50})
897
+ ]
898
+ }),
899
+ 5: new Level({
900
+ key: 5,
901
+ label: 'Veteran',
902
+ requiredExperience: 1000,
903
+ modifiers: [
904
+ new Modifier({key: 'hp-5', propertyKey: 'stats.hp', operation: '+', value: 150}),
905
+ new Modifier({key: 'atk-5', propertyKey: 'stats.atk', operation: '+', value: 20})
906
+ ]
907
+ }),
908
+ 10: new Level({
909
+ key: 10,
910
+ label: 'Master',
911
+ requiredExperience: 5000,
912
+ modifiers: [
913
+ new Modifier({key: 'hp-10', propertyKey: 'stats.hp', operation: '+', value: 300}),
914
+ new Modifier({key: 'atk-10', propertyKey: 'stats.atk', operation: '+', value: 50}),
915
+ new Modifier({key: 'def-10', propertyKey: 'stats.def', operation: '+', value: 30})
916
+ ]
917
+ })
918
+ };
919
+
920
+ // 2. Define skills by level
921
+ let skillsByLevel = {
922
+ 1: [basicSwordSkill],
923
+ 5: [powerAttackSkill, shieldBlockSkill],
924
+ 10: [ultimateSkill]
925
+ };
926
+
927
+ // 3. Initialize SkillsServer
928
+ let skillsServer = new SkillsServer({
929
+ owner: player,
930
+ client: roomClient,
931
+ key: 'warrior-path',
932
+ label: 'Warrior',
933
+ labelsByLevel: {
934
+ 1: 'Novice Warrior',
935
+ 5: 'Veteran Warrior',
936
+ 10: 'Master Warrior'
937
+ },
938
+ levels: levels,
939
+ skillsByLevel: skillsByLevel,
940
+ currentLevel: 1,
941
+ currentExp: 0,
942
+ autoFillRanges: true,
943
+ increaseLevelsWithExperience: true
944
+ });
945
+
946
+ // 4. Player gains XP from killing monster
947
+ await skillsServer.addExperience(250);
948
+ // - currentExp = 250
949
+ // - Still level 1
950
+ // - Client receives: {act: 'rski.Ea', data: {exp: 250}}
951
+
952
+ // 5. Player gains more XP
953
+ await skillsServer.addExperience(750);
954
+ // - currentExp = 1000
955
+ // - Levels up: 1 → 2 → 3 → 4 → 5 (auto-filled levels)
956
+ // - currentLevel = 5
957
+ // - currentLabel = 'Veteran Warrior'
958
+ // - Modifiers changed: -50 HP, +150 HP, +20 ATK = net +100 HP, +20 ATK
959
+ // - Skills added: powerAttackSkill, shieldBlockSkill
960
+ // - Client receives:
961
+ // - {act: 'rski.Ea', data: {exp: 1000}}
962
+ // - {act: 'rski.Lu', data: {lvl: 5, lab: 'Veteran Warrior', ...}}
963
+
964
+ // 6. Player continues to level 10
965
+ await skillsServer.addExperience(4000);
966
+ // - currentExp = 5000
967
+ // - Levels up: 5 → 6 → 7 → 8 → 9 → 10
968
+ // - currentLevel = 10
969
+ // - currentLabel = 'Master Warrior'
970
+ // - Modifiers changed: -150 HP, -20 ATK, +300 HP, +50 ATK, +30 DEF
971
+ // - Skills added: ultimateSkill
972
+ // - Client receives level up messages
973
+
974
+ // 7. At max level, can still gain XP but won't level up
975
+ await skillsServer.addExperience(1000);
976
+ // - currentExp = 6000 (above max required)
977
+ // - Still level 10
978
+ // - Client receives: {act: 'rski.Ea', data: {exp: 6000}}
979
+ ```
980
+
981
+ ---
982
+
983
+ ## COMMON PATTERNS
984
+
985
+ ### Pattern #1: Multi-Class System
986
+
987
+ ```javascript
988
+ let classes = {
989
+ warrior: new SkillsServer({
990
+ owner: player,
991
+ client: client,
992
+ key: 'warrior',
993
+ label: 'Warrior',
994
+ levels: warriorLevels,
995
+ skillsByLevel: warriorSkills
996
+ }),
997
+ mage: new SkillsServer({
998
+ owner: player,
999
+ client: client,
1000
+ key: 'mage',
1001
+ label: 'Mage',
1002
+ levels: mageLevels,
1003
+ skillsByLevel: mageSkills
1004
+ })
1005
+ };
1006
+
1007
+ // Level up specific class
1008
+ await classes.warrior.addExperience(500);
1009
+ await classes.mage.addExperience(300);
1010
+ ```
1011
+
1012
+ ---
1013
+
1014
+ ### Pattern #2: Skill Tree with Prerequisites
1015
+
1016
+ ```javascript
1017
+ let classPath = new ClassPath();
1018
+ await classPath.init({
1019
+ owner: player,
1020
+ skillsByLevel: {
1021
+ 1: [basicSkill],
1022
+ 5: [intermediateSkill], // Requires level 5
1023
+ 10: [advancedSkill] // Requires level 10
1024
+ }
1025
+ });
1026
+
1027
+ // Check if player meets skill requirement
1028
+ function canLearnSkill(skill, classPath) {
1029
+ for(let [level, skills] of Object.entries(classPath.skillsByLevel)) {
1030
+ if(skills.includes(skill)) {
1031
+ return classPath.currentLevel >= parseInt(level);
1032
+ }
1033
+ }
1034
+ return false;
1035
+ }
1036
+ ```
1037
+
1038
+ ---
1039
+
1040
+ ### Pattern #3: Prestige/Rebirth System
1041
+
1042
+ ```javascript
1043
+ async function prestigeClass(classPath) {
1044
+ // Store current level for rewards
1045
+ let prestigeLevel = classPath.currentLevel;
1046
+
1047
+ // Reset to level 1
1048
+ while(classPath.currentLevel > 1) {
1049
+ await classPath.levelDown();
1050
+ }
1051
+ classPath.currentExp = 0;
1052
+
1053
+ // Apply prestige bonus (permanent modifier)
1054
+ let prestigeBonus = new Modifier({
1055
+ key: `prestige-${prestigeLevel}`,
1056
+ propertyKey: 'stats.prestigeBonus',
1057
+ operation: '+',
1058
+ value: prestigeLevel * 10
1059
+ });
1060
+ sc.applyModifier(classPath.owner, prestigeBonus);
1061
+
1062
+ return prestigeLevel;
1063
+ }
1064
+ ```
1065
+
1066
+ ---
1067
+
1068
+ ### Pattern #4: Experience Gain with Modifiers
1069
+
1070
+ ```javascript
1071
+ function calculateXpGain(baseXp, player) {
1072
+ let xpModifier = 1.0;
1073
+
1074
+ // XP boost items
1075
+ if(player.hasItem('xp-potion')) {
1076
+ xpModifier += 0.5; // +50% XP
1077
+ }
1078
+
1079
+ // Party bonus
1080
+ if(player.inParty) {
1081
+ xpModifier += 0.2; // +20% XP
1082
+ }
1083
+
1084
+ // Level difference penalty
1085
+ let levelDiff = player.level - monster.level;
1086
+ if(levelDiff > 5) {
1087
+ xpModifier *= 0.5; // -50% XP for easy monsters
1088
+ }
1089
+
1090
+ return Math.floor(baseXp * xpModifier);
1091
+ }
1092
+
1093
+ // Usage
1094
+ let xpGained = calculateXpGain(100, player);
1095
+ await classPath.addExperience(xpGained);
1096
+ ```
1097
+
1098
+ ---
1099
+
1100
+ ### Pattern #5: Skill Point System
1101
+
1102
+ ```javascript
1103
+ class SkillPointClassPath extends ClassPath {
1104
+ constructor(props) {
1105
+ super(props);
1106
+ this.skillPoints = 0;
1107
+ }
1108
+
1109
+ async levelUp() {
1110
+ await super.levelUp();
1111
+ this.skillPoints += 1; // Gain 1 skill point per level
1112
+ }
1113
+
1114
+ async learnSkill(skill, cost = 1) {
1115
+ if(this.skillPoints < cost) {
1116
+ return {error: 'Not enough skill points'};
1117
+ }
1118
+ this.skillPoints -= cost;
1119
+ await this.addSkills([skill]);
1120
+ return {success: true};
1121
+ }
1122
+ }
1123
+ ```
1124
+
1125
+ ---
1126
+
1127
+ ## DEBUGGING LEVEL PROGRESSION
1128
+
1129
+ ### Check Current State
1130
+
1131
+ ```javascript
1132
+ console.log('=== ClassPath State ===');
1133
+ console.log('Key:', classPath.key);
1134
+ console.log('Current Level:', classPath.currentLevel);
1135
+ console.log('Current Label:', classPath.currentLabel);
1136
+ console.log('Current XP:', classPath.currentExp);
1137
+ console.log('Next Level XP:', classPath.getNextLevelExperience());
1138
+ console.log('Available Skills:', Object.keys(classPath.currentSkills));
1139
+ console.log('Total Levels:', Object.keys(classPath.levels).length);
1140
+ ```
1141
+
1142
+ ### Track Level Changes
1143
+
1144
+ ```javascript
1145
+ classPath.listenEvent(SkillsEvents.LEVEL_UP, async (cp) => {
1146
+ console.log('[LEVEL UP]', cp.currentLevel, '-', cp.currentLabel);
1147
+ console.log(' Skills:', Object.keys(cp.currentSkills));
1148
+ }, 'debug-level-up');
1149
+
1150
+ classPath.listenEvent(SkillsEvents.LEVEL_EXPERIENCE_ADDED, async (
1151
+ cp, xpAdded, newTotal, currentIdx, nextIdx, nextKey, nextLevel, nextXP, isLevelUp
1152
+ ) => {
1153
+ console.log('[XP GAIN]', `+${xpAdded}`, `(${newTotal}/${nextXP})`);
1154
+ if(isLevelUp) {
1155
+ console.log(' → LEVELED UP!');
1156
+ }
1157
+ }, 'debug-xp-gain');
1158
+ ```
1159
+
1160
+ ### Verify Modifier Application
1161
+
1162
+ ```javascript
1163
+ classPath.listenEvent(SkillsEvents.LEVEL_APPLY_MODIFIERS, async (cp) => {
1164
+ console.log('[MODIFIERS] Applying level', cp.currentLevel, 'modifiers');
1165
+ let level = cp.levels[cp.currentLevel];
1166
+ if(level && level.modifiers) {
1167
+ level.modifiers.forEach(mod => {
1168
+ console.log(` ${mod.propertyKey} ${mod.operation} ${mod.value}`);
1169
+ });
1170
+ }
1171
+ }, 'debug-modifiers');
1172
+ ```
1173
+
1174
+ ---
1175
+
1176
+ ## COMMON PITFALLS
1177
+
1178
+ ### ❌ PITFALL 1: Not Awaiting Level Operations
1179
+
1180
+ ```javascript
1181
+ // BAD
1182
+ classPath.levelUp(); // Missing await
1183
+ console.log(classPath.currentLevel); // May not be updated yet
1184
+
1185
+ // GOOD
1186
+ await classPath.levelUp();
1187
+ console.log(classPath.currentLevel); // Guaranteed updated
1188
+ ```
1189
+
1190
+ ---
1191
+
1192
+ ### ❌ PITFALL 2: Assuming Auto-Level-Up Without Flag
1193
+
1194
+ ```javascript
1195
+ // BAD
1196
+ let classPath = new ClassPath();
1197
+ await classPath.init({
1198
+ levels: levels,
1199
+ currentLevel: 1
1200
+ // increaseLevelsWithExperience not set (defaults to false)
1201
+ });
1202
+ await classPath.addExperience(1000);
1203
+ console.log(classPath.currentLevel); // Still 1! No auto-level-up
1204
+
1205
+ // GOOD
1206
+ await classPath.init({
1207
+ levels: levels,
1208
+ currentLevel: 1,
1209
+ increaseLevelsWithExperience: true // Enable auto-level-up
1210
+ });
1211
+ await classPath.addExperience(1000);
1212
+ console.log(classPath.currentLevel); // Leveled up correctly
1213
+ ```
1214
+
1215
+ ---
1216
+
1217
+ ### ❌ PITFALL 3: Modifying levels After Initialization
1218
+
1219
+ ```javascript
1220
+ // BAD
1221
+ await classPath.init({levels: levels});
1222
+ classPath.levels[20] = new Level({key: 20, requiredExperience: 10000});
1223
+ // LevelsByExperience not updated! Sorting broken!
1224
+
1225
+ // GOOD
1226
+ levels[20] = new Level({key: 20, requiredExperience: 10000});
1227
+ await classPath.init({levels: levels}); // Include new level in init
1228
+ ```
1229
+
1230
+ ---
1231
+
1232
+ ### ❌ PITFALL 4: Reusing Skill Instances Across Classes
1233
+
1234
+ ```javascript
1235
+ // BAD
1236
+ let sharedSkill = new Skill({owner: player});
1237
+ let warriorPath = new ClassPath({skillsByLevel: {1: [sharedSkill]}});
1238
+ let magePath = new ClassPath({skillsByLevel: {1: [sharedSkill]}});
1239
+ // Skill has single owner reference - conflicts!
1240
+
1241
+ // GOOD
1242
+ let warriorSkill = new Skill({owner: player, key: 'warrior-basic'});
1243
+ let mageSkill = new Skill({owner: player, key: 'mage-basic'});
1244
+ let warriorPath = new ClassPath({skillsByLevel: {1: [warriorSkill]}});
1245
+ let magePath = new ClassPath({skillsByLevel: {1: [mageSkill]}});
1246
+ ```
1247
+
1248
+ ---
1249
+
1250
+ ## REFERENCES
1251
+
1252
+ - Level: `lib/level.js:9-33`
1253
+ - LevelsSet: `lib/levels-set.js:11-298`
1254
+ - ClassPath: `lib/class-path.js:11-315`
1255
+ - SkillsServer: `lib/server.js:11-85`
1256
+ - Sender: `lib/server/sender.js:11-212`
1257
+ - Event Names: `lib/skills-events.js`
1258
+ - Event System: `.claude/event-system-architecture.md`
1259
+ - Skill Execution: `.claude/skill-execution-flow.md`