@reldens/skills 0.44.0 → 0.45.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 (45) hide show
  1. package/CLAUDE.md +488 -0
  2. package/README.md +322 -10
  3. package/lib/server.js +1 -24
  4. package/lib/skill.js +4 -4
  5. package/package.json +3 -4
  6. package/lib/server/data-server-validator.js +0 -29
  7. package/lib/server/storage/class-path-generator.js +0 -48
  8. package/lib/server/storage/conditions-generator.js +0 -29
  9. package/lib/server/storage/levels-generator.js +0 -41
  10. package/lib/server/storage/models/mikro-orm/class-path-level-labels-model.js +0 -86
  11. package/lib/server/storage/models/mikro-orm/class-path-level-skills-model.js +0 -98
  12. package/lib/server/storage/models/mikro-orm/class-path-model.js +0 -105
  13. package/lib/server/storage/models/mikro-orm/level-model.js +0 -88
  14. package/lib/server/storage/models/mikro-orm/level-modifiers-model.js +0 -119
  15. package/lib/server/storage/models/mikro-orm/levels-set-model.js +0 -79
  16. package/lib/server/storage/models/mikro-orm/owners-class-path-model.js +0 -79
  17. package/lib/server/storage/models/mikro-orm/registered-models-mikro-orm.js +0 -39
  18. package/lib/server/storage/models/mikro-orm/skill-attack-model.js +0 -156
  19. package/lib/server/storage/models/mikro-orm/skill-group-relation-model.js +0 -82
  20. package/lib/server/storage/models/mikro-orm/skill-model.js +0 -236
  21. package/lib/server/storage/models/mikro-orm/skill-owner-conditions-model.js +0 -83
  22. package/lib/server/storage/models/mikro-orm/skill-owner-effects-model.js +0 -119
  23. package/lib/server/storage/models/mikro-orm/skill-physical-data-model.js +0 -83
  24. package/lib/server/storage/models/mikro-orm/skill-target-effects-model.js +0 -125
  25. package/lib/server/storage/models/mikro-orm/skills-groups-model.js +0 -77
  26. package/lib/server/storage/models/objection-js/class-path-level-labels-model.js +0 -44
  27. package/lib/server/storage/models/objection-js/class-path-level-skills-model.js +0 -53
  28. package/lib/server/storage/models/objection-js/class-path-model.js +0 -85
  29. package/lib/server/storage/models/objection-js/level-model.js +0 -44
  30. package/lib/server/storage/models/objection-js/level-modifiers-model.js +0 -35
  31. package/lib/server/storage/models/objection-js/levels-set-model.js +0 -44
  32. package/lib/server/storage/models/objection-js/owners-class-path-model.js +0 -35
  33. package/lib/server/storage/models/objection-js/registered-models-objection-js.js +0 -39
  34. package/lib/server/storage/models/objection-js/skill-attack-model.js +0 -35
  35. package/lib/server/storage/models/objection-js/skill-group-relation-model.js +0 -44
  36. package/lib/server/storage/models/objection-js/skill-model.js +0 -89
  37. package/lib/server/storage/models/objection-js/skill-owner-conditions-model.js +0 -35
  38. package/lib/server/storage/models/objection-js/skill-owner-effects-model.js +0 -35
  39. package/lib/server/storage/models/objection-js/skill-physical-data-model.js +0 -35
  40. package/lib/server/storage/models/objection-js/skill-target-effects-model.js +0 -35
  41. package/lib/server/storage/models/objection-js/skills-groups-model.js +0 -35
  42. package/lib/server/storage/models-manager.js +0 -111
  43. package/lib/server/storage/modifiers-generator.js +0 -28
  44. package/lib/server/storage/skills-generator.js +0 -102
  45. package/lib/server/storage-observer.js +0 -89
