@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,979 @@
1
+ # SKILL EXECUTION FLOW
2
+ ## Complete Step-by-Step Guide
3
+
4
+ ---
5
+
6
+ ## OVERVIEW
7
+
8
+ This document provides a detailed walkthrough of skill execution from the moment a skill is triggered until all effects are applied and events fired. Understanding this flow is critical for debugging, extending functionality, and implementing custom skills.
9
+
10
+ ---
11
+
12
+ ## ENTRY POINTS
13
+
14
+ ### Method 1: Direct Execution
15
+ ```javascript
16
+ await skill.execute(target);
17
+ ```
18
+
19
+ ### Method 2: With Owner Execution Hook
20
+ ```javascript
21
+ // For physical skills, owner must implement this
22
+ await owner.executePhysicalSkill(target, skill);
23
+ ```
24
+
25
+ ---
26
+
27
+ ## COMPLETE EXECUTION FLOW
28
+
29
+ ### PHASE 1: PRE-VALIDATION
30
+
31
+ **File:** `lib/skill.js:106-125`
32
+
33
+ ```
34
+ 1. execute(target) called
35
+ 2. Set this.target = target
36
+ 3. Check if owner is casting (this.owner.isCasting)
37
+ → If true: return {error: SKILL.CAN_NOT_ACTIVATE}
38
+ 4. Fire SKILL_BEFORE_EXECUTE event
39
+ → Event params: (this, target)
40
+ 5. Continue to validation
41
+ ```
42
+
43
+ **Events Fired:**
44
+ - `SkillsEvents.SKILL_BEFORE_EXECUTE`
45
+
46
+ **Possible Returns:**
47
+ - `{error: SKILL.CAN_NOT_ACTIVATE}` - Owner is casting another skill
48
+
49
+ ---
50
+
51
+ ### PHASE 2: VALIDATION
52
+
53
+ **File:** `lib/skill.js:147-187`
54
+
55
+ ```
56
+ 1. validate() called
57
+ 2. Fire VALIDATE_BEFORE event
58
+ → Event params: (this)
59
+ 3. Check ownerConditions (if defined)
60
+ → For each condition in this.ownerConditions:
61
+ → condition.isValid(this.owner)
62
+ → If any fails:
63
+ → Fire VALIDATE_FAIL event with failedCondition
64
+ → Return false
65
+ 4. Check canActivate flag (cooldown/delay)
66
+ → If false: Return false
67
+ 5. Check range (if rangeAutomaticValidation enabled)
68
+ → Call this.owner.isInRange(this, this.target, this.range)
69
+ → Fire SKILL_BEFORE_IN_RANGE event
70
+ → Fire SKILL_AFTER_IN_RANGE event with result
71
+ → If out of range: Return false
72
+ 6. Call onExecuteConditions() (hook for custom validation)
73
+ → If returns false: Return false
74
+ 7. Set canActivate = false (start cooldown)
75
+ 8. Set skillActivationTimer for cooldown reset
76
+ 9. Fire VALIDATE_SUCCESS event
77
+ 10. Return true
78
+ ```
79
+
80
+ **Events Fired:**
81
+ - `SkillsEvents.VALIDATE_BEFORE`
82
+ - `SkillsEvents.VALIDATE_FAIL` (if condition fails)
83
+ - `SkillsEvents.SKILL_BEFORE_IN_RANGE` (if range check enabled)
84
+ - `SkillsEvents.SKILL_AFTER_IN_RANGE` (if range check enabled)
85
+ - `SkillsEvents.VALIDATE_SUCCESS` (if all checks pass)
86
+
87
+ **Possible Returns:**
88
+ - `false` - Validation failed (condition, range, cooldown)
89
+ - `true` - Validation passed, ready to execute
90
+
91
+ **Hooks:**
92
+ - `onExecuteConditions()` - Override for custom validation logic
93
+
94
+ ---
95
+
96
+ ### PHASE 3: OWNER EFFECTS APPLICATION
97
+
98
+ **File:** `lib/skill.js:126-128`
99
+
100
+ ```
101
+ 1. Check if this.ownerEffects exists and has length > 0
102
+ 2. If yes:
103
+ → Fire SKILL_APPLY_OWNER_EFFECTS event
104
+ → Event params: (this, target)
105
+ → Call applyModifiers(this.ownerEffects, this.owner, true)
106
+ → Note: avoidCritical = true (no crits on owner effects)
107
+ ```
108
+
109
+ **Events Fired:**
110
+ - `SkillsEvents.SKILL_APPLY_OWNER_EFFECTS`
111
+
112
+ **What Happens:**
113
+ - Modifiers in ownerEffects are applied to the skill owner
114
+ - Examples: Buff owner's attack, consume mana, apply shield
115
+ - Critical damage is NOT applied to owner effects
116
+
117
+ ---
118
+
119
+ ### PHASE 4: CAST TIME HANDLING
120
+
121
+ **File:** `lib/skill.js:129-134`
122
+
123
+ ```
124
+ 1. Check if this.castTime > 0
125
+ 2. If yes:
126
+ → Fire SKILL_BEFORE_CAST event
127
+ → Event params: (this, target)
128
+ → Set this.owner.isCasting = true
129
+ → await sleep(this.castTime)
130
+ → Set this.owner.isCasting = false
131
+ → Fire SKILL_AFTER_CAST event
132
+ → Event params: (this, target)
133
+ 3. Continue to skill logic
134
+ ```
135
+
136
+ **Events Fired:**
137
+ - `SkillsEvents.SKILL_BEFORE_CAST` (if castTime > 0)
138
+ - `SkillsEvents.SKILL_AFTER_CAST` (if castTime > 0)
139
+
140
+ **State Changes:**
141
+ - `owner.isCasting` set to true during cast
142
+ - `owner.isCasting` set to false after cast completes
143
+
144
+ **Blocking:**
145
+ - If owner is already casting, execute() returns early (PHASE 1)
146
+ - Cast time blocks thread with await sleep()
147
+
148
+ ---
149
+
150
+ ### PHASE 5: SKILL LOGIC EXECUTION
151
+
152
+ **File:** `lib/skill.js:135-137`
153
+
154
+ ```
155
+ 1. Fire SKILL_BEFORE_RUN_LOGIC event
156
+ → Event params: (this, target)
157
+ 2. await this.runSkillLogic()
158
+ → This is the main skill behavior method
159
+ → Overridden by skill types (Attack, Effect, Physical, etc.)
160
+ 3. Fire SKILL_AFTER_RUN_LOGIC event
161
+ → Event params: (this, target)
162
+ ```
163
+
164
+ **Events Fired:**
165
+ - `SkillsEvents.SKILL_BEFORE_RUN_LOGIC`
166
+ - `SkillsEvents.SKILL_AFTER_RUN_LOGIC`
167
+
168
+ **Hooks:**
169
+ - `runSkillLogic()` - MUST be overridden by skill types
170
+
171
+ ---
172
+
173
+ ### PHASE 6: POST-EXECUTION
174
+
175
+ **File:** `lib/skill.js:138-141`
176
+
177
+ ```
178
+ 1. Increment this.usesCount
179
+ 2. Fire SKILL_AFTER_EXECUTE event
180
+ → Event params: (this, target)
181
+ 3. Return result (varies by skill type)
182
+ ```
183
+
184
+ **Events Fired:**
185
+ - `SkillsEvents.SKILL_AFTER_EXECUTE`
186
+
187
+ **State Changes:**
188
+ - `usesCount` incremented
189
+ - If `usesLimit` reached, skill may become unavailable
190
+
191
+ ---
192
+
193
+ ## SKILL TYPE-SPECIFIC LOGIC
194
+
195
+ ### BASE SKILL (lib/skill.js)
196
+
197
+ **runSkillLogic():**
198
+ ```javascript
199
+ async runSkillLogic()
200
+ {
201
+ // No implementation in base class
202
+ // Must be overridden
203
+ return true;
204
+ }
205
+ ```
206
+
207
+ ---
208
+
209
+ ### ATTACK SKILL (lib/types/attack.js:69-143)
210
+
211
+ **runSkillLogic() Flow:**
212
+
213
+ ```
214
+ 1. Check if this.applyDirectDamage is true
215
+ → If true: Skip calculations, apply hitDamage directly
216
+ → If false: Continue to damage calculation
217
+
218
+ 2. DODGE CHECK:
219
+ → Calculate owner aim total (sum of aimProperties)
220
+ → Calculate target dodge total (sum of dodgeProperties)
221
+ → If dodgeFullEnabled:
222
+ → Check if dodge > (aim * dodgeOverAimSuccess)
223
+ → If true: Return {error: SKILL.DODGED}
224
+
225
+ 3. DAMAGE CALCULATION:
226
+ → Calculate attack total (sum of attackProperties)
227
+ → Calculate defense total (sum of defenseProperties)
228
+ → Base damage = hitDamage modified by attack-defense difference
229
+ → If damageAffected:
230
+ → Apply dodge/aim ratio to damage
231
+ → Calculate critical damage (if not avoided)
232
+ → If criticalAffected:
233
+ → Apply dodge/aim ratio to critical
234
+
235
+ 4. DAMAGE APPLICATION:
236
+ → Fire SKILL_ATTACK_APPLY_DAMAGE event
237
+ → Event params: (this, target, damage, newValue)
238
+ → Apply damage to target.stats[affectedProperty]
239
+ → If !allowEffectBelowZero:
240
+ → Clamp value to 0 minimum
241
+ → Update target property
242
+
243
+ 5. Return result with damage details
244
+ ```
245
+
246
+ **Events Fired:**
247
+ - `SkillsEvents.SKILL_ATTACK_APPLY_DAMAGE`
248
+
249
+ **Return Format:**
250
+ ```javascript
251
+ {
252
+ damages: {
253
+ [affectedProperty]: finalDamageValue
254
+ },
255
+ [affectedProperty]: target.stats[affectedProperty]
256
+ }
257
+ ```
258
+
259
+ **Critical Calculation:**
260
+ Attack skills apply critical to the damage value BEFORE adding to current:
261
+ ```javascript
262
+ // lib/types/attack.js:101
263
+ damage = damage + this.getCriticalDiff(damage);
264
+ ```
265
+
266
+ ---
267
+
268
+ ### EFFECT SKILL (lib/types/effect.js:46-68)
269
+
270
+ **runSkillLogic() Flow:**
271
+
272
+ ```
273
+ 1. Check if target is defined
274
+ → If not: Return {error: SKILL.TARGET_NOT_AVAILABLE}
275
+
276
+ 2. Validate range (if rangeAutomaticValidation)
277
+ → Check this.owner.isInRange(this, this.target, this.range)
278
+ → If out of range: Return {error: SKILL.OUT_OF_RANGE}
279
+
280
+ 3. Apply target effects:
281
+ → Call applyModifiers(this.targetEffects, this.target)
282
+ → Note: avoidCritical = false (crits can apply)
283
+
284
+ 4. Fire SKILL_EFFECT_TARGET_MODIFIERS event
285
+ → Event params: (this, this.target)
286
+
287
+ 5. Return success result
288
+ ```
289
+
290
+ **Events Fired:**
291
+ - `SkillsEvents.SKILL_EFFECT_TARGET_MODIFIERS`
292
+
293
+ **Return Format:**
294
+ ```javascript
295
+ {
296
+ error: false
297
+ }
298
+ ```
299
+
300
+ **Critical Calculation:**
301
+ Effect skills apply critical to modifier value BEFORE adding to current:
302
+ ```javascript
303
+ // lib/skill.js:306-308
304
+ let newValue = modifier.getModifiedValue();
305
+ if(!avoidCritical){
306
+ newValue = newValue + this.getCriticalDiff(modifier.value);
307
+ }
308
+ ```
309
+
310
+ ---
311
+
312
+ ### PHYSICAL ATTACK SKILL (lib/types/physical-attack.js:58-115)
313
+
314
+ **runSkillLogic() Flow:**
315
+
316
+ ```
317
+ 1. Validate physical properties (width, height, magnitude)
318
+ → If invalid: Return {error: SKILL.PHYSICAL_SKILL_INVALID_TARGET}
319
+
320
+ 2. Check if owner implements executePhysicalSkill()
321
+ → If not: Return {error: SKILL.TARGET_NOT_AVAILABLE}
322
+
323
+ 3. Set this.lastState = SKILL.PHYSICAL_SKILL_RUN_LOGIC
324
+
325
+ 4. Define executeOnHit callback:
326
+ → Validate target matches (if validateTargetOnHit)
327
+ → Fire SKILL_PHYSICAL_ATTACK_HIT event
328
+ → Event params: (this, target)
329
+ → Call parent runSkillLogic() (Attack damage logic)
330
+ → Return damage result
331
+
332
+ 5. Call owner.executePhysicalSkill(this.target, this, executeOnHit)
333
+ → Owner's physics system handles collision detection
334
+ → When collision occurs, executeOnHit is called
335
+
336
+ 6. Return {executed: true}
337
+ ```
338
+
339
+ **Events Fired:**
340
+ - `SkillsEvents.SKILL_PHYSICAL_ATTACK_HIT` (on collision)
341
+ - `SkillsEvents.SKILL_ATTACK_APPLY_DAMAGE` (from parent logic)
342
+
343
+ **Owner Requirements:**
344
+ Owner must implement:
345
+ ```javascript
346
+ async executePhysicalSkill(target, skill, executeOnHit)
347
+ {
348
+ // Create physics body with skill.objectWidth, skill.objectHeight
349
+ // Apply force with skill.magnitude
350
+ // On collision, call executeOnHit(collidedTarget)
351
+ }
352
+ ```
353
+
354
+ **Return Format:**
355
+ ```javascript
356
+ {
357
+ executed: true
358
+ }
359
+ ```
360
+
361
+ ---
362
+
363
+ ### PHYSICAL EFFECT SKILL (lib/types/physical-effect.js:58-113)
364
+
365
+ **runSkillLogic() Flow:**
366
+
367
+ ```
368
+ 1. Validate physical properties (width, height, magnitude)
369
+ → If invalid: Return {error: SKILL.PHYSICAL_SKILL_INVALID_TARGET}
370
+
371
+ 2. Check if owner implements executePhysicalSkill()
372
+ → If not: Return {error: SKILL.TARGET_NOT_AVAILABLE}
373
+
374
+ 3. Set this.lastState = SKILL.PHYSICAL_SKILL_RUN_LOGIC
375
+
376
+ 4. Define executeOnHit callback:
377
+ → Validate target matches (if validateTargetOnHit)
378
+ → Fire SKILL_PHYSICAL_EFFECT_HIT event
379
+ → Event params: (this, target)
380
+ → Call parent runSkillLogic() (Effect modifier logic)
381
+ → Return effect result
382
+
383
+ 5. Call owner.executePhysicalSkill(this.target, this, executeOnHit)
384
+ → Owner's physics system handles collision detection
385
+ → When collision occurs, executeOnHit is called
386
+
387
+ 6. Return {executed: true}
388
+ ```
389
+
390
+ **Events Fired:**
391
+ - `SkillsEvents.SKILL_PHYSICAL_EFFECT_HIT` (on collision)
392
+ - `SkillsEvents.SKILL_EFFECT_TARGET_MODIFIERS` (from parent logic)
393
+
394
+ **Owner Requirements:**
395
+ Same as PhysicalAttack - must implement executePhysicalSkill()
396
+
397
+ **Return Format:**
398
+ ```javascript
399
+ {
400
+ executed: true
401
+ }
402
+ ```
403
+
404
+ ---
405
+
406
+ ## MODIFIER APPLICATION FLOW
407
+
408
+ ### applyModifiers() Method
409
+
410
+ **File:** `lib/skill.js:293-313`
411
+
412
+ ```
413
+ 1. Initialize this.lastAppliedModifiers = {}
414
+ 2. For each modifier in modifiersObjectList:
415
+ → Set modifier.target = target
416
+ → Call modifier.getModifiedValue()
417
+ → This uses @reldens/modifiers Calculator
418
+ → Returns currentValue + modifierValue
419
+ → If !avoidCritical:
420
+ → Calculate critical bonus: getCriticalDiff(modifier.value)
421
+ → Add critical bonus to newValue
422
+ → Apply newValue to target property
423
+ → Store in lastAppliedModifiers
424
+ ```
425
+
426
+ **Critical Calculation:**
427
+ ```javascript
428
+ // Critical applies ONLY to modifier.value, not to currentValue
429
+ getCriticalDiff(value)
430
+ {
431
+ let criticalValue = this.applyCriticalValue(value);
432
+ return criticalValue - value; // Returns the bonus amount
433
+ }
434
+
435
+ // Example:
436
+ // currentValue = 80, modifier.value = 10, critical = 2x
437
+ // getModifiedValue() returns 90 (80 + 10)
438
+ // getCriticalDiff(10) returns 10 (20 - 10)
439
+ // Final: 90 + 10 = 100
440
+ ```
441
+
442
+ **Important:**
443
+ - Owner effects ALWAYS use avoidCritical = true
444
+ - Target effects use avoidCritical = false (can crit)
445
+
446
+ ---
447
+
448
+ ## COMPLETE SEQUENCE DIAGRAM
449
+
450
+ ```
451
+ ┌──────────────────────────────────────────────────────────────┐
452
+ │ skill.execute(target) CALLED │
453
+ └────────────────────┬─────────────────────────────────────────┘
454
+ │
455
+ ▼
456
+ ╔════════════════════════╗
457
+ ║ PHASE 1: PRE-VALIDATION ║
458
+ ╚════════════════════════╝
459
+ │
460
+ ├─→ Check owner.isCasting
461
+ │ └─→ If true: Return {error: CAN_NOT_ACTIVATE}
462
+ │
463
+ ├─→ Fire: SKILL_BEFORE_EXECUTE
464
+ │
465
+ ▼
466
+ ╔════════════════════════╗
467
+ ║ PHASE 2: VALIDATION ║
468
+ ╚════════════════════════╝
469
+ │
470
+ ├─→ Fire: VALIDATE_BEFORE
471
+ │
472
+ ├─→ Check ownerConditions
473
+ │ └─→ If fails: Fire VALIDATE_FAIL, Return false
474
+ │
475
+ ├─→ Check canActivate (cooldown)
476
+ │ └─→ If false: Return false
477
+ │
478
+ ├─→ Check range (if enabled)
479
+ │ ├─→ Fire: SKILL_BEFORE_IN_RANGE
480
+ │ ├─→ Fire: SKILL_AFTER_IN_RANGE
481
+ │ └─→ If out of range: Return false
482
+ │
483
+ ├─→ Call onExecuteConditions()
484
+ │ └─→ If false: Return false
485
+ │
486
+ ├─→ Set canActivate = false
487
+ ├─→ Start skillActivationTimer
488
+ ├─→ Fire: VALIDATE_SUCCESS
489
+ │
490
+ ▼
491
+ ╔════════════════════════╗
492
+ ║ PHASE 3: OWNER EFFECTS ║
493
+ ╚════════════════════════╝
494
+ │
495
+ ├─→ If ownerEffects exist:
496
+ │ ├─→ Fire: SKILL_APPLY_OWNER_EFFECTS
497
+ │ └─→ applyModifiers(ownerEffects, owner, true)
498
+ │
499
+ ▼
500
+ ╔════════════════════════╗
501
+ ║ PHASE 4: CAST TIME ║
502
+ ╚════════════════════════╝
503
+ │
504
+ ├─→ If castTime > 0:
505
+ │ ├─→ Fire: SKILL_BEFORE_CAST
506
+ │ ├─→ Set owner.isCasting = true
507
+ │ ├─→ await sleep(castTime)
508
+ │ ├─→ Set owner.isCasting = false
509
+ │ └─→ Fire: SKILL_AFTER_CAST
510
+ │
511
+ ▼
512
+ ╔════════════════════════╗
513
+ ║ PHASE 5: SKILL LOGIC ║
514
+ ╚════════════════════════╝
515
+ │
516
+ ├─→ Fire: SKILL_BEFORE_RUN_LOGIC
517
+ │
518
+ ├─→ await runSkillLogic()
519
+ │ │
520
+ │ ├─→ [BASE SKILL]
521
+ │ │ └─→ (no implementation)
522
+ │ │
523
+ │ ├─→ [ATTACK SKILL]
524
+ │ │ ├─→ Check dodge
525
+ │ │ ├─→ Calculate damage
526
+ │ │ ├─→ Apply critical
527
+ │ │ ├─→ Fire: SKILL_ATTACK_APPLY_DAMAGE
528
+ │ │ └─→ Apply to affectedProperty
529
+ │ │
530
+ │ ├─→ [EFFECT SKILL]
531
+ │ │ ├─→ Validate range
532
+ │ │ ├─→ applyModifiers(targetEffects, target)
533
+ │ │ └─→ Fire: SKILL_EFFECT_TARGET_MODIFIERS
534
+ │ │
535
+ │ ├─→ [PHYSICAL ATTACK]
536
+ │ │ ├─→ Validate properties
537
+ │ │ ├─→ owner.executePhysicalSkill()
538
+ │ │ ├─→ On collision:
539
+ │ │ │ ├─→ Fire: SKILL_PHYSICAL_ATTACK_HIT
540
+ │ │ │ └─→ Call parent Attack logic
541
+ │ │ └─→ Return {executed: true}
542
+ │ │
543
+ │ └─→ [PHYSICAL EFFECT]
544
+ │ ├─→ Validate properties
545
+ │ ├─→ owner.executePhysicalSkill()
546
+ │ ├─→ On collision:
547
+ │ │ ├─→ Fire: SKILL_PHYSICAL_EFFECT_HIT
548
+ │ │ └─→ Call parent Effect logic
549
+ │ └─→ Return {executed: true}
550
+ │
551
+ ├─→ Fire: SKILL_AFTER_RUN_LOGIC
552
+ │
553
+ ▼
554
+ ╔════════════════════════╗
555
+ ║ PHASE 6: POST-EXECUTE ║
556
+ ╚════════════════════════╝
557
+ │
558
+ ├─→ Increment usesCount
559
+ ├─→ Fire: SKILL_AFTER_EXECUTE
560
+ │
561
+ ▼
562
+ ┌─────────────────────┐
563
+ │ Return result │
564
+ └─────────────────────┘
565
+ ```
566
+
567
+ ---
568
+
569
+ ## EVENT SEQUENCE SUMMARY
570
+
571
+ ### Standard Skill Execution (No Cast Time):
572
+ 1. `SKILL_BEFORE_EXECUTE`
573
+ 2. `VALIDATE_BEFORE`
574
+ 3. `SKILL_BEFORE_IN_RANGE` (if range check enabled)
575
+ 4. `SKILL_AFTER_IN_RANGE` (if range check enabled)
576
+ 5. `VALIDATE_SUCCESS`
577
+ 6. `SKILL_APPLY_OWNER_EFFECTS` (if ownerEffects exist)
578
+ 7. `SKILL_BEFORE_RUN_LOGIC`
579
+ 8. [Type-specific events]
580
+ 9. `SKILL_AFTER_RUN_LOGIC`
581
+ 10. `SKILL_AFTER_EXECUTE`
582
+
583
+ ### With Cast Time:
584
+ (Same as above, but insert after owner effects):
585
+ - `SKILL_BEFORE_CAST`
586
+ - (wait castTime ms)
587
+ - `SKILL_AFTER_CAST`
588
+
589
+ ### Attack Skill Additional Event:
590
+ - `SKILL_ATTACK_APPLY_DAMAGE` (during runSkillLogic)
591
+
592
+ ### Effect Skill Additional Event:
593
+ - `SKILL_EFFECT_TARGET_MODIFIERS` (during runSkillLogic)
594
+
595
+ ### Physical Attack Additional Event:
596
+ - `SKILL_PHYSICAL_ATTACK_HIT` (on collision)
597
+
598
+ ### Physical Effect Additional Event:
599
+ - `SKILL_PHYSICAL_EFFECT_HIT` (on collision)
600
+
601
+ ---
602
+
603
+ ## COOLDOWN SYSTEM
604
+
605
+ ### Timer Setup (lib/skill.js:178-184)
606
+
607
+ ```javascript
608
+ this.canActivate = false;
609
+ this.skillActivationTimer = setTimeout(() => {
610
+ this.canActivate = true;
611
+ }, this.skillDelay);
612
+ ```
613
+
614
+ ### How It Works:
615
+ 1. When validation starts, `canActivate` is set to false
616
+ 2. Timer is created for `skillDelay` milliseconds
617
+ 3. When timer fires, `canActivate` is set back to true
618
+ 4. If skill is executed while `canActivate = false`, validation fails
619
+
620
+ ### Important:
621
+ - `skillDelay` is in milliseconds
622
+ - Default is 0 (no cooldown)
623
+ - Timer must complete before skill can be used again
624
+ - Multiple skill instances can have independent timers
625
+
626
+ ---
627
+
628
+ ## CRITICAL HIT SYSTEM
629
+
630
+ ### Components:
631
+
632
+ 1. **criticalChance** (0-1): Probability of critical hit
633
+ 2. **criticalMultiplier** (default 2): Damage/effect multiplier
634
+ 3. **criticalFixedValue** (default null): Fixed bonus instead of multiplier
635
+
636
+ ### Calculation Methods:
637
+
638
+ **applyCriticalValue(value)** - Apply critical to a value:
639
+ ```javascript
640
+ // lib/skill.js:315-328
641
+ applyCriticalValue(value)
642
+ {
643
+ if(!this.canCriticalHit()){
644
+ return value;
645
+ }
646
+ if(this.criticalFixedValue){
647
+ return value + this.criticalFixedValue;
648
+ }
649
+ return value * this.criticalMultiplier;
650
+ }
651
+ ```
652
+
653
+ **getCriticalDiff(value)** - Get critical bonus amount:
654
+ ```javascript
655
+ // lib/skill.js:330-334
656
+ getCriticalDiff(value)
657
+ {
658
+ let criticalValue = this.applyCriticalValue(value);
659
+ return criticalValue - value;
660
+ }
661
+ ```
662
+
663
+ **canCriticalHit()** - Roll for critical:
664
+ ```javascript
665
+ // lib/skill.js:336-343
666
+ canCriticalHit()
667
+ {
668
+ if(!this.criticalChance){
669
+ return false;
670
+ }
671
+ let criticalRoll = Math.random();
672
+ return criticalRoll <= this.criticalChance;
673
+ }
674
+ ```
675
+
676
+ ### Critical Application:
677
+
678
+ **Attack Skills:**
679
+ ```javascript
680
+ // Applies to damage value
681
+ damage = damage + this.getCriticalDiff(damage);
682
+ ```
683
+
684
+ **Effect Skills:**
685
+ ```javascript
686
+ // Applies to modifier value
687
+ let newValue = modifier.getModifiedValue();
688
+ if(!avoidCritical){
689
+ newValue = newValue + this.getCriticalDiff(modifier.value);
690
+ }
691
+ ```
692
+
693
+ ### Critical Affected by Dodge/Aim (Attack only):
694
+
695
+ If `criticalAffected` is enabled:
696
+ ```javascript
697
+ let criticalDamage = this.getCriticalDiff(damage);
698
+ if(this.criticalAffected && totalDodge && totalAim){
699
+ criticalDamage = criticalDamage * (totalAim / totalDodge);
700
+ }
701
+ damage = damage + criticalDamage;
702
+ ```
703
+
704
+ ---
705
+
706
+ ## RANGE VALIDATION
707
+
708
+ ### Components:
709
+
710
+ 1. **range**: Maximum distance (0 = infinite)
711
+ 2. **rangeAutomaticValidation**: Enable auto-check before execution
712
+ 3. **owner.isInRange(skill, target, range)**: Distance check method
713
+
714
+ ### Validation Points:
715
+
716
+ **During Skill Validation (if rangeAutomaticValidation):**
717
+ ```javascript
718
+ // lib/skill.js:164-171
719
+ if(this.rangeAutomaticValidation){
720
+ await this.fireEvent(SkillsEvents.SKILL_BEFORE_IN_RANGE, this);
721
+ let interactionResult = this.owner.isInRange(this, this.target, this.range);
722
+ await this.fireEvent(SkillsEvents.SKILL_AFTER_IN_RANGE, this, interactionResult);
723
+ if(!interactionResult){
724
+ return false;
725
+ }
726
+ }
727
+ ```
728
+
729
+ **During Effect Skill Logic:**
730
+ ```javascript
731
+ // lib/types/effect.js:52-55
732
+ if(this.rangeAutomaticValidation && !this.owner.isInRange(this, this.target, this.range)){
733
+ return {error: SKILL.OUT_OF_RANGE};
734
+ }
735
+ ```
736
+
737
+ ### Owner Requirements:
738
+
739
+ Owner must implement:
740
+ ```javascript
741
+ isInRange(skill, target, range)
742
+ {
743
+ if(range === 0){
744
+ return true; // Infinite range
745
+ }
746
+ let distance = this.getDistanceTo(target);
747
+ return distance <= range;
748
+ }
749
+ ```
750
+
751
+ ---
752
+
753
+ ## TARGET VALIDATION
754
+
755
+ ### Target Types:
756
+
757
+ 1. **Fixed Target**: Set in skill constructor
758
+ 2. **Dynamic Target**: Passed to execute(target)
759
+
760
+ ### Validation:
761
+
762
+ **Allow Self Target:**
763
+ ```javascript
764
+ // If allowSelfTarget = false and target === owner
765
+ // Validation should fail (implement in onExecuteConditions)
766
+ ```
767
+
768
+ **Physical Skill Target Validation:**
769
+ ```javascript
770
+ // lib/types/physical-attack.js:74-80
771
+ if(this.validateTargetOnHit && target['key'] !== this.target['key']){
772
+ return {
773
+ executed: true,
774
+ error: SKILL.PHYSICAL_SKILL_INVALID_TARGET
775
+ };
776
+ }
777
+ ```
778
+
779
+ ---
780
+
781
+ ## USES LIMIT SYSTEM
782
+
783
+ ### Properties:
784
+
785
+ 1. **usesLimit**: Maximum uses (0 = unlimited)
786
+ 2. **usesCount**: Current usage count
787
+
788
+ ### Tracking:
789
+
790
+ ```javascript
791
+ // lib/skill.js:138
792
+ this.usesCount++;
793
+ ```
794
+
795
+ ### Implementation Note:
796
+
797
+ The current implementation does NOT enforce usesLimit. You must implement this check manually:
798
+
799
+ ```javascript
800
+ onExecuteConditions()
801
+ {
802
+ if(this.usesLimit > 0 && this.usesCount >= this.usesLimit){
803
+ return false; // Skill exhausted
804
+ }
805
+ return true;
806
+ }
807
+ ```
808
+
809
+ ---
810
+
811
+ ## DEBUGGING SKILL EXECUTION
812
+
813
+ ### Add Logging to Track Flow:
814
+
815
+ ```javascript
816
+ async execute(target)
817
+ {
818
+ console.log('[EXECUTE] Starting skill:', this.key);
819
+ this.target = target;
820
+
821
+ if(this.owner.isCasting){
822
+ console.log('[EXECUTE] Owner is casting, aborting');
823
+ return {error: SKILL.CAN_NOT_ACTIVATE};
824
+ }
825
+
826
+ console.log('[EXECUTE] Firing BEFORE_EXECUTE event');
827
+ await this.fireEvent(SkillsEvents.SKILL_BEFORE_EXECUTE, this, target);
828
+
829
+ console.log('[EXECUTE] Starting validation');
830
+ if(!this.validate()){
831
+ console.log('[EXECUTE] Validation failed');
832
+ return false;
833
+ }
834
+ console.log('[EXECUTE] Validation passed');
835
+
836
+ // ... rest of execution
837
+ }
838
+ ```
839
+
840
+ ### Check Event Registration:
841
+
842
+ ```javascript
843
+ listenEvent(eventName, callback, removeKey, masterKey) {
844
+ let fullName = this.eventFullName(eventName);
845
+ console.log('[LISTEN]', fullName, 'removeKey:', removeKey);
846
+ return this.events.onWithKey(fullName, callback, removeKey, masterKey);
847
+ }
848
+ ```
849
+
850
+ ### Track Critical Hits:
851
+
852
+ ```javascript
853
+ canCriticalHit()
854
+ {
855
+ if(!this.criticalChance){
856
+ return false;
857
+ }
858
+ let criticalRoll = Math.random();
859
+ let isCrit = criticalRoll <= this.criticalChance;
860
+ console.log('[CRITICAL] Roll:', criticalRoll, 'Chance:', this.criticalChance, 'Result:', isCrit);
861
+ return isCrit;
862
+ }
863
+ ```
864
+
865
+ ---
866
+
867
+ ## COMMON PITFALLS
868
+
869
+ ### ❌ PITFALL 1: Not Awaiting execute()
870
+
871
+ **BAD:**
872
+ ```javascript
873
+ skill.execute(target); // Missing await
874
+ console.log('Skill done'); // Runs immediately
875
+ ```
876
+
877
+ **GOOD:**
878
+ ```javascript
879
+ await skill.execute(target); // Wait for completion
880
+ console.log('Skill done'); // Runs after skill finishes
881
+ ```
882
+
883
+ ### ❌ PITFALL 2: Forgetting to Override runSkillLogic()
884
+
885
+ **BAD:**
886
+ ```javascript
887
+ class MySkill extends Skill {
888
+ // No runSkillLogic implementation
889
+ }
890
+ // Skill does nothing when executed
891
+ ```
892
+
893
+ **GOOD:**
894
+ ```javascript
895
+ class MySkill extends Skill {
896
+ async runSkillLogic() {
897
+ // Implement behavior
898
+ return true;
899
+ }
900
+ }
901
+ ```
902
+
903
+ ### ❌ PITFALL 3: Applying Critical to Wrong Value
904
+
905
+ **BAD:**
906
+ ```javascript
907
+ // Applying critical to (currentValue + modifierValue)
908
+ let newValue = modifier.getModifiedValue(); // 80 + 10 = 90
909
+ newValue = newValue * 2; // 90 * 2 = 180 ❌
910
+ ```
911
+
912
+ **GOOD:**
913
+ ```javascript
914
+ // Applying critical to modifierValue only
915
+ let newValue = modifier.getModifiedValue(); // 80 + 10 = 90
916
+ newValue = newValue + this.getCriticalDiff(modifier.value); // 90 + 10 = 100 ✓
917
+ ```
918
+
919
+ ### ❌ PITFALL 4: Checking Range Without Validation Flag
920
+
921
+ **BAD:**
922
+ ```javascript
923
+ // Range checked but rangeAutomaticValidation = false
924
+ let skill = new Skill({
925
+ owner: owner,
926
+ target: target,
927
+ range: 100
928
+ // rangeAutomaticValidation not set (defaults to false)
929
+ });
930
+ await skill.execute(target); // Range NOT checked
931
+ ```
932
+
933
+ **GOOD:**
934
+ ```javascript
935
+ let skill = new Skill({
936
+ owner: owner,
937
+ target: target,
938
+ range: 100,
939
+ rangeAutomaticValidation: true // Enable auto range check
940
+ });
941
+ await skill.execute(target); // Range checked
942
+ ```
943
+
944
+ ### ❌ PITFALL 5: Physical Skills Without Owner Implementation
945
+
946
+ **BAD:**
947
+ ```javascript
948
+ let skill = new PhysicalAttack({
949
+ owner: owner, // owner does NOT implement executePhysicalSkill
950
+ objectWidth: 10,
951
+ objectHeight: 10
952
+ });
953
+ await skill.execute(target); // Returns TARGET_NOT_AVAILABLE error
954
+ ```
955
+
956
+ **GOOD:**
957
+ ```javascript
958
+ owner.executePhysicalSkill = async function(target, skill, executeOnHit) {
959
+ // Implement physics logic
960
+ };
961
+ let skill = new PhysicalAttack({
962
+ owner: owner,
963
+ objectWidth: 10,
964
+ objectHeight: 10
965
+ });
966
+ await skill.execute(target); // Works correctly
967
+ ```
968
+
969
+ ---
970
+
971
+ ## REFERENCES
972
+
973
+ - Base Skill: `lib/skill.js:12-348`
974
+ - Attack Logic: `lib/types/attack.js:69-143`
975
+ - Effect Logic: `lib/types/effect.js:46-68`
976
+ - Physical Attack: `lib/types/physical-attack.js:58-115`
977
+ - Physical Effect: `lib/types/physical-effect.js:58-113`
978
+ - Event Names: `lib/skills-events.js`
979
+ - Constants: `lib/constants.js`