@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,472 @@
1
+ # Architecture Overview
2
+
3
+ ## Package Structure
4
+
5
+ ```
6
+ @reldens/skills/
7
+ ├── lib/
8
+ │ ├── skill.js # Base Skill class
9
+ │ ├── level.js # Single Level class
10
+ │ ├── levels-set.js # Level progression system
11
+ │ ├── class-path.js # Class with skill tree
12
+ │ ├── server.js # Server-side wrapper
13
+ │ ├── constants.js # Shared constants
14
+ │ ├── skills-events.js # Event definitions
15
+ │ ├── server/
16
+ │ │ └── sender.js # Server-to-client messages
17
+ │ ├── client/
18
+ │ │ └── receiver.js # Client message handler
19
+ │ └── types/
20
+ │ ├── attack.js # Damage-dealing skill
21
+ │ ├── effect.js # Modifier-applying skill
22
+ │ ├── physical-attack.js # Physics-enabled attack
23
+ │ ├── physical-effect.js # Physics-enabled effect
24
+ │ ├── physical-skill-runner.js # Physics execution helper
25
+ │ └── physical-properties-validator.js
26
+ ├── tests/
27
+ │ ├── run-tests.js # Test runner
28
+ │ ├── utils/ # Test utilities
29
+ │ ├── fixtures/ # Test data and mocks
30
+ │ └── unit/ # Unit tests
31
+ ├── .claude/
32
+ │ ├── settings.json # Claude permissions
33
+ │ ├── instructions.md # Development workflow
34
+ │ ├── testing-guide.md # Testing documentation
35
+ │ └── architecture.md # This file
36
+ ├── index.js # Main export
37
+ ├── package.json # Package metadata
38
+ └── CLAUDE.md # Package documentation
39
+ ```
40
+
41
+ ## Core Classes
42
+
43
+ ### Inheritance Hierarchy
44
+
45
+ ```
46
+ Skill (base class)
47
+ ├── Attack (damage calculations)
48
+ │ └── PhysicalAttack (physics-enabled)
49
+ └── Effect (modifier application)
50
+ └── PhysicalEffect (physics-enabled)
51
+
52
+ LevelsSet (experience and progression)
53
+ └── ClassPath (skill tree system)
54
+ └── SkillsServer (server wrapper)
55
+ ```
56
+
57
+ ## Data Flow
58
+
59
+ ### Skill Execution Flow
60
+
61
+ ```
62
+ 1. Client Request
63
+ └→ Player triggers skill
64
+
65
+ 2. Validation Phase
66
+ ├→ skill.validate()
67
+ │ ├→ Check isReady
68
+ │ ├→ Check canActivate
69
+ │ ├→ Check isCasting
70
+ │ ├→ Check usesLimit
71
+ │ └→ validateConditions()
72
+ │
73
+ └→ skill.execute(target)
74
+ ├→ Fire SKILL_BEFORE_EXECUTE
75
+ ├→ Check target existence
76
+ ├→ onExecuteConditions() (custom)
77
+ ├→ isValidRange(target)
78
+ ├→ applyModifiers (owner effects)
79
+ └→ Fire SKILL_APPLY_OWNER_EFFECTS
80
+
81
+ 3. Cast Time Handling
82
+ ├→ If castTime > 0:
83
+ │ ├→ Fire SKILL_BEFORE_CAST
84
+ │ ├→ Set owner.isCasting = true
85
+ │ ├→ setTimeout(castTime)
86
+ │ └→ Fire SKILL_AFTER_CAST
87
+ └→ Else: Execute immediately
88
+
89
+ 4. Skill Logic Execution
90
+ ├→ Fire SKILL_BEFORE_RUN_LOGIC
91
+ ├→ runSkillLogic() (class-specific)
92
+ │ ├→ Attack: applyDamageTo()
93
+ │ │ ├→ Calculate aim vs dodge
94
+ │ │ ├→ Check full dodge
95
+ │ │ ├→ Calculate damage (atk vs def)
96
+ │ │ ├→ Apply critical damage
97
+ │ │ └→ Fire SKILL_ATTACK_APPLY_DAMAGE
98
+ │ │
99
+ │ └→ Effect: applyModifiers()
100
+ │ ├→ Apply targetEffects[]
101
+ │ └→ Fire SKILL_EFFECT_TARGET_MODIFIERS
102
+ │
103
+ └→ Fire SKILL_AFTER_RUN_LOGIC
104
+
105
+ 5. Completion
106
+ ├→ Increment skill.uses
107
+ ├→ onExecuteRewards() (custom)
108
+ └→ Fire SKILL_AFTER_EXECUTE
109
+
110
+ 6. Server Communication (if SkillsServer)
111
+ └→ Sender broadcasts to clients
112
+ ```
113
+
114
+ ### Level Progression Flow
115
+
116
+ ```
117
+ 1. Experience Gain
118
+ └→ levelsSet.addExperience(amount)
119
+ ├→ newTotalExp = currentExp + amount
120
+ ├→ Check if threshold reached
121
+ └→ Fire LEVEL_EXPERIENCE_ADDED
122
+
123
+ 2. Auto Level Up (if enabled)
124
+ └→ levelsSet.levelUp()
125
+ ├→ currentLevel++
126
+ ├→ applyLevelModifiers()
127
+ │ ├→ Get level instance
128
+ │ └→ Apply modifiers to owner
129
+ └→ Fire LEVEL_UP
130
+
131
+ 3. Server Notification (if SkillsServer)
132
+ └→ Sender.onLevelUp()
133
+ └→ Send/Broadcast level data
134
+ ```
135
+
136
+ ### Class Path Initialization
137
+
138
+ ```
139
+ 1. Construction
140
+ └→ new ClassPath(props)
141
+ ├→ Extends LevelsSet
142
+ ├→ Set key, label, labelsByLevel
143
+ ├→ Set skillsByLevel
144
+ └→ Initialize currentSkills
145
+
146
+ 2. Initialization
147
+ └→ classPath.init(props)
148
+ ├→ Call parent LevelsSet.init()
149
+ ├→ Fire INIT_CLASS_PATH_END
150
+ └→ setOwnerSkills() (populate based on level)
151
+
152
+ 3. Level Changes
153
+ └→ Override levelUp()
154
+ ├→ Call parent LevelsSet.levelUp()
155
+ ├→ Update currentLabel
156
+ ├→ addSkills() (new level skills)
157
+ └→ Fire ADD_SKILLS_AFTER
158
+
159
+ └→ Override levelDown()
160
+ ├→ removeSkills() (reverted level)
161
+ ├→ Call parent LevelsSet.levelDown()
162
+ └→ Fire REMOVE_SKILLS_AFTER
163
+ ```
164
+
165
+ ## Event System
166
+
167
+ ### Event Namespacing
168
+
169
+ All events are automatically namespaced by owner:
170
+
171
+ ```javascript
172
+ // Event pattern
173
+ ownerEventKey.reldens.skills.eventName
174
+
175
+ // Example
176
+ skills.ownerId.player-123.reldens.skills.levelUp
177
+ ```
178
+
179
+ ### Event Categories
180
+
181
+ 1. **Validation Events**
182
+ - VALIDATE_BEFORE
183
+ - VALIDATE_SUCCESS
184
+ - VALIDATE_FAIL
185
+
186
+ 2. **Execution Events**
187
+ - SKILL_BEFORE_EXECUTE
188
+ - SKILL_AFTER_EXECUTE
189
+ - SKILL_BEFORE_RUN_LOGIC
190
+ - SKILL_AFTER_RUN_LOGIC
191
+
192
+ 3. **Cast Events**
193
+ - SKILL_BEFORE_CAST
194
+ - SKILL_AFTER_CAST
195
+
196
+ 4. **Combat Events**
197
+ - SKILL_ATTACK_APPLY_DAMAGE
198
+ - SKILL_EFFECT_TARGET_MODIFIERS
199
+ - SKILL_PHYSICAL_ATTACK_HIT
200
+ - SKILL_PHYSICAL_EFFECT_HIT
201
+
202
+ 5. **Progression Events**
203
+ - LEVEL_UP
204
+ - LEVEL_DOWN
205
+ - LEVEL_EXPERIENCE_ADDED
206
+ - LEVEL_APPLY_MODIFIERS
207
+
208
+ 6. **Class Path Events**
209
+ - INIT_CLASS_PATH_END
210
+ - SET_SKILLS
211
+ - ADD_SKILLS_BEFORE/AFTER
212
+ - REMOVE_SKILLS_BEFORE/AFTER
213
+
214
+ ## Property Management
215
+
216
+ ### Property Paths
217
+
218
+ Properties use path notation for nested access:
219
+
220
+ ```javascript
221
+ // Flat property
222
+ propertyKey: 'hp'
223
+ // Accesses: owner.hp
224
+
225
+ // Nested property
226
+ propertyKey: 'stats/hp'
227
+ // Accesses: owner.stats.hp
228
+
229
+ // Deep nesting
230
+ propertyKey: 'stats/power/magical'
231
+ // Accesses: owner.stats.power.magical
232
+ ```
233
+
234
+ ### Property Manager Usage
235
+
236
+ ```javascript
237
+ // Get property value
238
+ let hp = this.propertyManager.getPropertyValue(owner, 'stats/hp');
239
+
240
+ // Set property value
241
+ this.propertyManager.setOwnerProperty(owner, 'stats/hp', 90);
242
+ ```
243
+
244
+ ## Modifier Integration
245
+
246
+ ### Modifier Application
247
+
248
+ Skills use modifiers from `@reldens/modifiers` package:
249
+
250
+ ```javascript
251
+ const { Modifier, ModifierConst } = require('@reldens/modifiers');
252
+
253
+ // Create modifier
254
+ let modifier = new Modifier({
255
+ key: 'atk-boost',
256
+ propertyKey: 'stats/atk',
257
+ operation: ModifierConst.OPS.INC,
258
+ value: 5
259
+ });
260
+
261
+ // Apply to owner
262
+ modifier.apply(owner);
263
+
264
+ // Revert from owner
265
+ modifier.revert(owner);
266
+ ```
267
+
268
+ ### Owner vs Target Effects
269
+
270
+ ```javascript
271
+ // Owner effects: Applied when skill executes
272
+ ownerEffects: [hpCostModifier, manaCostModifier]
273
+
274
+ // Target effects: Applied to target on hit
275
+ targetEffects: [damageModifier, stunModifier]
276
+ ```
277
+
278
+ ## Network Communication
279
+
280
+ ### Sender Pattern (Server)
281
+
282
+ ```javascript
283
+ // Server broadcasts skill events
284
+ sender.onSkillBeforeCast(skill, target)
285
+ └→ client.broadcast({
286
+ act: SkillsConst.ACTION_SKILL_BEFORE_CAST,
287
+ owner: ownerId,
288
+ data: {key, target}
289
+ })
290
+ ```
291
+
292
+ ### Receiver Pattern (Client)
293
+
294
+ ```javascript
295
+ // Client receives and processes
296
+ receiver.processMessage(message)
297
+ └→ If action matches:
298
+ └→ Call mapped method
299
+ └→ this.onSkillBeforeCast(message)
300
+ ```
301
+
302
+ ### Message Format
303
+
304
+ ```javascript
305
+ {
306
+ act: 'rski.ICpe', // Action constant
307
+ owner: 'player-123', // Owner ID
308
+ data: { // Compressed data
309
+ lvl: 5, // Level
310
+ lab: 'Warrior', // Label
311
+ exp: 1500, // Experience
312
+ ne: 2000, // Next level XP
313
+ skl: ['sword'] // Skills
314
+ }
315
+ }
316
+ ```
317
+
318
+ ## Critical Calculation Flows
319
+
320
+ ### Damage Calculation
321
+
322
+ ```
323
+ 1. Get Properties Totals
324
+ ├→ ownerAtk = sum(attackProperties)
325
+ ├→ targetDef = sum(defenseProperties)
326
+ ├→ ownerAim = sum(aimProperties)
327
+ └→ targetDodge = sum(dodgeProperties)
328
+
329
+ 2. Dodge Check
330
+ ├→ If dodgeFullEnabled && dodge > (aim * dodgeOverAimSuccess):
331
+ └→ Return false (dodged)
332
+
333
+ 3. Base Damage
334
+ ├→ If applyDirectDamage:
335
+ │ └→ damage = hitDamage
336
+ └→ Else:
337
+ └→ damage = calculateProportionDamage()
338
+
339
+ 4. Attack vs Defense
340
+ ├→ diff = ownerAtk - targetDef
341
+ ├→ If diff > 0: Increase damage by percentage
342
+ └→ If diff < 0: Decrease damage by percentage
343
+
344
+ 5. Dodge Proportion (if damageAffected)
345
+ ├→ dodgeAimDiff = getDiffProportion(aim, dodge)
346
+ └→ damage = damage - (damage * dodgeAimDiff / 100)
347
+
348
+ 6. Critical Damage
349
+ ├→ critDamage = getCriticalDiff(damage)
350
+ ├→ If criticalAffected && dodge > aim:
351
+ │ └→ Reduce critDamage by dodge proportion
352
+ └→ damage = damage + critDamage
353
+
354
+ 7. Apply to Target
355
+ └→ newHp = currentHp - damage
356
+ ```
357
+
358
+ ### Experience-Based Leveling
359
+
360
+ ```
361
+ 1. Check Experience
362
+ └→ If newExp >= nextLevel.requiredExperience:
363
+
364
+ 2. Level Up Loop
365
+ └→ For each level in levelsByExperience:
366
+ ├→ If newExp >= level.requiredExperience:
367
+ │ └→ levelUp()
368
+ └→ Else: break
369
+
370
+ 3. Apply Modifiers
371
+ └→ For each modifier in level.modifiers:
372
+ └→ modifier.apply(owner)
373
+ ```
374
+
375
+ ## Design Patterns
376
+
377
+ ### Strategy Pattern
378
+
379
+ Different skill types implement the same interface:
380
+
381
+ ```javascript
382
+ class Skill {
383
+ async runSkillLogic() { /* base implementation */ }
384
+ }
385
+
386
+ class Attack extends Skill {
387
+ async runSkillLogic() { /* damage logic */ }
388
+ }
389
+
390
+ class Effect extends Skill {
391
+ async runSkillLogic() { /* modifier logic */ }
392
+ }
393
+ ```
394
+
395
+ ### Observer Pattern
396
+
397
+ Event system allows loose coupling:
398
+
399
+ ```javascript
400
+ // Register listener
401
+ skill.listenEvent(SkillsEvents.LEVEL_UP, callback);
402
+
403
+ // Fire event
404
+ skill.fireEvent(SkillsEvents.LEVEL_UP, data);
405
+ ```
406
+
407
+ ### Template Method Pattern
408
+
409
+ Base class defines workflow, subclasses implement steps:
410
+
411
+ ```javascript
412
+ // Base workflow in Skill.execute()
413
+ async execute(target) {
414
+ await this.fireEvent(SKILL_BEFORE_EXECUTE);
415
+ // ... validation ...
416
+ await this.runSkillLogic(); // Implemented by subclass
417
+ await this.fireEvent(SKILL_AFTER_EXECUTE);
418
+ }
419
+ ```
420
+
421
+ ## Performance Considerations
422
+
423
+ 1. **Event Listeners**: Always remove listeners when owner is destroyed
424
+ 2. **Timers**: Clear skillActivationTimer and castingTimer properly
425
+ 3. **Object Pooling**: Consider pooling for frequently created skills
426
+ 4. **Property Caching**: Cache getPropertyValue results if called multiple times
427
+ 5. **Modifier Management**: Limit number of active modifiers per entity
428
+ 6. **Range Validation**: Use squared distance to avoid Math.sqrt when possible
429
+
430
+ ## Extension Points
431
+
432
+ ### Custom Skill Types
433
+
434
+ ```javascript
435
+ class MyCustomSkill extends Skill {
436
+ constructor(props) {
437
+ super(props);
438
+ this.customProperty = props.customProperty;
439
+ }
440
+
441
+ async runSkillLogic() {
442
+ // Custom implementation
443
+ }
444
+
445
+ onExecuteConditions() {
446
+ // Custom validation
447
+ }
448
+ }
449
+ ```
450
+
451
+ ### Custom Level Progression
452
+
453
+ ```javascript
454
+ class CustomLevelsSet extends LevelsSet {
455
+ async addExperience(number) {
456
+ // Custom XP calculation
457
+ let modifiedXp = this.calculateBonus(number);
458
+ return await super.addExperience(modifiedXp);
459
+ }
460
+ }
461
+ ```
462
+
463
+ ### Event Hooks
464
+
465
+ ```javascript
466
+ // Hook into any event for custom logic
467
+ skill.listenEvent(SkillsEvents.SKILL_AFTER_EXECUTE, async (skill, target) => {
468
+ // Award achievement
469
+ // Play animation
470
+ // Update statistics
471
+ });
472
+ ```