@directivegames/genesys.js 3.1.24

package/docs/guides/11-equipment-and-weapons.md

@@ -0,0 +1,850 @@
+## Instruction
+Use this doc to understand how equipment and weapons work in Genesys.js and learn how to create interactive items using the IEquipment interface, GenericEquipment base class for timing control, and ProjectileWeaponComponent for ranged weapons that integrate with Pawn actors.
+
+# 11-equipment-and-weapons.md
+
+## Equipment and Weapon Systems in Genesys.js
+
+The Equipment and Weapon System in Genesys.js provides a flexible, component-based approach to creating interactive items that characters can use. Whether you're building projectile weapons, melee weapons, tools, or special abilities, this system offers the building blocks to create engaging gameplay mechanics.
+
+The system is built around three core concepts:
+
+*   **`IEquipment` Interface**: A contract that defines how equipment responds to player input (primary fire, secondary fire, etc.).
+*   **`GenericEquipment` Base Class**: A `SceneComponent` that provides timing logic and rate limiting for equipment actions.
+*   **`ProjectileWeaponComponent`**: A concrete implementation that fires projectile actors, perfect for guns, magic spells, or any ranged weapon.
+
+By understanding these components and how they integrate with `Pawn` actors, you can create sophisticated weapon systems with minimal code.
+
+---
+
+## 1. The Equipment Interface (`IEquipment`)
+
+At its core, any equipment in Genesys.js must implement the `IEquipment` interface. This interface provides a standardized way for `Pawn` actors to interact with equipment components.
+
+### The Equipment Contract
+
+```typescript
+export interface IEquipment {
+    beginFire(): boolean;
+    endFire(): boolean;
+    beginAltFire(): boolean;
+    endAltFire(): boolean;
+}
+```
+
+*   **`beginFire()`**: Called when the player starts the primary action (e.g., pulling the trigger).
+*   **`endFire()`**: Called when the player stops the primary action (e.g., releasing the trigger).
+*   **`beginAltFire()`**: Called when the player starts the secondary action (e.g., aiming down sights).
+*   **`endAltFire()`**: Called when the player stops the secondary action.
+
+Each method returns a `boolean` indicating whether the action was successfully handled.
+
+### Runtime Type Checking
+
+The system provides a helper function to safely check if an object implements the equipment interface:
+
+```typescript
+import { isEquipment } from 'genesys.js';
+
+// Safe type checking
+if (isEquipment(someComponent)) {
+    // TypeScript now knows this object has beginFire, endFire, etc.
+    someComponent.beginFire();
+}
+```
+
+---
+
+## 2. How Equipment Integrates with Pawns
+
+The `Pawn` class automatically searches for equipment components and routes input to them. When a player presses the fire button, the pawn calls the equipment's `beginFire()` method.
+
+### Automatic Equipment Discovery
+
+Pawns automatically discover equipment components in two places:
+1. **Non-Scene Components**: Components attached directly to the pawn that don't have a transform.
+2. **Scene Components**: Components that are part of the pawn's scene graph hierarchy.
+
+```typescript
+// This method in Pawn searches for and calls equipment
+protected callEquipment(method: keyof IEquipment): boolean {
+    // Check non-scene components first
+    for (const component of this.nonSceneComponents) {
+        if (isEquipment(component) && component[method]()) {
+            return true;
+        }
+    }
+    // Then check scene components
+    for (const component of this.getComponents(SceneComponent)) {
+        if (isEquipment(component) && component[method]()) {
+            return true;
+        }
+    }
+    return false;
+}
+```
+
+### Input Flow for Equipment
+
+1. Player presses fire button (mouse click, gamepad trigger, etc.)
+2. `PlayerController` receives the input event
+3. `PlayerController` calls `pawn.beginFire()`
+4. `Pawn` searches all components for those implementing `IEquipment`
+5. First equipment component that successfully handles the action stops the chain
+
+---
+
+## 3. Generic Equipment Base Class
+
+The `GenericEquipment` class provides common functionality that most weapons need: timing control, rate limiting, and single-fire vs. automatic fire modes.
+
+### Key Features
+
+*   **Rate Limiting**: Ensures weapons don't fire faster than their configured rate.
+*   **Single Fire Mode**: Allows for semi-automatic weapons that fire once per trigger pull.
+*   **Automatic Fire Mode**: Enables fully automatic weapons that continue firing while the trigger is held.
+*   **Scene Integration**: Extends `SceneComponent`, so it has a position and can be attached to the scene graph.
+
+### Basic Usage
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+interface CustomWeaponOptions extends ENGINE.GenericEquipmentOptions {
+    // Add any custom options here if needed
+}
+
+@ENGINE.GameClass()
+class CustomWeapon extends ENGINE.GenericEquipment<CustomWeaponOptions> {
+    static override get DEFAULT_OPTIONS(): CustomWeaponOptions {
+        return {
+            ...ENGINE.GenericEquipment.DEFAULT_OPTIONS,
+            fireInterval: 0.1, // Fire 10 times per second
+            isSingleFire: false // Full auto
+        };
+    }
+
+    // This method is called each time the weapon should fire
+    protected doFire(): void {
+        console.log("Bang!");
+        // Your custom firing logic here
+    }
+}
+```
+
+### Configuration Options
+
+```typescript
+interface GenericEquipmentOptions extends SceneComponentOptions {
+    fireInterval: number;    // Time between shots in seconds
+    isSingleFire: boolean;   // True for semi-auto, false for full-auto
+}
+
+interface ProjectileWeaponOptions extends GenericEquipmentOptions {
+    projectileOptions: ProjectileOptions;       // Projectile configuration
+    projectileClass?: typeof Projectile;       // Custom projectile class
+    modelPath?: string;                         // 3D model path
+    ammoCapacity?: number;                      // Max ammo (0 = infinite)
+    reloadTime?: number;                        // Reload duration in seconds
+}
+```
+
+### Timing Logic
+
+The `GenericEquipment` class handles complex timing logic automatically:
+- Tracks when firing began and manages fire rate
+- Handles the difference between single-fire and automatic weapons
+- Ensures consistent timing even with variable frame rates
+- Calls your `doFire()` method at the appropriate intervals
+
+---
+
+## 4. Projectile Weapon Component
+
+The `ProjectileWeaponComponent` is a complete, ready-to-use weapon implementation that fires `Projectile` actors. It's perfect for guns, cannons, magic spells, or any weapon that launches objects.
+
+### Basic Projectile Weapon Setup
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Create a simple gun that fires yellow spheres
+const weapon = new ENGINE.ProjectileWeaponComponent({
+    fireInterval: 0.2,        // 5 shots per second
+    isSingleFire: false,      // Full automatic
+    projectileOptions: {
+        velocity: 100,          // Speed of projectiles
+        range: 50,             // How far they travel
+        damageDealt: 25,       // Damage on hit
+        useOverlapCheck: true, // Use overlap instead of collision
+        destroyOnHit: true,    // Destroy projectile on impact
+        geometry: new THREE.SphereGeometry(0.3),
+        material: new THREE.MeshStandardMaterial({ color: 'yellow' })
+    }
+});
+```
+
+### Advanced Projectile Configuration
+
+```typescript
+// Create a powerful magic staff
+const magicStaff = new ENGINE.ProjectileWeaponComponent({
+    position: new THREE.Vector3(0, 1, -0.5), // Offset from pawn center
+    fireInterval: 1.0,        // Slow, powerful shots
+    isSingleFire: true,       // One shot per click
+    projectileOptions: {
+        velocity: 75,
+        range: 100,
+        damageDealt: 100,
+        useOverlapCheck: false, // Use full collision
+        destroyOnHit: true,
+        gravityScale: 0,        // No gravity for magic projectiles
+        geometry: new THREE.SphereGeometry(0.8),
+        material: new THREE.MeshStandardMaterial({ 
+            color: 'purple',
+            emissive: 'purple',
+            emissiveIntensity: 0.3
+        })
+    }
+});
+```
+
+### Visual Representation and 3D Models
+
+ProjectileWeaponComponent includes built-in support for 3D models with automatic fallback to primitive shapes:
+
+```typescript
+// Weapon with 3D model
+const rifle = new ENGINE.ProjectileWeaponComponent({
+    modelPath: '@engine/assets/models/Weapons/SM_Rifle_01.glb', // 3D model path
+    position: new THREE.Vector3(0.3, -0.3, -0.4), // Position in first-person
+    rotation: new THREE.Euler(0, Math.PI/2, 0),   // Orientation
+    scale: new THREE.Vector3(1, 1, 1),            // Size scaling
+    projectileOptions: {
+        // ... projectile configuration
+    }
+});
+
+// Weapon with fallback primitive (if model fails to load)
+const pistol = new ENGINE.ProjectileWeaponComponent({
+    modelPath: '/path/to/missing/model.glb', // This will fail
+    // Fallback: Creates a gray cylinder primitive automatically
+    projectileOptions: {
+        // ... projectile configuration
+    }
+});
+```
+
+The component automatically handles:
+- **Model Loading**: Loads GLTF/GLB files asynchronously
+- **Error Handling**: Graceful fallback if model fails to load
+- **Primitive Fallback**: Creates a simple cylinder shape if no model is available
+- **Transform Application**: Applies position, rotation, and scale to the visual representation
+
+### Ammo Management System
+
+ProjectileWeaponComponent includes a comprehensive ammo management system:
+
+```typescript
+// Weapon with finite ammo and reload mechanics
+const shotgun = new ENGINE.ProjectileWeaponComponent({
+    modelPath: '@engine/assets/models/Weapons/SM_ShotGun_01.glb',
+    
+    // Fire control
+    fireInterval: 0.8,        // Slow fire rate
+    isSingleFire: true,       // Semi-automatic
+    
+    // Ammo management
+    ammoCapacity: 8,          // 8 shots per magazine
+    reloadTime: 2.5,          // 2.5 seconds to reload
+    
+    projectileOptions: {
+        velocity: 150,
+        range: 30,
+        damageDealt: 80,
+        // ... other projectile options
+    }
+});
+
+// Access ammo information
+console.log(`Current ammo: ${shotgun.getCurrentAmmo()}`);       // e.g., 5
+console.log(`Max ammo: ${shotgun.getMaxAmmo()}`);               // 8
+console.log(`Infinite ammo: ${shotgun.isAmmoInfinite()}`);      // false
+
+// Trigger a reload
+shotgun.reload();
+
+// Infinite ammo weapon (default behavior)
+const magicStaff = new ENGINE.ProjectileWeaponComponent({
+    ammoCapacity: 0,          // 0 = infinite ammo
+    // No ammo consumption, no reloading needed
+    projectileOptions: {
+        // ... projectile configuration
+    }
+});
+```
+
+The ammo system provides:
+- **Automatic Consumption**: Ammo decreases with each shot
+- **Auto-Reload**: Automatically starts reloading when ammo reaches zero
+- **Reload Prevention**: Cannot fire while reloading
+- **Infinite Ammo**: Set `ammoCapacity: 0` for unlimited ammunition
+- **Flexible Timing**: Configurable reload duration with `reloadTime`
+
+#### Ammo Management API
+
+```typescript
+// Query ammo state
+const currentAmmo = weapon.getCurrentAmmo();      // Current ammunition count
+const maxAmmo = weapon.getMaxAmmo();              // Maximum ammunition capacity
+const hasInfiniteAmmo = weapon.isAmmoInfinite();  // True if ammo is unlimited
+
+// Trigger reload (automatically handled by engine input system)
+weapon.reload();                                  // Starts reload if not already reloading
+
+// Check if weapon is currently reloading (read-only property)
+// Note: Use in game logic to disable certain actions during reload
+```
+
+### Targeted Shooting
+
+The `ProjectileWeaponComponent` supports shooting at specific targets:
+
+```typescript
+// Fire a single shot at a specific world position
+const targetPosition = new THREE.Vector3(10, 5, -20);
+weapon.tryFireAtTarget(targetPosition);
+```
+
+### Custom Projectile Classes
+
+You can use custom projectile classes for specialized behavior:
+
+```typescript
+@ENGINE.GameClass()
+class ExplosiveProjectile extends ENGINE.Projectile {
+    protected override onHit(component: any, otherComponent: any, event: any): void {
+        // Custom explosion logic
+        this.createExplosion();
+        super.onHit(component, otherComponent, event);
+    }
+
+    private createExplosion(): void {
+        // Spawn explosion effects, deal area damage, etc.
+        console.log("BOOM!");
+    }
+}
+
+// Use the custom projectile class
+const rocketLauncher = new ENGINE.ProjectileWeaponComponent({
+    projectileClass: ExplosiveProjectile,
+    projectileOptions: {
+        // ... other options
+    }
+});
+```
+
+---
+
+## 5. Creating Complete Weapon Systems
+
+Let's build a complete example showing how to create a character with multiple weapons and switching capabilities.
+
+### Multi-Weapon Character
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+interface WeaponizedPawnOptions extends ENGINE.PawnOptions {
+    primaryWeapon?: ENGINE.ProjectileWeaponComponent;
+    secondaryWeapon?: ENGINE.ProjectileWeaponComponent;
+}
+
+@ENGINE.GameClass()
+class WeaponizedPawn extends ENGINE.Pawn<WeaponizedPawnOptions> {
+    private primaryWeapon: ENGINE.ProjectileWeaponComponent | null = null;
+    private secondaryWeapon: ENGINE.ProjectileWeaponComponent | null = null;
+    private currentWeapon: ENGINE.ProjectileWeaponComponent | null = null;
+
+    constructor(options: WeaponizedPawnOptions) {
+        super(options);
+        
+        this.setupWeapons(options);
+        this.setupInputHandling();
+    }
+
+    private setupWeapons(options: WeaponizedPawnOptions): void {
+        // Primary weapon (assault rifle) - high capacity, fast fire
+        this.primaryWeapon = options.primaryWeapon ?? new ENGINE.ProjectileWeaponComponent({
+            modelPath: '@engine/assets/models/Weapons/SM_Rifle_01.glb', // 3D model
+            position: new THREE.Vector3(0.5, 1, -1),
+            rotation: new THREE.Euler(0, Math.PI/2, 0),
+            
+            // Fire control
+            fireInterval: 0.1, // 600 RPM
+            isSingleFire: false, // Full auto
+            
+            // Ammo management
+            ammoCapacity: 30,    // 30-round magazine
+            reloadTime: 2.0,     // Quick reload
+            
+            // Audio effects
+            fireSoundUrl: '@engine/assets/sounds/game-gun-short.mp3',
+            
+            // Recoil effects
+            recoilOptions: {
+                weaponRecoilDistance: 0.06,
+                weaponRecoilDuration: 0.10,
+                weaponRecoilRotation: 0.04,
+            },
+            
+            projectileOptions: {
+                velocity: 200,
+                range: 100,
+                damageDealt: 20,
+                useOverlapCheck: true,
+                destroyOnHit: true,
+                geometry: new THREE.SphereGeometry(0.1),
+                material: new THREE.MeshStandardMaterial({ color: 'orange' })
+            }
+        });
+
+        // Secondary weapon (shotgun) - low capacity, high damage
+        this.secondaryWeapon = options.secondaryWeapon ?? new ENGINE.ProjectileWeaponComponent({
+            modelPath: '@engine/assets/models/Weapons/SM_ShotGun_01.glb', // 3D model
+            position: new THREE.Vector3(0.5, 1, -1),
+            rotation: new THREE.Euler(0, Math.PI/2, 0),
+            
+            // Fire control
+            fireInterval: 0.8, // Slow but powerful
+            isSingleFire: true, // Semi-automatic
+            
+            // Ammo management
+            ammoCapacity: 8,     // 8-round magazine
+            reloadTime: 2.5,     // Slower reload
+            
+            // Audio effects
+            fireSoundUrl: '@engine/assets/sounds/explosion.mp3', // Heavier sound
+            
+            // Recoil effects
+            recoilOptions: {
+                weaponRecoilDistance: 0.15, // Strong backward movement
+                weaponRecoilDuration: 0.25,  // Longer recovery
+                weaponRecoilRotation: 0.08,  // Strong upward kick
+            },
+            
+            projectileOptions: {
+                velocity: 150,
+                range: 30,
+                damageDealt: 80,
+                useOverlapCheck: true,
+                destroyOnHit: true,
+                geometry: new THREE.SphereGeometry(0.2),
+                material: new THREE.MeshStandardMaterial({ color: 'red' })
+            }
+        });
+
+        // Start with primary weapon
+        this.currentWeapon = this.primaryWeapon;
+        this.rootComponent.add(this.currentWeapon);
+    }
+
+    private setupInputHandling(): void {
+        // Handle weapon switching and reloading
+        this.onKeyDown.add((event: KeyboardEvent) => {
+            switch (event.code) {
+                case 'Digit1':
+                    this.switchToPrimary();
+                    return true;
+                case 'Digit2':
+                    this.switchToSecondary();
+                    return true;
+                case 'KeyR':
+                    this.reloadCurrentWeapon();
+                    return true;
+            }
+            return false;
+        });
+    }
+
+    private reloadCurrentWeapon(): void {
+        if (this.currentWeapon) {
+            this.currentWeapon.reload();
+            this.updateAmmoUI();
+        }
+    }
+
+    private updateAmmoUI(): void {
+        if (this.currentWeapon) {
+            const current = this.currentWeapon.getCurrentAmmo();
+            const max = this.currentWeapon.getMaxAmmo();
+            const infinite = this.currentWeapon.isAmmoInfinite();
+            
+            if (infinite) {
+                console.log('Ammo: ∞');
+                // In a real game: ammoDisplay.setText('∞');
+            } else {
+                console.log(`Ammo: ${current}/${max}`);
+                // In a real game: ammoDisplay.setText(`${current}/${max}`);
+            }
+        }
+    }
+
+    private switchToPrimary(): void {
+        if (this.currentWeapon === this.primaryWeapon) return;
+        
+        this.switchWeapon(this.primaryWeapon!);
+        console.log("Switched to assault rifle");
+        this.updateAmmoUI(); // Update UI for new weapon
+    }
+
+    private switchToSecondary(): void {
+        if (this.currentWeapon === this.secondaryWeapon) return;
+        
+        this.switchWeapon(this.secondaryWeapon!);
+        console.log("Switched to shotgun");
+        this.updateAmmoUI(); // Update UI for new weapon
+    }
+
+    private switchWeapon(newWeapon: ENGINE.ProjectileWeaponComponent): void {
+        // Remove current weapon from scene
+        if (this.currentWeapon) {
+            this.rootComponent.remove(this.currentWeapon);
+        }
+
+        // Add new weapon to scene
+        this.currentWeapon = newWeapon;
+        this.rootComponent.add(this.currentWeapon);
+    }
+
+    // Override equipment calls to only use current weapon
+    protected override callEquipment(method: keyof ENGINE.IEquipment): boolean {
+        if (this.currentWeapon && ENGINE.isEquipment(this.currentWeapon)) {
+            return this.currentWeapon[method]();
+        }
+        return false;
+    }
+}
+```
+
+### Usage Example
+
+```typescript
+class WeaponDemo extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        ENGINE.GameBuilder.createDefaultLighting(this.world);
+        ENGINE.GameBuilder.createDefaultGround(this.world);
+
+        // Create the weaponized pawn
+        const pawn = new WeaponizedPawn({
+            position: new THREE.Vector3(0, 2, 0),
+            movementComponent: new ENGINE.CharacterMovementComponent({
+                movementType: ENGINE.CharacterMovementType.FirstPerson
+            }),
+            camera: new THREE.PerspectiveCamera(75, 1, 0.1, 1000),
+            rootComponent: new ENGINE.MeshComponent({
+                geometry: new THREE.CapsuleGeometry(0.5, 2),
+                material: new THREE.MeshStandardMaterial({ color: 'blue' })
+            })
+        });
+
+        // Create controller and possess the pawn
+        const controller = new ENGINE.PlayerController();
+        controller.possess(pawn);
+
+        this.world.addActors(pawn, controller);
+    }
+}
+```
+
+---
+
+## 6. Sound and Recoil Configuration
+
+### Sound Effects
+
+Add sound to weapons with the `fireSoundUrl` parameter:
+
+```typescript
+const weapon = new ENGINE.ProjectileWeaponComponent({
+    fireSoundUrl: '@engine/assets/sounds/game-gun-short.mp3',
+    projectileOptions: {
+        // ... projectile configuration
+    }
+});
+```
+
+### Recoil Effects
+
+Configure visual recoil with the `recoilOptions` parameter:
+
+```typescript
+const weapon = new ENGINE.ProjectileWeaponComponent({
+    recoilOptions: {
+        weaponRecoilDistance: 0.1,    // How far back the weapon moves
+        weaponRecoilDuration: 0.15,   // Animation duration in seconds
+        weaponRecoilRotation: 0.05,   // Upward rotation in radians
+    },
+    projectileOptions: {
+        // ... projectile configuration
+    }
+});
+```
+
+### Complete Example
+
+```typescript
+const rifle = new ENGINE.ProjectileWeaponComponent({
+    modelPath: '@engine/assets/models/Weapons/SM_Rifle_01.glb',
+    
+    // Sound configuration
+    fireSoundUrl: '@engine/assets/sounds/game-gun-short.mp3',
+    
+    // Recoil configuration
+    recoilOptions: {
+        weaponRecoilDistance: 0.06,  // Moderate backward movement
+        weaponRecoilDuration: 0.10,  // Quick recovery
+        weaponRecoilRotation: 0.04,  // Slight upward kick
+    },
+    
+    projectileOptions: {
+        velocity: 200,
+        range: 100,
+        damageDealt: 25,
+        // ... other options
+    }
+});
+```
+
+---
+
+## 8. Advanced Equipment Concepts
+
+### Custom Equipment Types
+
+You can create equipment that doesn't fire projectiles by extending `GenericEquipment` directly:
+
+```typescript
+interface MeleeWeaponOptions extends ENGINE.GenericEquipmentOptions {
+    damage: number;
+    range: number;
+}
+
+@ENGINE.GameClass()
+class MeleeWeapon extends ENGINE.GenericEquipment<MeleeWeaponOptions> {
+    static override get DEFAULT_OPTIONS(): MeleeWeaponOptions {
+        return {
+            ...ENGINE.GenericEquipment.DEFAULT_OPTIONS,
+            fireInterval: 0.5, // Swing every 0.5 seconds
+            isSingleFire: true, // One swing per click
+            damage: 50,
+            range: 3
+        };
+    }
+
+    protected doFire(): void {
+        this.performMeleeAttack();
+    }
+
+    private performMeleeAttack(): void {
+        const world = this.getWorld();
+        if (!world) return;
+
+        // Get attack position and direction
+        const attackPosition = new THREE.Vector3();
+        const attackDirection = new THREE.Vector3();
+        this.getWorldPosition(attackPosition);
+        this.getWorldDirection(attackDirection);
+
+        // Perform raycast to find targets
+        const raycast = world.physicsEngine.raycast(
+            attackPosition,
+            attackDirection,
+            this.options.range
+        );
+
+        if (raycast.hasHit) {
+            const hitActor = raycast.hitComponent?.getActor();
+            const statsComponent = hitActor?.getComponent(ENGINE.CharacterStatsComponent);
+            
+            if (statsComponent) {
+                statsComponent.takeDamage(this.options.damage);
+                console.log(`Melee hit for ${this.options.damage} damage!`);
+            }
+        }
+    }
+}
+```
+
+### Equipment with Alternative Fire Modes
+
+```typescript
+interface DualModeWeaponOptions extends ENGINE.GenericEquipmentOptions {
+    // Add any specific options for dual mode weapons
+}
+
+@ENGINE.GameClass()
+class DualModeWeapon extends ENGINE.GenericEquipment<DualModeWeaponOptions> {
+    private isAltModeActive: boolean = false;
+
+    public override beginAltFire(): boolean {
+        this.isAltModeActive = true;
+        console.log("Switched to alternative fire mode");
+        return true;
+    }
+
+    public override endAltFire(): boolean {
+        this.isAltModeActive = false;
+        console.log("Switched back to primary fire mode");
+        return true;
+    }
+
+    protected doFire(): void {
+        if (this.isAltModeActive) {
+            this.fireAlternativeMode();
+        } else {
+            this.firePrimaryMode();
+        }
+    }
+
+    private firePrimaryMode(): void {
+        // Rapid fire bullets
+        console.log("Primary fire: rapid bullets");
+    }
+
+    private fireAlternativeMode(): void {
+        // Charged shot
+        console.log("Alternative fire: charged blast");
+    }
+}
+```
+
+### Equipment Events and Delegates
+
+Equipment components can use delegates to notify other systems of important events:
+
+```typescript
+@ENGINE.GameClass()
+class EventfulWeapon extends ENGINE.ProjectileWeaponComponent {
+    public readonly onAmmoChanged = new ENGINE.Delegate<[number, number]>(); // current, max
+    public readonly onReloadStarted = new ENGINE.Delegate<[]>();
+    public readonly onReloadCompleted = new ENGINE.Delegate<[]>();
+
+    private currentAmmo: number = 30;
+    private maxAmmo: number = 30;
+
+    protected override doFire(): void {
+        if (this.currentAmmo <= 0) {
+            console.log("Out of ammo!");
+            return;
+        }
+
+        super.doFire();
+        this.currentAmmo--;
+        this.onAmmoChanged.invoke(this.currentAmmo, this.maxAmmo);
+
+        if (this.currentAmmo === 0) {
+            this.startReload();
+        }
+    }
+
+    private startReload(): void {
+        this.onReloadStarted.invoke();
+        
+        // Use timer system for reload delay
+        this.getWorld()?.timerSystem.setTimeout(() => {
+            this.currentAmmo = this.maxAmmo;
+            this.onAmmoChanged.invoke(this.currentAmmo, this.maxAmmo);
+            this.onReloadCompleted.invoke();
+        }, 2000); // 2 second reload
+    }
+}
+```
+
+---
+
+## 7. Integration with Character Stats
+
+Equipment often needs to interact with character statistics for damage calculations, cooldowns, and other gameplay mechanics.
+
+### Using CharacterStatsComponent
+
+```typescript
+class StatsAwareWeapon extends ENGINE.ProjectileWeaponComponent {
+    constructor(options: ENGINE.ProjectileWeaponOptions) {
+        super(options);
+    }
+
+    public override beginPlay(): void {
+        super.beginPlay();
+        this.updateFromCharacterStats();
+    }
+
+    private updateFromCharacterStats(): void {
+        const actor = this.getActor();
+        const statsComponent = actor?.getComponent(ENGINE.CharacterStatsComponent);
+        
+        if (statsComponent) {
+            // Update weapon properties based on character stats
+            this.options.fireInterval = statsComponent.getAttackCooldown();
+            this.options.projectileOptions.damageDealt = statsComponent.getAttackDamage();
+            this.options.projectileOptions.range = statsComponent.getAttackRange();
+        }
+    }
+}
+```
+
+---
+
+## 8. Best Practices and Performance
+
+### Equipment Optimization
+
+1. **Reuse Projectile Geometries**: Create shared geometry instances instead of new ones for each projectile.
+2. **Limit Active Projectiles**: Implement projectile pooling for high-fire-rate weapons.
+3. **Use Appropriate Collision**: Choose between overlap and collision based on your needs.
+
+```typescript
+// Shared geometry for better performance
+const BULLET_GEOMETRY = new THREE.SphereGeometry(0.1);
+const BULLET_MATERIAL = new THREE.MeshStandardMaterial({ color: 'yellow' });
+
+const efficientWeapon = new ENGINE.ProjectileWeaponComponent({
+    projectileOptions: {
+        geometry: BULLET_GEOMETRY, // Reused
+        material: BULLET_MATERIAL, // Reused
+        // ... other options
+    }
+});
+```
+
+### Equipment Design Patterns
+
+1. **Composition over Inheritance**: Use multiple small components rather than large monolithic weapon classes.
+2. **Data-Driven Configuration**: Store weapon stats in JSON files for easy balancing.
+3. **Event-Driven Architecture**: Use delegates to decouple weapon logic from UI and other systems.
+
+---
+
+## Conclusion
+
+The Equipment and Weapon System in Genesys.js provides a robust foundation for creating interactive items in your games. By understanding the interface-based design, the timing logic of `GenericEquipment`, and the complete implementation in `ProjectileWeaponComponent`, you can create everything from simple guns to complex magical artifacts.
+
+The system's comprehensive feature set includes:
+- **Visual Effects**: Realistic recoil animations that respond to weapon characteristics
+- **Audio Integration**: Full 3D positional audio with automatic sound management
+- **Ammo Management**: Flexible ammunition systems with reload mechanics
+- **Performance Optimization**: Efficient rendering and audio processing for rapid-fire scenarios
+
+The component-based architecture means you can mix and match different behaviors, create data-driven weapon configurations, and easily extend functionality without breaking existing code. Whether you're building a first-person shooter, a fantasy RPG, or any game that needs interactive equipment, this system provides the tools you need to create engaging gameplay mechanics with professional-quality audio and visual feedback.
+
+## Source Code
+Below are relevant engine source code you MUST digest in order to get complete understanding of the topic. Read them carefully.
+
+```
+<file path={src/actors/Pawn.ts}>
+<file path={src/components/gameplay/Equipment.ts}>
+<file path={src/components/gameplay/GenericEquipment.ts}>
+<file path={src/components/gameplay/ProjectileWeaponComponent.ts}>
+<file path={src/actors/Projectile.ts}>
+```