@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,982 @@
1
+ # CLASS HIERARCHY AND RELATIONSHIPS
2
+ ## Complete Architecture Reference
3
+
4
+ ---
5
+
6
+ ## OVERVIEW
7
+
8
+ This document provides a comprehensive view of the @reldens/skills package architecture, including class inheritance, composition relationships, dependencies, and integration patterns.
9
+
10
+ ---
11
+
12
+ ## CLASS INHERITANCE HIERARCHY
13
+
14
+ ```
15
+ EventsManagerSingleton (from @reldens/utils)
16
+ ↓
17
+ ├── Level (standalone)
18
+ │
19
+ ├── LevelsSet
20
+ │ ├── init()
21
+ │ ├── levelUp()
22
+ │ ├── levelDown()
23
+ │ ├── addExperience()
24
+ │ └── applyLevelModifiers()
25
+ │ ↓
26
+ │ ClassPath extends LevelsSet
27
+ │ ├── (inherits all LevelsSet methods)
28
+ │ ├── setOwnerSkills()
29
+ │ ├── addSkills()
30
+ │ ├── removeSkills()
31
+ │ └── levelUp() [overridden]
32
+ │ ↓
33
+ │ SkillsServer extends ClassPath
34
+ │ ├── (inherits all ClassPath methods)
35
+ │ └── constructor() [creates Sender]
36
+ │
37
+ └── Skill
38
+ ├── execute()
39
+ ├── validate()
40
+ ├── runSkillLogic() [abstract]
41
+ ├── applyModifiers()
42
+ └── getCriticalDiff()
43
+ ↓
44
+ Attack extends Skill
45
+ ├── (inherits all Skill methods)
46
+ └── runSkillLogic() [damage calculation]
47
+ ↓
48
+ PhysicalAttack extends Attack
49
+ ├── (inherits all Attack methods)
50
+ └── runSkillLogic() [physics-based damage]
51
+
52
+ Effect extends Skill
53
+ ├── (inherits all Skill methods)
54
+ └── runSkillLogic() [modifier application]
55
+ ↓
56
+ PhysicalEffect extends Effect
57
+ ├── (inherits all Effect methods)
58
+ └── runSkillLogic() [physics-based effects]
59
+ ```
60
+
61
+ ---
62
+
63
+ ## CLASS DETAILS
64
+
65
+ ### Level (lib/level.js)
66
+
67
+ **Type:** Data Container
68
+ **Extends:** None
69
+ **Dependencies:**
70
+ - @reldens/utils: `sc` (Shortcuts)
71
+
72
+ **Properties:**
73
+ ```javascript
74
+ {
75
+ key: number, // Level number (integer)
76
+ label: string, // Display name
77
+ requiredExperience: number, // Total XP needed
78
+ modifiers: Array<Modifier> // @reldens/modifiers instances
79
+ }
80
+ ```
81
+
82
+ **Purpose:** Represents a single level with associated modifiers and XP requirement.
83
+
84
+ **Relationships:**
85
+ - **Used by:** LevelsSet, ClassPath
86
+ - **Contains:** Modifier instances (from @reldens/modifiers)
87
+
88
+ ---
89
+
90
+ ### LevelsSet (lib/levels-set.js)
91
+
92
+ **Type:** Base Class
93
+ **Extends:** None (uses EventsManagerSingleton)
94
+ **Dependencies:**
95
+ - @reldens/utils: `sc`, `EventsManagerSingleton`
96
+ - @reldens/modifiers: (indirectly through Level modifiers)
97
+
98
+ **Properties:**
99
+ ```javascript
100
+ {
101
+ owner: Entity, // Entity with getPosition()
102
+ key: string, // LevelsSet identifier
103
+ levels: Object<Level>, // Level instances by key
104
+ currentLevel: number, // Current level number
105
+ currentExp: number, // Current experience
106
+ autoFillRanges: boolean, // Auto-generate levels
107
+ increaseLevelsWithExperience: boolean, // Auto level-up
108
+ events: EventsManager, // Event system instance
109
+ previousLevel: Level // Last level for modifier reversion
110
+ }
111
+ ```
112
+
113
+ **Methods:**
114
+ ```javascript
115
+ // Initialization
116
+ async init(props)
117
+
118
+ // Level Management
119
+ async levelUp()
120
+ async levelDown()
121
+ async applyLevelModifiers()
122
+
123
+ // Experience Management
124
+ async addExperience(number)
125
+ getNextLevelExperience()
126
+
127
+ // Level Configuration
128
+ async setLevels(levels)
129
+ autoFillLevelRanges(levels)
130
+
131
+ // Event System
132
+ async fireEvent(eventName, ...args)
133
+ listenEvent(eventName, callback, removeKey, masterKey)
134
+ eventFullName(eventName)
135
+ getOwnerEventKey()
136
+ ```
137
+
138
+ **Purpose:** Manages level progression, experience tracking, and modifier application.
139
+
140
+ **Relationships:**
141
+ - **Contains:** Level instances
142
+ - **Extended by:** ClassPath
143
+ - **Used by:** SkillsServer (via ClassPath)
144
+
145
+ ---
146
+
147
+ ### ClassPath (lib/class-path.js)
148
+
149
+ **Type:** Extended Class
150
+ **Extends:** LevelsSet
151
+ **Dependencies:**
152
+ - Same as LevelsSet
153
+ - Skill instances
154
+
155
+ **Additional Properties:**
156
+ ```javascript
157
+ {
158
+ label: string, // Base class label
159
+ currentLabel: string, // Active label
160
+ labelsByLevel: Object<string>, // Level-specific labels
161
+ skillsByLevel: Object<Array<Skill>>, // Skills by level
162
+ skillsByLevelKeys: Object<Array<string>>, // Skill keys by level
163
+ currentSkills: Object<Skill>, // Available skills
164
+ affectedProperty: string // Property for skills
165
+ }
166
+ ```
167
+
168
+ **Additional Methods:**
169
+ ```javascript
170
+ // Skill Management
171
+ async setOwnerSkills(skills)
172
+ async addSkills(skills)
173
+ async removeSkills(skills)
174
+
175
+ // Label Management
176
+ updateLabelByLevel()
177
+
178
+ // Overridden
179
+ async levelUp() // Extended with skill unlocking
180
+ ```
181
+
182
+ **Purpose:** Extends LevelsSet with skill trees and class-specific progression.
183
+
184
+ **Relationships:**
185
+ - **Extends:** LevelsSet
186
+ - **Contains:** Skill instances
187
+ - **Extended by:** SkillsServer
188
+ - **Uses:** Sender (in SkillsServer)
189
+
190
+ ---
191
+
192
+ ### SkillsServer (lib/server.js)
193
+
194
+ **Type:** Server Wrapper
195
+ **Extends:** ClassPath
196
+ **Dependencies:**
197
+ - Same as ClassPath
198
+ - Sender instance
199
+
200
+ **Additional Properties:**
201
+ ```javascript
202
+ {
203
+ client: Client, // Client with send() and broadcast()
204
+ sender: Sender // Message sender instance
205
+ }
206
+ ```
207
+
208
+ **Additional Methods:**
209
+ ```javascript
210
+ constructor(props) // Creates and initializes ClassPath + Sender
211
+ ```
212
+
213
+ **Purpose:** Server-side ClassPath wrapper with automatic client synchronization.
214
+
215
+ **Relationships:**
216
+ - **Extends:** ClassPath
217
+ - **Contains:** Sender instance
218
+ - **Requires:** Client object
219
+
220
+ ---
221
+
222
+ ### Skill (lib/skill.js)
223
+
224
+ **Type:** Base Class
225
+ **Extends:** None (uses EventsManagerSingleton)
226
+ **Dependencies:**
227
+ - @reldens/utils: `sc`, `EventsManagerSingleton`, `InteractionArea`
228
+ - @reldens/modifiers: `Condition`
229
+
230
+ **Properties:**
231
+ ```javascript
232
+ {
233
+ key: string, // Unique identifier
234
+ owner: Entity, // Entity with getPosition()
235
+ target: Entity, // Target entity
236
+ range: number, // Skill range (0 = infinite)
237
+ rangeAutomaticValidation: boolean, // Auto-validate range
238
+ allowSelfTarget: boolean, // Allow self-targeting
239
+ usesLimit: number, // Max uses (0 = unlimited)
240
+ usesCount: number, // Current use count
241
+ ownerConditions: Array<Condition>, // Owner validation conditions
242
+ ownerEffects: Array<Modifier>, // Effects applied to owner
243
+ skillDelay: number, // Cooldown in ms
244
+ canActivate: boolean, // Cooldown state
245
+ castTime: number, // Cast time in ms
246
+ criticalChance: number, // Critical probability (0-1)
247
+ criticalMultiplier: number, // Critical damage multiplier
248
+ criticalFixedValue: number, // Fixed critical bonus
249
+ lastAppliedModifiers: Object, // Last modifier results
250
+ events: EventsManager // Event system instance
251
+ }
252
+ ```
253
+
254
+ **Methods:**
255
+ ```javascript
256
+ // Execution
257
+ async execute(target)
258
+ async validate()
259
+ async runSkillLogic() // Abstract - override in subclasses
260
+
261
+ // Critical System
262
+ applyCriticalValue(value)
263
+ getCriticalDiff(value)
264
+ canCriticalHit()
265
+
266
+ // Modifier Application
267
+ applyModifiers(modifiersObjectList, target, avoidCritical)
268
+
269
+ // Hooks
270
+ onExecuteConditions() // Override for custom validation
271
+
272
+ // Event System
273
+ async fireEvent(eventName, ...args)
274
+ listenEvent(eventName, callback, removeKey, masterKey)
275
+ eventFullName(eventName)
276
+ getOwnerEventKey()
277
+ ```
278
+
279
+ **Purpose:** Base class for all skill types with validation, execution, and modifier systems.
280
+
281
+ **Relationships:**
282
+ - **Extended by:** Attack, Effect
283
+ - **Used by:** ClassPath (in skillsByLevel)
284
+ - **Requires:** Owner entity
285
+ - **Uses:** Condition, Modifier (from @reldens/modifiers)
286
+
287
+ ---
288
+
289
+ ### Attack (lib/types/attack.js)
290
+
291
+ **Type:** Skill Type
292
+ **Extends:** Skill
293
+ **Dependencies:** Same as Skill
294
+
295
+ **Additional Properties:**
296
+ ```javascript
297
+ {
298
+ affectedProperty: string, // Target property to damage
299
+ hitDamage: number, // Base damage at 100%
300
+ applyDirectDamage: boolean, // Skip calculations
301
+ attackProperties: Array<string>, // Owner attack properties
302
+ defenseProperties: Array<string>, // Target defense properties
303
+ aimProperties: Array<string>, // Owner aim properties
304
+ dodgeProperties: Array<string>, // Target dodge properties
305
+ dodgeFullEnabled: boolean, // Enable complete dodge
306
+ dodgeOverAimSuccess: number, // Dodge threshold multiplier
307
+ damageAffected: boolean, // Apply dodge/aim to damage
308
+ criticalAffected: boolean, // Apply dodge/aim to critical
309
+ propertiesTotalOperators: Object, // Custom operators for totals
310
+ allowEffectBelowZero: boolean // Allow negative values
311
+ }
312
+ ```
313
+
314
+ **Overridden Methods:**
315
+ ```javascript
316
+ async runSkillLogic() // Damage calculation and application
317
+ ```
318
+
319
+ **Purpose:** Damage-based skills with attack/defense and dodge/aim systems.
320
+
321
+ **Relationships:**
322
+ - **Extends:** Skill
323
+ - **Extended by:** PhysicalAttack
324
+ - **Used by:** ClassPath (as skill instance)
325
+
326
+ ---
327
+
328
+ ### Effect (lib/types/effect.js)
329
+
330
+ **Type:** Skill Type
331
+ **Extends:** Skill
332
+ **Dependencies:** Same as Skill
333
+
334
+ **Additional Properties:**
335
+ ```javascript
336
+ {
337
+ targetEffects: Array<Modifier> // Modifiers applied to target
338
+ }
339
+ ```
340
+
341
+ **Overridden Methods:**
342
+ ```javascript
343
+ async runSkillLogic() // Modifier application to target
344
+ ```
345
+
346
+ **Purpose:** Modifier-based skills (buffs/debuffs).
347
+
348
+ **Relationships:**
349
+ - **Extends:** Skill
350
+ - **Extended by:** PhysicalEffect
351
+ - **Used by:** ClassPath (as skill instance)
352
+
353
+ ---
354
+
355
+ ### PhysicalAttack (lib/types/physical-attack.js)
356
+
357
+ **Type:** Skill Type
358
+ **Extends:** Attack
359
+ **Dependencies:**
360
+ - Same as Attack
361
+ - PhysicalPropertiesValidator
362
+ - PhysicalSkillRunner
363
+
364
+ **Additional Properties:**
365
+ ```javascript
366
+ {
367
+ magnitude: number, // Physics force
368
+ objectWidth: number, // Collision body width
369
+ objectHeight: number, // Collision body height
370
+ validateTargetOnHit: boolean // Verify target on collision
371
+ }
372
+ ```
373
+
374
+ **Overridden Methods:**
375
+ ```javascript
376
+ async runSkillLogic() // Physics-based attack execution
377
+ ```
378
+
379
+ **Purpose:** Attack skills with physics/collision detection.
380
+
381
+ **Relationships:**
382
+ - **Extends:** Attack
383
+ - **Requires:** Owner implements `executePhysicalSkill()`
384
+ - **Uses:** PhysicalPropertiesValidator, PhysicalSkillRunner
385
+
386
+ ---
387
+
388
+ ### PhysicalEffect (lib/types/physical-effect.js)
389
+
390
+ **Type:** Skill Type
391
+ **Extends:** Effect
392
+ **Dependencies:**
393
+ - Same as Effect
394
+ - PhysicalPropertiesValidator
395
+ - PhysicalSkillRunner
396
+
397
+ **Additional Properties:**
398
+ ```javascript
399
+ {
400
+ magnitude: number, // Physics force
401
+ objectWidth: number, // Collision body width
402
+ objectHeight: number, // Collision body height
403
+ validateTargetOnHit: boolean // Verify target on collision
404
+ }
405
+ ```
406
+
407
+ **Overridden Methods:**
408
+ ```javascript
409
+ async runSkillLogic() // Physics-based effect execution
410
+ ```
411
+
412
+ **Purpose:** Effect skills with physics/collision detection.
413
+
414
+ **Relationships:**
415
+ - **Extends:** Effect
416
+ - **Requires:** Owner implements `executePhysicalSkill()`
417
+ - **Uses:** PhysicalPropertiesValidator, PhysicalSkillRunner
418
+
419
+ ---
420
+
421
+ ## COMPOSITION RELATIONSHIPS
422
+
423
+ ### LevelsSet Composition
424
+
425
+ ```
426
+ LevelsSet
427
+ ├── contains: Level[]
428
+ │ └── Level
429
+ │ └── contains: Modifier[] (from @reldens/modifiers)
430
+ │
431
+ └── uses: EventsManagerSingleton (from @reldens/utils)
432
+ ```
433
+
434
+ ### ClassPath Composition
435
+
436
+ ```
437
+ ClassPath (extends LevelsSet)
438
+ ├── inherits: LevelsSet composition
439
+ │
440
+ ├── contains: Skill[]
441
+ │ └── Skill (Attack, Effect, PhysicalAttack, PhysicalEffect)
442
+ │ ├── contains: Condition[] (from @reldens/modifiers)
443
+ │ └── contains: Modifier[] (from @reldens/modifiers)
444
+ │
445
+ └── skillsByLevel: {level: Skill[]}
446
+ ```
447
+
448
+ ### SkillsServer Composition
449
+
450
+ ```
451
+ SkillsServer (extends ClassPath)
452
+ ├── inherits: ClassPath composition
453
+ │
454
+ ├── contains: Sender
455
+ │ ├── listens to: ClassPath events
456
+ │ └── uses: Client (send/broadcast)
457
+ │
458
+ └── uses: Client
459
+ ```
460
+
461
+ ---
462
+
463
+ ## SERVER-CLIENT ARCHITECTURE
464
+
465
+ ```
466
+ ┌─────────────────────────────────────────────────────────────┐
467
+ │ SERVER SIDE │
468
+ ├─────────────────────────────────────────────────────────────┤
469
+ │ │
470
+ │ ┌───────────────┐ ┌──────────────┐ │
471
+ │ │ SkillsServer │───────▶│ ClassPath │ │
472
+ │ │ (wrapper) │ │ (progression)│ │
473
+ │ └───────┬───────┘ └──────┬───────┘ │
474
+ │ │ │ │
475
+ │ │ creates │ fires events │
476
+ │ │ │ │
477
+ │ ▼ ▼ │
478
+ │ ┌───────────────┐ ┌──────────────┐ │
479
+ │ │ Sender │◀───────│ Events │ │
480
+ │ │ (broadcaster) │listens │ Manager │ │
481
+ │ └───────┬───────┘ └──────────────┘ │
482
+ │ │ │
483
+ │ │ sends messages │
484
+ │ │ │
485
+ └──────────┼──────────────────────────────────────────────────┘
486
+ │
487
+ │ Network (WebSocket, etc.)
488
+ │
489
+ ┌──────────▼──────────────────────────────────────────────────┐
490
+ │ CLIENT SIDE │
491
+ ├─────────────────────────────────────────────────────────────┤
492
+ │ │
493
+ │ ┌───────────────┐ ┌──────────────┐ │
494
+ │ │ Receiver │───────▶│ UI/Game │ │
495
+ │ │ (processor) │updates │ Client │ │
496
+ │ └───────▲───────┘ └──────────────┘ │
497
+ │ │ │
498
+ │ │ receives messages │
499
+ │ │ │
500
+ └──────────┴──────────────────────────────────────────────────┘
501
+ ```
502
+
503
+ ### Message Flow Example:
504
+
505
+ ```
506
+ 1. SERVER: Player gains XP
507
+ ├─▶ SkillsServer.addExperience(500)
508
+ │ └─▶ ClassPath.addExperience(500)
509
+ │ └─▶ Fires LEVEL_EXPERIENCE_ADDED event
510
+ │
511
+ 2. SERVER: Sender catches event
512
+ ├─▶ Sender.sendExperienceData(classPath)
513
+ │ └─▶ client.send({act: 'rski.Ea', data: {exp: 500}})
514
+ │
515
+ 3. NETWORK: Message transmitted
516
+ │
517
+ 4. CLIENT: Receiver processes message
518
+ └─▶ Receiver.processMessage({act: 'rski.Ea', ...})
519
+ └─▶ Receiver.onLevelExperienceAdded(message)
520
+ └─▶ Update UI (XP bar, etc.)
521
+ ```
522
+
523
+ ---
524
+
525
+ ## EXTERNAL DEPENDENCIES
526
+
527
+ ### @reldens/utils
528
+
529
+ **Used by:** All classes
530
+
531
+ **Imports:**
532
+ - `sc` (Shortcuts): Property getters/setters, modifier application
533
+ - `EventsManagerSingleton`: Global event system
534
+ - `InteractionArea`: Range validation (used by Skill)
535
+ - `Logger`: Logging utility
536
+
537
+ **Key Methods Used:**
538
+ ```javascript
539
+ // Shortcuts
540
+ sc.get(object, path, defaultValue)
541
+ sc.hasOwn(object, property)
542
+ sc.applyModifier(target, modifier)
543
+ sc.revertModifier(target, modifier)
544
+
545
+ // EventsManager
546
+ EventsManagerSingleton.on(eventName, callback)
547
+ EventsManagerSingleton.onWithKey(eventName, callback, removeKey, masterKey)
548
+ EventsManagerSingleton.emit(eventName, ...args)
549
+ EventsManagerSingleton.removeAllListeners()
550
+
551
+ // InteractionArea
552
+ InteractionArea.isValidInteraction(area1, area2, distance)
553
+ ```
554
+
555
+ ---
556
+
557
+ ### @reldens/modifiers
558
+
559
+ **Used by:** Level, Skill, Attack, Effect
560
+
561
+ **Imports:**
562
+ - `Modifier`: Modifier instances for buffs/debuffs
563
+ - `Condition`: Validation conditions
564
+ - `PropertyManager`: Property management (indirect)
565
+ - `Calculator`: Modifier calculation (indirect)
566
+
567
+ **Key Patterns:**
568
+ ```javascript
569
+ // Creating modifiers
570
+ let modifier = new Modifier({
571
+ key: 'hp-buff',
572
+ propertyKey: 'stats.hp',
573
+ operation: '+',
574
+ value: 50
575
+ });
576
+
577
+ // Using modifiers in skills
578
+ modifier.target = target;
579
+ let newValue = modifier.getModifiedValue(); // Returns modified value
580
+ modifier.setOwnerProperty(modifier.propertyKey, newValue);
581
+
582
+ // Creating conditions
583
+ let condition = new Condition({
584
+ key: 'has-mana',
585
+ propertyKey: 'stats.mp',
586
+ operation: '>=',
587
+ value: 50
588
+ });
589
+
590
+ // Validating conditions
591
+ let isValid = condition.isValid(owner);
592
+ ```
593
+
594
+ ---
595
+
596
+ ## OWNER ENTITY REQUIREMENTS
597
+
598
+ ### Minimum Requirements for All Classes
599
+
600
+ **For LevelsSet / ClassPath:**
601
+
602
+ ```javascript
603
+ class MinimalOwner {
604
+ constructor() {
605
+ this.position = {x: 0, y: 0};
606
+ }
607
+
608
+ getPosition() {
609
+ return this.position;
610
+ }
611
+
612
+ // Required for event system
613
+ get eventsPrefix() {
614
+ return 'skills.ownerId.' + this.id;
615
+ }
616
+ }
617
+ ```
618
+
619
+ ---
620
+
621
+ ### Requirements for Skills
622
+
623
+ **Basic Skills:**
624
+
625
+ ```javascript
626
+ class SkillOwner extends MinimalOwner {
627
+ isInRange(skill, target, range) {
628
+ if(range === 0) return true;
629
+ let distance = this.getDistanceTo(target);
630
+ return distance <= range;
631
+ }
632
+
633
+ getDistanceTo(target) {
634
+ let dx = this.position.x - target.position.x;
635
+ let dy = this.position.y - target.position.y;
636
+ return Math.sqrt(dx * dx + dy * dy);
637
+ }
638
+ }
639
+ ```
640
+
641
+ ---
642
+
643
+ **Skills with Cast Time:**
644
+
645
+ ```javascript
646
+ class CastingOwner extends SkillOwner {
647
+ constructor() {
648
+ super();
649
+ this.isCasting = false; // Required for cast time
650
+ }
651
+ }
652
+ ```
653
+
654
+ ---
655
+
656
+ **Physical Skills:**
657
+
658
+ ```javascript
659
+ class PhysicalOwner extends CastingOwner {
660
+ async executePhysicalSkill(target, skill, executeOnHit) {
661
+ // Create physics body with skill.objectWidth, skill.objectHeight
662
+ let body = this.physicsEngine.createBody({
663
+ width: skill.objectWidth,
664
+ height: skill.objectHeight,
665
+ position: this.position
666
+ });
667
+
668
+ // Apply force/magnitude
669
+ body.applyForce(skill.magnitude, this.directionToTarget(target));
670
+
671
+ // Handle collision
672
+ body.onCollision((collidedEntity) => {
673
+ if(collidedEntity === target) {
674
+ executeOnHit(target);
675
+ }
676
+ });
677
+
678
+ return true;
679
+ }
680
+ }
681
+ ```
682
+
683
+ ---
684
+
685
+ ### Requirements for Client
686
+
687
+ **SkillsServer Client:**
688
+
689
+ ```javascript
690
+ class GameClient {
691
+ send(message) {
692
+ // Send message to this client only
693
+ this.connection.send(JSON.stringify(message));
694
+ }
695
+
696
+ broadcast(message) {
697
+ // Send message to all clients in room
698
+ this.room.broadcast(JSON.stringify(message));
699
+ }
700
+ }
701
+ ```
702
+
703
+ ---
704
+
705
+ ## INTEGRATION PATTERNS
706
+
707
+ ### Pattern #1: Basic Single-Class Setup
708
+
709
+ ```javascript
710
+ import {ClassPath} from '@reldens/skills/lib/class-path.js';
711
+ import {Level} from '@reldens/skills/lib/level.js';
712
+ import {Skill} from '@reldens/skills/lib/skill.js';
713
+
714
+ // Create levels
715
+ let levels = {
716
+ 1: new Level({key: 1, requiredExperience: 0}),
717
+ 5: new Level({key: 5, requiredExperience: 1000})
718
+ };
719
+
720
+ // Create skills
721
+ let skill1 = new Skill({key: 'basic', owner: player});
722
+ let skill2 = new Skill({key: 'advanced', owner: player});
723
+
724
+ // Initialize class path
725
+ let classPath = new ClassPath();
726
+ await classPath.init({
727
+ owner: player,
728
+ key: 'warrior',
729
+ levels: levels,
730
+ skillsByLevel: {
731
+ 1: [skill1],
732
+ 5: [skill2]
733
+ }
734
+ });
735
+ ```
736
+
737
+ ---
738
+
739
+ ### Pattern #2: Server-Side Multi-Class System
740
+
741
+ ```javascript
742
+ import {SkillsServer} from '@reldens/skills/lib/server.js';
743
+
744
+ class PlayerClassManager {
745
+ constructor(player, client) {
746
+ this.player = player;
747
+ this.client = client;
748
+ this.classes = {};
749
+ }
750
+
751
+ async createClass(key, config) {
752
+ this.classes[key] = new SkillsServer({
753
+ owner: this.player,
754
+ client: this.client,
755
+ key: key,
756
+ label: config.label,
757
+ levels: config.levels,
758
+ skillsByLevel: config.skillsByLevel
759
+ });
760
+ return this.classes[key];
761
+ }
762
+
763
+ async addXP(classKey, amount) {
764
+ if(!this.classes[classKey]) {
765
+ throw new Error('Class not found: ' + classKey);
766
+ }
767
+ await this.classes[classKey].addExperience(amount);
768
+ }
769
+
770
+ getClass(classKey) {
771
+ return this.classes[classKey];
772
+ }
773
+ }
774
+ ```
775
+
776
+ ---
777
+
778
+ ### Pattern #3: Client-Side Integration
779
+
780
+ ```javascript
781
+ import {Receiver} from '@reldens/skills/lib/client/receiver.js';
782
+
783
+ class SkillsUI extends Receiver {
784
+ constructor(owner) {
785
+ super({owner});
786
+ this.xpBar = document.getElementById('xp-bar');
787
+ this.levelDisplay = document.getElementById('level');
788
+ this.skillsContainer = document.getElementById('skills');
789
+ }
790
+
791
+ onLevelUp(message) {
792
+ // Update UI on level up
793
+ this.levelDisplay.textContent = message.data.lvl;
794
+ this.updateSkillsDisplay(message.data.skl);
795
+ this.showLevelUpAnimation();
796
+ }
797
+
798
+ onLevelExperienceAdded(message) {
799
+ // Update XP bar
800
+ let percentage = (message.data.exp / message.data.ne) * 100;
801
+ this.xpBar.style.width = percentage + '%';
802
+ }
803
+
804
+ updateSkillsDisplay(skillKeys) {
805
+ this.skillsContainer.innerHTML = '';
806
+ skillKeys.forEach(key => {
807
+ let skillButton = this.createSkillButton(key);
808
+ this.skillsContainer.appendChild(skillButton);
809
+ });
810
+ }
811
+ }
812
+
813
+ // Initialize
814
+ let skillsUI = new SkillsUI(player);
815
+ gameClient.onMessage('*', (message) => {
816
+ skillsUI.processMessage(message);
817
+ });
818
+ ```
819
+
820
+ ---
821
+
822
+ ### Pattern #4: Custom Skill Type
823
+
824
+ ```javascript
825
+ import {Skill} from '@reldens/skills/lib/skill.js';
826
+
827
+ class HealSkill extends Skill {
828
+ constructor(props) {
829
+ super(props);
830
+ this.healAmount = props.healAmount || 50;
831
+ this.affectedProperty = props.affectedProperty || 'hp';
832
+ }
833
+
834
+ async runSkillLogic() {
835
+ // Validate target
836
+ if(!this.target) {
837
+ return {error: 'TARGET_NOT_AVAILABLE'};
838
+ }
839
+
840
+ // Calculate heal (with critical)
841
+ let healAmount = this.healAmount;
842
+ healAmount = healAmount + this.getCriticalDiff(healAmount);
843
+
844
+ // Apply heal
845
+ let currentValue = sc.get(this.target, this.affectedProperty, 0);
846
+ let maxValue = sc.get(this.target, 'stats.maxHp', 100);
847
+ let newValue = Math.min(currentValue + healAmount, maxValue);
848
+
849
+ sc.set(this.target, this.affectedProperty, newValue);
850
+
851
+ // Fire custom event
852
+ await this.fireEvent('SKILL_HEAL_APPLIED', this, this.target, healAmount, newValue);
853
+
854
+ return {
855
+ healed: healAmount,
856
+ [this.affectedProperty]: newValue
857
+ };
858
+ }
859
+ }
860
+ ```
861
+
862
+ ---
863
+
864
+ ### Pattern #5: Persistent Storage Integration
865
+
866
+ ```javascript
867
+ class PersistentClassPath extends ClassPath {
868
+ async init(props) {
869
+ // Load from database
870
+ let savedData = await database.loadClassPath(props.owner.id, props.key);
871
+
872
+ if(savedData) {
873
+ // Restore saved state
874
+ props.currentLevel = savedData.currentLevel;
875
+ props.currentExp = savedData.currentExp;
876
+ }
877
+
878
+ await super.init(props);
879
+
880
+ // Listen for changes to save
881
+ this.listenEvent(SkillsEvents.LEVEL_UP, async (cp) => {
882
+ await this.save();
883
+ }, 'persistent-level-up');
884
+
885
+ this.listenEvent(SkillsEvents.LEVEL_EXPERIENCE_ADDED, async (cp) => {
886
+ await this.save();
887
+ }, 'persistent-xp-added');
888
+ }
889
+
890
+ async save() {
891
+ await database.saveClassPath(this.owner.id, this.key, {
892
+ currentLevel: this.currentLevel,
893
+ currentExp: this.currentExp,
894
+ currentSkills: Object.keys(this.currentSkills)
895
+ });
896
+ }
897
+ }
898
+ ```
899
+
900
+ ---
901
+
902
+ ## CLASS RESPONSIBILITY SUMMARY
903
+
904
+ | Class | Primary Responsibility | Key Methods | Events |
905
+ |-------|------------------------|-------------|--------|
906
+ | **Level** | Store level data | (constructor only) | None |
907
+ | **LevelsSet** | Manage level progression and XP | init, levelUp, addExperience | LEVEL_UP, LEVEL_EXPERIENCE_ADDED |
908
+ | **ClassPath** | Add skill trees to progression | setOwnerSkills, addSkills, removeSkills | ADD_SKILLS_*, REMOVE_SKILLS_* |
909
+ | **SkillsServer** | Server-client synchronization | (constructor) | (via Sender) |
910
+ | **Skill** | Base skill execution | execute, validate, applyModifiers | SKILL_BEFORE_EXECUTE, VALIDATE_* |
911
+ | **Attack** | Damage-based skills | runSkillLogic (damage calc) | SKILL_ATTACK_APPLY_DAMAGE |
912
+ | **Effect** | Modifier-based skills | runSkillLogic (modifiers) | SKILL_EFFECT_TARGET_MODIFIERS |
913
+ | **PhysicalAttack** | Physics-based attacks | runSkillLogic (physics) | SKILL_PHYSICAL_ATTACK_HIT |
914
+ | **PhysicalEffect** | Physics-based effects | runSkillLogic (physics) | SKILL_PHYSICAL_EFFECT_HIT |
915
+ | **Sender** | Broadcast server events to clients | register, send methods | (listens to ClassPath events) |
916
+ | **Receiver** | Process client messages | processMessage, on* methods | None |
917
+
918
+ ---
919
+
920
+ ## DEPENDENCY GRAPH
921
+
922
+ ```
923
+ ┌────────────────────────────────────────────────────────┐
924
+ │ EXTERNAL PACKAGES │
925
+ ├────────────────────────────────────────────────────────┤
926
+ │ @reldens/utils @reldens/modifiers │
927
+ │ ├─ Shortcuts (sc) ├─ Modifier │
928
+ │ ├─ EventsManagerSingleton├─ Condition │
929
+ │ ├─ InteractionArea └─ Calculator │
930
+ │ └─ Logger │
931
+ └────────┬──────────────────────────┬────────────────────┘
932
+ │ │
933
+ ▼ ▼
934
+ ┌─────────────────┐ ┌───────────────────┐
935
+ │ Level │◀───────│ LevelsSet │
936
+ │ (standalone) │contains│ (progression) │
937
+ └─────────────────┘ └─────────┬─────────┘
938
+ │ extends
939
+ ▼
940
+ ┌───────────────────┐
941
+ │ ClassPath │
942
+ │ (skill trees) │
943
+ └─────────┬─────────┘
944
+ │ extends
945
+ ▼
946
+ ┌───────────────────┐ ┌──────────┐
947
+ │ SkillsServer │◀───────│ Sender │
948
+ │ (server) │creates │(broadcast)│
949
+ └───────────────────┘ └──────────┘
950
+
951
+ ┌──────────┐ ┌────────────┐ ┌──────────────────┐
952
+ │ Skill │◀───────│ Attack │◀───────│ PhysicalAttack │
953
+ │ (base) │extends │ (damage) │extends │ (physics) │
954
+ └────┬─────┘ └────────────┘ └──────────────────┘
955
+ │ extends
956
+ ▼
957
+ ┌────────────┐ ┌──────────────────┐
958
+ │ Effect │◀───────│ PhysicalEffect │
959
+ │(modifiers) │extends │ (physics) │
960
+ └────────────┘ └──────────────────┘
961
+
962
+ ┌──────────┐
963
+ │ Receiver │
964
+ │ (client) │
965
+ └──────────┘
966
+ ```
967
+
968
+ ---
969
+
970
+ ## REFERENCES
971
+
972
+ - Level: `lib/level.js:9-33`
973
+ - LevelsSet: `lib/levels-set.js:11-298`
974
+ - ClassPath: `lib/class-path.js:11-315`
975
+ - SkillsServer: `lib/server.js:11-85`
976
+ - Skill: `lib/skill.js:12-348`
977
+ - Attack: `lib/types/attack.js:14-145`
978
+ - Effect: `lib/types/effect.js:14-70`
979
+ - PhysicalAttack: `lib/types/physical-attack.js:16-118`
980
+ - PhysicalEffect: `lib/types/physical-effect.js:16-116`
981
+ - Sender: `lib/server/sender.js:11-212`
982
+ - Receiver: `lib/client/receiver.js:10-73`