package/CLAUDE.md ADDED
@@ -0,0 +1,488 @@
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## File Access Permissions
6
+
7
+ **IMPORTANT: These permissions must be approved by the user at the beginning of each session.**
8
+
9
+ Once approved, you are granted the following permissions for files under `D:\dap\work\reldens\npm-packages\reldens-skills`:
10
+
11
+ ✅ **ALLOWED**:
12
+ - Read ANY file under `D:\dap\work\reldens\npm-packages\reldens-skills`
13
+ - Create NEW files under `D:\dap\work\reldens\npm-packages\reldens-skills`
14
+
15
+ ❌ **FORBIDDEN**:
16
+ - Edit or modify EXISTING files
17
+ - Delete files
18
+ - Move files
19
+
20
+ **When modifications to existing files are needed:**
21
+ - Provide complete NEW file artifacts with the full updated content
22
+ - User will manually replace the existing files with the new content
23
+ - Never use the Edit tool on existing files
24
+
25
+ ## Code Rules & Standards
26
+
27
+ 1. Read and follow ALL coding rules from `D:\dap\work\reldens\_source\ai-coding-rules.md`.
28
+ 2. Apply the code rules to every single line of code you provide.
29
+ 3. Self-audit every response against the rules before sending.
30
+
31
+ ## Package Overview
32
+
33
+ **@reldens/skills** (v0.45.0) is a comprehensive skills, leveling, and combat system that provides:
34
+ - Level sets with automatic progression and experience management
35
+ - Class paths with skill trees and level-dependent unlocks
36
+ - Multiple skill types (base, attack, effect, physical variants)
37
+ - Combat mechanics (damage calculation, critical hits, dodge system)
38
+ - Real-time server-client synchronization via Sender/Receiver pattern
39
+ - Event-driven architecture for custom logic integration
40
+ - Modifiers system integration via @reldens/modifiers
41
+
42
+ This package is part of the Reldens MMORPG Platform ecosystem and can be attached to any entity owner with position methods.
43
+
44
+ ## Key Commands
45
+
46
+ ```bash
47
+ # Run tests
48
+ npm test
49
+ ```
50
+
51
+ ## Architecture
52
+
53
+ ### Package Structure
54
+
55
+ ```
56
+ lib/
57
+ ├── skill.js # Base Skill class
58
+ ├── level.js # Single level with modifiers
59
+ ├── levels-set.js # Level progression system
60
+ ├── class-path.js # Skill tree with class progression
61
+ ├── server.js # SkillsServer wrapper
62
+ ├── constants.js # Shared constants and action names
63
+ ├── skills-events.js # Event name definitions
64
+ ├── server/
65
+ │ └── sender.js # Server-to-client message sender
66
+ ├── client/
67
+ │ └── receiver.js # Client message receiver
68
+ └── types/
69
+ ├── attack.js # Damage-based skills
70
+ ├── effect.js # Modifier-based skills
71
+ ├── physical-attack.js # Physics-enabled attacks
72
+ ├── physical-effect.js # Physics-enabled effects
73
+ ├── physical-properties-validator.js
74
+ └── physical-skill-runner.js
75
+ ```
76
+
77
+ ### Core Classes
78
+
79
+ **Skill** (`lib/skill.js:12`):
80
+ - Base class for all skills
81
+ - Provides validation, execution, range checking
82
+ - Event system integration
83
+ - Owner/target relationship management
84
+ - Critical hit system (chance, multiplier, fixed value)
85
+ - Cooldown/delay system (`skillDelay`, `canActivate`)
86
+ - Cast time support with `castTime` property
87
+ - Owner conditions validation
88
+ - Owner effects application
89
+ - Properties:
90
+ - `key`: Unique skill identifier
91
+ - `owner`: Entity that owns the skill (must have `getPosition()` method)
92
+ - `target`: Target entity (can be fixed or passed on execution)
93
+ - `range`: Skill range (0 = infinite range)
94
+ - `rangeAutomaticValidation`: Auto-validate range before execution
95
+ - `allowSelfTarget`: Allow targeting the owner
96
+ - `usesLimit`: Maximum uses (0 = unlimited)
97
+ - `ownerConditions`: Array of Condition instances
98
+ - `ownerEffects`: Array of modifiers applied to owner on execution
99
+ - `criticalChance`, `criticalMultiplier`, `criticalFixedValue`
100
+
101
+ **Level** (`lib/level.js:9`):
102
+ - Represents a single level with:
103
+ - `key`: Integer level number
104
+ - `modifiers`: Array of modifiers applied at this level
105
+ - `label`: Display name for the level
106
+ - `requiredExperience`: XP required to reach this level
107
+
108
+ **LevelsSet** (`lib/levels-set.js:11`):
109
+ - Manages level progression and experience
110
+ - Auto-fills level ranges if `autoFillRanges` enabled
111
+ - Experience-based automatic leveling
112
+ - Modifier application/reversion on level up/down
113
+ - Properties:
114
+ - `owner`: Entity with `getPosition()` method
115
+ - `levels`: Object of Level instances
116
+ - `currentLevel`: Current level number
117
+ - `currentExp`: Current experience points
118
+ - `autoFillRanges`: Auto-generate intermediate levels
119
+ - `autoFillExperienceMultiplier`: XP multiplier for auto-generated levels (default: 1.5)
120
+ - `increaseLevelsWithExperience`: Auto level up when XP threshold reached
121
+ - `levelsByExperience`: Sorted array of level keys by required XP
122
+ - `setRequiredExperienceLimit`: Cap XP at max level requirement
123
+ - Methods:
124
+ - `levelUp()`: Increase level, apply modifiers
125
+ - `levelDown()`: Decrease level, revert modifiers
126
+ - `addExperience(number)`: Add XP, auto-level if enabled
127
+ - `getNextLevelExperience()`: Get XP required for next level
128
+
129
+ **ClassPath** (`lib/class-path.js:11`):
130
+ - Extends LevelsSet
131
+ - Provides skill tree functionality
132
+ - Level-based skill unlocking
133
+ - Dynamic label changes per level
134
+ - Properties:
135
+ - `key`: Class path identifier
136
+ - `label`: Base display name
137
+ - `labelsByLevel`: Object of {levelKey: 'label'} for level-specific names
138
+ - `currentLabel`: Active display name
139
+ - `skillsByLevel`: Object of {levelKey: [Skill instances]}
140
+ - `skillsByLevelKeys`: Object of {levelKey: [skill keys]}
141
+ - `currentSkills`: Object of currently available skills
142
+ - `affectedProperty`: Property affected by class skills (e.g., 'hp')
143
+ - Methods:
144
+ - `addSkills(skills)`: Add skills to current set
145
+ - `removeSkills(skills)`: Remove skills from current set
146
+ - `setOwnerSkills(skills)`: Initialize owner's skill set based on current level
147
+
148
+ **SkillsServer** (`lib/server.js:11`):
149
+ - Server-side wrapper for ClassPath
150
+ - Integrates Sender for client communication
151
+ - Validates client has `send()` and `broadcast()` methods
152
+ - Automatically initializes ClassPath and registers listeners
153
+
154
+ ### Skill Types
155
+
156
+ **Attack** (`lib/types/attack.js:14`):
157
+ - Extends Skill for damage-based skills
158
+ - Damage calculation with attack vs defense properties
159
+ - Dodge system with aim vs dodge properties
160
+ - Critical damage affected by aim/dodge ratio
161
+ - Properties:
162
+ - `affectedProperty`: Target property to modify (e.g., 'hp')
163
+ - `hitDamage`: Base damage at 100%
164
+ - `applyDirectDamage`: Skip calculations, apply hitDamage directly
165
+ - `attackProperties`: Array of owner properties for attack total
166
+ - `defenseProperties`: Array of target properties for defense total
167
+ - `aimProperties`: Array of owner properties for aim total
168
+ - `dodgeProperties`: Array of target properties for dodge total
169
+ - `dodgeFullEnabled`: Enable complete dodge if dodge > (aim * dodgeOverAimSuccess)
170
+ - `dodgeOverAimSuccess`: Dodge threshold multiplier (default: 1)
171
+ - `damageAffected`: Apply dodge/aim ratio to damage
172
+ - `criticalAffected`: Apply dodge/aim ratio to critical damage
173
+ - `propertiesTotalOperators`: Custom operators for property totals
174
+ - `allowEffectBelowZero`: Allow negative values on affected property
175
+ - Damage Calculation:
176
+ 1. Calculate owner aim and target dodge totals
177
+ 2. Check full dodge: `dodge > (aim * dodgeOverAimSuccess)`
178
+ 3. Calculate base damage: `hitDamage` modified by attack vs defense diff
179
+ 4. Apply dodge/aim ratio if `damageAffected` enabled
180
+ 5. Calculate critical damage with dodge/aim ratio if `criticalAffected`
181
+ 6. Apply total damage to `affectedProperty`
182
+
183
+ **Effect** (`lib/types/effect.js:14`):
184
+ - Extends Skill for modifier-based skills (buffs/debuffs)
185
+ - Applies modifiers to target with critical chance
186
+ - Properties:
187
+ - `targetEffects`: Array of modifiers applied to target
188
+ - Logic: Validates range, applies modifiers with critical calculation
189
+
190
+ **PhysicalAttack** (`lib/types/physical-attack.js:16`):
191
+ - Extends Attack for physics-enabled attacks
192
+ - Requires collision detection system
193
+ - Properties:
194
+ - `magnitude`: Physics force/magnitude
195
+ - `objectWidth`: Collision object width
196
+ - `objectHeight`: Collision object height
197
+ - `validateTargetOnHit`: Verify target matches on collision
198
+ - Requires owner to implement `executePhysicalSkill(target, skill)` method
199
+ - Uses PhysicalSkillRunner for execution
200
+ - Fires `SKILL_PHYSICAL_ATTACK_HIT` event on collision
201
+ - Calls parent `runSkillLogic()` in `executeOnHit(target)` callback
202
+
203
+ **PhysicalEffect** (`lib/types/physical-effect.js:16`):
204
+ - Extends Effect for physics-enabled effects
205
+ - Same physics properties as PhysicalAttack
206
+ - Uses PhysicalSkillRunner for execution
207
+ - Fires `SKILL_PHYSICAL_EFFECT_HIT` event on collision
208
+
209
+ ### Communication System
210
+
211
+ **Sender** (`lib/server/sender.js:11`):
212
+ - Server-to-client message broadcaster
213
+ - Registers event listeners on ClassPath events
214
+ - Sends compressed data to client
215
+ - Behaviors:
216
+ - `BEHAVIOR_SEND`: Send to owner client only
217
+ - `BEHAVIOR_BROADCAST`: Broadcast to all clients
218
+ - `BEHAVIOR_BOTH`: Both send and broadcast
219
+ - Registered Events:
220
+ - `INIT_CLASS_PATH_END`: Send initial class data (level, label, XP, skills)
221
+ - `LEVEL_UP`: Send level up data (new level, label, skills, next XP)
222
+ - `LEVEL_EXPERIENCE_ADDED`: Send current XP
223
+ - `SKILL_BEFORE_CAST`: Broadcast skill cast start
224
+ - `SKILL_ATTACK_APPLY_DAMAGE`: Broadcast damage application
225
+ - Message Format:
226
+ ```javascript
227
+ {
228
+ act: 'rski.ICpe', // Action constant
229
+ owner: ownerId, // Owner ID
230
+ data: { // Compressed data
231
+ lvl: 5, // Level
232
+ lab: 'Warrior', // Label
233
+ exp: 1500, // Current XP
234
+ ne: 2000, // Next level XP
235
+ skl: ['sword', 'shield'] // Skill keys
236
+ }
237
+ }
238
+ ```
239
+
240
+ **Receiver** (`lib/client/receiver.js:10`):
241
+ - Client-side message processor
242
+ - Maps action constants to method names
243
+ - Validates message action prefix (`rski.`)
244
+ - Properties:
245
+ - `actions`: Object mapping action constants to method names
246
+ - `avoidDefaults`: Skip default action-to-method mapping
247
+ - Default Method Mapping: Each action constant maps to `on[ActionName]` method
248
+ - Usage: Extend and implement handler methods (e.g., `onLevelUp(message)`)
249
+
250
+ ### Events System
251
+
252
+ All events are prefixed with `reldens.skills.` and appended with owner event key.
253
+
254
+ **Level Set Events** (fired by LevelsSet):
255
+ - `INIT_LEVEL_SET_START`: Before level set initialization
256
+ - `INIT_LEVEL_SET_END`: After level set initialization
257
+ - `SET_LEVELS`: After levels are set
258
+ - `GENERATED_LEVELS`: After auto-filling a level range
259
+ - `LEVEL_UP`: After level increases
260
+ - `LEVEL_DOWN`: After level decreases
261
+ - `LEVEL_APPLY_MODIFIERS`: Before applying level modifiers
262
+ - `LEVEL_EXPERIENCE_ADDED`: After XP added (args: number, newTotal, currentLevelIndex, nextLevelIndex, nextLevelKey, nextLevel, nextLevelExp, isLevelUp)
263
+
264
+ **Class Path Events** (fired by ClassPath):
265
+ - `INIT_CLASS_PATH_END`: After class path initialization
266
+ - `SET_SKILLS`: After owner skills set
267
+ - `ADD_SKILLS_BEFORE`: Before adding skills
268
+ - `ADD_SKILLS_AFTER`: After adding skills
269
+ - `REMOVE_SKILLS_BEFORE`: Before removing skills
270
+ - `REMOVE_SKILLS_AFTER`: After removing skills
271
+
272
+ **Skill Execution Events** (fired by Skill):
273
+ - `VALIDATE_BEFORE`: Before skill validation
274
+ - `VALIDATE_SUCCESS`: After successful validation
275
+ - `VALIDATE_FAIL`: After validation failure (args: skill, failedCondition)
276
+ - `SKILL_BEFORE_IN_RANGE`: Before range check
277
+ - `SKILL_AFTER_IN_RANGE`: After range check (args: skill, interactionResult)
278
+ - `SKILL_BEFORE_EXECUTE`: Before skill execution
279
+ - `SKILL_APPLY_OWNER_EFFECTS`: After applying owner effects
280
+ - `SKILL_BEFORE_CAST`: Before cast time starts
281
+ - `SKILL_AFTER_CAST`: After cast time completes
282
+ - `SKILL_BEFORE_RUN_LOGIC`: Before skill logic execution
283
+ - `SKILL_AFTER_RUN_LOGIC`: After skill logic execution
284
+ - `SKILL_AFTER_EXECUTE`: After skill execution complete
285
+
286
+ **Attack/Effect Events**:
287
+ - `SKILL_ATTACK_APPLY_DAMAGE`: After damage applied (args: skill, target, damage, newValue)
288
+ - `SKILL_EFFECT_TARGET_MODIFIERS`: After effect modifiers applied
289
+ - `SKILL_PHYSICAL_ATTACK_HIT`: On physical attack collision
290
+ - `SKILL_PHYSICAL_EFFECT_HIT`: On physical effect collision
291
+
292
+ **Event Naming Convention**:
293
+ Events are automatically namespaced by owner:
294
+ ```javascript
295
+ // Event fired as: 'skills.ownerId.123.reldens.skills.levelUp'
296
+ skill.fireEvent(SkillsEvents.LEVEL_UP, this);
297
+
298
+ // Listen to specific owner's events:
299
+ skill.listenEvent(SkillsEvents.LEVEL_UP, callback, removeKey, masterKey);
300
+ ```
301
+
302
+ ### Constants
303
+
304
+ **Skill Types** (`constants.js:10`):
305
+ - `SKILL.TYPE.BASE`: Base skill (1)
306
+ - `SKILL.TYPE.ATTACK`: Attack skill (2)
307
+ - `SKILL.TYPE.EFFECT`: Effect skill (3)
308
+ - `SKILL.TYPE.PHYSICAL_ATTACK`: Physical attack (4)
309
+ - `SKILL.TYPE.PHYSICAL_EFFECT`: Physical effect (5)
310
+
311
+ **Skill States** (`constants.js:53`):
312
+ - `PHYSICAL_SKILL_INVALID_TARGET`: Target validation failed
313
+ - `PHYSICAL_SKILL_RUN_LOGIC`: Running physical skill logic
314
+ - `OUT_OF_RANGE`: Target out of range
315
+ - `CAN_NOT_ACTIVATE`: Skill on cooldown or owner casting
316
+ - `DODGED`: Attack dodged
317
+ - `APPLYING_DAMAGE`: Damage calculation in progress
318
+ - `APPLIED_DAMAGE`: Damage applied successfully
319
+ - `APPLIED_CRITICAL_DAMAGE`: Critical damage applied
320
+ - `APPLYING_EFFECTS`: Effects being applied
321
+ - `APPLIED_EFFECTS`: Effects applied successfully
322
+ - `EXECUTE_PHYSICAL_ATTACK`: Physical attack executing
323
+ - `TARGET_NOT_AVAILABLE`: Target undefined or invalid
324
+
325
+ **Action Constants** (`constants.js:7`):
326
+ All action constants use `rski.` prefix (Reldens Skills) for network messages:
327
+ - `ACTION_INIT_CLASS_PATH_END`: 'rski.ICpe'
328
+ - `ACTION_LEVEL_UP`: 'rski.Lu'
329
+ - `ACTION_LEVEL_EXPERIENCE_ADDED`: 'rski.Ea'
330
+ - (See constants.js:24-51 for complete list)
331
+
332
+ **Behaviors** (`constants.js:20`):
333
+ - `BEHAVIOR_SEND`: Send to owner only
334
+ - `BEHAVIOR_BROADCAST`: Broadcast to all
335
+ - `BEHAVIOR_BOTH`: Both send and broadcast
336
+
337
+ ## Dependencies
338
+
339
+ - **@reldens/modifiers** (^0.32.0): Provides PropertyManager, Condition, Calculator, and modifier system
340
+ - **@reldens/utils** (^0.54.0): Provides Shortcuts (sc), Logger, EventsManagerSingleton, InteractionArea
341
+
342
+ ## Common Development Patterns
343
+
344
+ ### Creating a Custom Skill
345
+
346
+ ```javascript
347
+ const { Skill } = require('@reldens/skills');
348
+
349
+ class MyCustomSkill extends Skill
350
+ {
351
+ constructor(props)
352
+ {
353
+ super(props);
354
+ // Custom properties
355
+ }
356
+
357
+ async runSkillLogic()
358
+ {
359
+ // Implement skill behavior
360
+ // Access this.owner, this.target
361
+ // Use this.applyModifiers(), this.applyCriticalValue()
362
+ return true; // Success
363
+ }
364
+
365
+ onExecuteConditions()
366
+ {
367
+ // Custom validation before execution
368
+ return true; // Valid
369
+ }
370
+ }
371
+ ```
372
+
373
+ ### Setting Up a Class Path
374
+
375
+ ```javascript
376
+ const { ClassPath, Level } = require('@reldens/skills');
377
+
378
+ let levels = {
379
+ 1: new Level({
380
+ key: 1,
381
+ modifiers: [/* modifier instances */],
382
+ requiredExperience: 0
383
+ }),
384
+ 5: new Level({
385
+ key: 5,
386
+ modifiers: [/* modifier instances */],
387
+ requiredExperience: 1000
388
+ })
389
+ };
390
+
391
+ let classPath = new ClassPath({
392
+ owner: playerEntity,
393
+ key: 'warrior',
394
+ label: 'Warrior',
395
+ levels: levels,
396
+ autoFillRanges: true, // Auto-generate levels 2, 3, 4
397
+ currentLevel: 1,
398
+ currentExp: 0,
399
+ skillsByLevel: {
400
+ 1: [swordSkill],
401
+ 5: [shieldSkill]
402
+ }
403
+ });
404
+
405
+ await classPath.init({
406
+ owner: playerEntity,
407
+ key: 'warrior',
408
+ levels: levels
409
+ });
410
+ ```
411
+
412
+ ### Server-Side Integration
413
+
414
+ ```javascript
415
+ const { SkillsServer } = require('@reldens/skills');
416
+
417
+ let skillsServer = new SkillsServer({
418
+ owner: playerEntity,
419
+ client: roomClient, // Must have send() and broadcast() methods
420
+ key: 'warrior',
421
+ levels: levels,
422
+ skillsByLevel: skillsByLevel
423
+ });
424
+ ```
425
+
426
+ ### Client-Side Integration
427
+
428
+ ```javascript
429
+ const { Receiver } = require('@reldens/skills/lib/client/receiver');
430
+
431
+ class MySkillsUI extends Receiver
432
+ {
433
+ onLevelUp(message)
434
+ {
435
+ console.log('Level up!', message.data.lvl);
436
+ // Update UI with new level, label, skills
437
+ }
438
+
439
+ onLevelExperienceAdded(message)
440
+ {
441
+ console.log('XP gained:', message.data.exp);
442
+ // Update XP bar
443
+ }
444
+ }
445
+
446
+ let receiver = new MySkillsUI({owner: playerEntity});
447
+ gameClient.onMessage('*', (message) => receiver.processMessage(message));
448
+ ```
449
+
450
+ ### Hooking into Events
451
+
452
+ ```javascript
453
+ // Listen to skill events
454
+ skill.listenEvent(SkillsEvents.SKILL_AFTER_EXECUTE, async (skill, target) => {
455
+ console.log('Skill executed:', skill.key);
456
+ // Custom logic after skill execution
457
+ }, 'myUniqueKey', skill.getOwnerEventKey());
458
+
459
+ // Listen to level events
460
+ classPath.listenEvent(SkillsEvents.LEVEL_UP, async (classPath) => {
461
+ console.log('Leveled up to:', classPath.currentLevel);
462
+ // Award achievement, show animation, etc.
463
+ }, 'levelUpListener', classPath.getOwnerEventKey());
464
+ ```
465
+
466
+ ## Important Notes
467
+
468
+ - **Owner Requirements**: All owners must implement `getPosition()` returning `{x, y}` object
469
+ - **Physical Skills**: Require owner to implement `executePhysicalSkill(target, skill)` method
470
+ - **Event-Driven**: All major operations fire events for custom logic integration
471
+ - **Standalone Package**: Can be used independently from main Reldens platform
472
+ - **Server Authoritative**: For multiplayer games, always validate skills on server
473
+ - **Modifiers Integration**: Uses @reldens/modifiers Condition and Modifier instances
474
+ - **Range System**: Range 0 = infinite range, uses InteractionArea for circular validation
475
+ - **Critical System**: Independent chance, multiplier, and fixed value properties
476
+ - **Auto-Leveling**: Automatically levels up when XP threshold reached if enabled
477
+ - **Experience Cap**: Can limit XP to max level requirement with `setRequiredExperienceLimit`
478
+
479
+ ## Analysis Approach
480
+
481
+ When working on code issues:
482
+ - Always investigate thoroughly before making changes
483
+ - Read related files completely before proposing solutions
484
+ - Trace execution flows and dependencies
485
+ - Provide proof for issues, never guess or assume
486
+ - Verify file contents before creating patches
487
+ - Never jump to early conclusions
488
+ - A variable with an unexpected value is not an issue, it is the result of a previous issue