@directivegames/genesys.js 3.1.24

package/src/components/gameplay/BaseWeaponComponent.ts

@@ -0,0 +1,597 @@
+/**
+ * BaseWeaponComponent provides common weapon functionality including visual representation,
+ * sound management, ammo system, crosshair support, and recoil effects.
+ *
+ * This base class contains all shared functionality between different weapon types like
+ * projectile weapons and instant hit weapons. It extends GenericEquipment to provide
+ * timing logic for fire actions.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Extend this class for specific weapon implementations.
+ * - Override `doFire` to implement weapon-specific firing logic.
+ * - Use `canFire` and related methods to implement custom firing conditions.
+ */
+import * as THREE from 'three';
+
+import { Pawn } from '../../actors/Pawn.js';
+import { Crosshair } from '../../ui/components/Crosshair.js';
+import { Delegate } from '../../utils/Delegate.js';
+import { SoundComponent } from '../audio/SoundComponent.js';
+import { GLTFMeshComponent } from '../visual/GLTFMeshComponent.js';
+
+import { GenericEquipment } from './GenericEquipment.js';
+
+import type { IEquipment } from './Equipment.js';
+import type { GenericEquipmentOptions } from './GenericEquipment.js';
+import type { CrosshairOptions } from '../../ui/components/Crosshair.js';
+
+export interface RecoilOptions {
+  /**
+   * Weapon model recoil distance (how far back the weapon moves)
+   */
+  weaponRecoilDistance: number;
+  /**
+   * Duration of weapon recoil animation in seconds
+   */
+  weaponRecoilDuration: number;
+  /**
+   * Weapon model recoil rotation in radians (pitch up)
+   */
+  weaponRecoilRotation: number;
+}
+
+export interface BaseWeaponOptions extends GenericEquipmentOptions {
+  /**
+   * Optional path to a 3D model for the weapon.
+   * If not provided, no visual representation will be created.
+   */
+  modelPath?: string;
+  /**
+   * Optional transform for the weapon model relative to the weapon component.
+   */
+  modelTransform?: {
+    position?: THREE.Vector3;
+    rotation?: THREE.Euler;
+    scale?: THREE.Vector3;
+  };
+
+  /**
+   * Optional offset from the weapon component's position for the fire spawn.
+   */
+  fireSpawnOffset?: THREE.Vector3;
+
+  /**
+   * Optional options for the crosshair.
+   * If provided, a crosshair will be created and displayed.
+   */
+  crosshairOptions?: CrosshairOptions;
+
+  /**
+   * Optional maximum ammo capacity.
+   * If not provided, ammo will be infinite.
+   */
+  ammoCapacity?: number;
+  /**
+   * Optional reload time in seconds.
+   */
+  reloadTime?: number;
+
+  /**
+   * Optional sound to play when the weapon is fired.
+   */
+  fireSoundUrl?: string;
+
+  /**
+   * Optional sound to play when attempting to fire with no ammo.
+   */
+  emptyFireSoundUrl?: string;
+
+  /**
+   * Optional sound to play during reload.
+   */
+  reloadSoundUrl?: string;
+
+  /**
+   * Optional recoil configuration for visual effects.
+   */
+  recoilOptions?: RecoilOptions;
+
+  /**
+   * Maximum range for target acquisition raycasting.
+   */
+  range?: number;
+}
+
+export type ReloadStartedDelegate = Delegate<[], void>;
+export type ReloadCompletedDelegate = Delegate<[], void>;
+export type BaseWeaponDefaultOptions = GenericEquipmentOptions & Partial<BaseWeaponOptions>;
+
+enum WeaponSounds {
+  Fire = 'fire',
+  EmptyFire = 'emptyFire',
+  Reload = 'reload',
+}
+
+
+export abstract class BaseWeaponComponent<TOptions extends BaseWeaponOptions> extends GenericEquipment<TOptions> implements IEquipment {
+  protected targetPosition: THREE.Vector3 | null = null;
+  protected weaponMesh: THREE.Object3D | null = null;
+  protected crosshair: Crosshair | null = null;
+
+  // Ammo management
+  protected currentAmmo: number = 0;
+  protected isReloading: boolean = false;
+  protected raycaster: THREE.Raycaster | null = null;
+  protected soundComponent: SoundComponent | null = null;
+
+  // Recoil effect properties
+  protected originalWeaponPosition: THREE.Vector3 = new THREE.Vector3();
+  protected originalWeaponRotation: THREE.Euler = new THREE.Euler();
+
+  // Reload animation properties
+  protected reloadAnimationTimer: any = null;
+
+  static override get DEFAULT_OPTIONS(): BaseWeaponDefaultOptions {
+    return {
+      ...GenericEquipment.DEFAULT_OPTIONS,
+      ammoCapacity: 0,
+      reloadTime: 2.0,
+      range: 1000,
+      recoilOptions: {
+        weaponRecoilDistance: 0.1,
+        weaponRecoilDuration: 0.15,
+        weaponRecoilRotation: 0.05,
+      },
+    };
+  }
+
+  public readonly onReloadStarted: ReloadStartedDelegate = new Delegate<[], void>();
+  public readonly onReloadCompleted: ReloadCompletedDelegate = new Delegate<[], void>();
+
+  constructor(options: TOptions) {
+    super(options);
+
+    // Initialize ammo based on capacity
+    this.currentAmmo = this.options.ammoCapacity ?? 0;
+
+    // Create the weapon visual representation
+    this.createWeaponMesh();
+  }
+
+  public override beginPlay(): void {
+    super.beginPlay();
+    const owner = this.getActor();
+    if (owner?.getPlayerController() && this.options.crosshairOptions) {
+      this.crosshair = new Crosshair(this.getWorld()!.uiManager, this.options.crosshairOptions);
+      this.crosshair.initialize();
+    }
+
+    // Setup sound component with all weapon sounds
+    const audioClips = [];
+    if (this.options.fireSoundUrl) {
+      audioClips.push({ key: WeaponSounds.Fire, audioUrl: this.options.fireSoundUrl, maxDuration: this.options.fireInterval });
+    }
+    if (this.options.emptyFireSoundUrl) {
+      audioClips.push({ key: WeaponSounds.EmptyFire, audioUrl: this.options.emptyFireSoundUrl, maxDuration: 1.0 });
+    }
+    if (this.options.reloadSoundUrl) {
+      audioClips.push({ key: WeaponSounds.Reload, audioUrl: this.options.reloadSoundUrl, maxDuration: this.options.reloadTime ?? 2.0 });
+    }
+
+    if (audioClips.length > 0) {
+      this.soundComponent = new SoundComponent({
+        audioClips: audioClips,
+      });
+      this.add(this.soundComponent);
+    }
+
+    // Store original weapon transform for recoil reset
+    if (this.weaponMesh) {
+      this.originalWeaponPosition.copy(this.weaponMesh.position);
+      this.originalWeaponRotation.copy(this.weaponMesh.rotation);
+    }
+  }
+
+  public override endPlay(): void {
+    if (this.crosshair) {
+      this.crosshair.destroy();
+      this.crosshair = null;
+    }
+
+    // Cancel any ongoing reload animation
+    if (this.reloadAnimationTimer) {
+      const world = this.getWorld();
+      if (world) {
+        world.timerSystem.clearTimer(this.reloadAnimationTimer);
+      }
+      this.reloadAnimationTimer = null;
+    }
+
+    super.endPlay();
+  }
+
+  protected createWeaponMesh(): void {
+    if (this.options.modelPath) {
+      // Load 3D model using GLTFMeshComponent
+      console.log(`Loading weapon model: ${this.options.modelPath}`);
+      const gltfComponent = new GLTFMeshComponent({
+        modelUrl: this.options.modelPath,
+        position: this.options.modelTransform?.position,
+        rotation: this.options.modelTransform?.rotation,
+        scale: this.options.modelTransform?.scale,
+        physicsOptions: {
+          enabled: false, // Disable physics for weapon visuals
+        }
+      });
+      this.weaponMesh = gltfComponent;
+      this.add(this.weaponMesh);
+    }
+  }
+
+  public tryFireAtTarget(targetPosition: THREE.Vector3): void {
+    this.targetPosition = targetPosition;
+    this.beginFire();
+    this.endFire();
+    this.targetPosition = null;
+  }
+
+  /**
+   * Override this method to add custom firing conditions.
+   * @returns true if the weapon can fire, false otherwise
+   */
+  protected canFire(): boolean {
+    // Check if reloading
+    if (this.isReloading) {
+      return false;
+    }
+
+    // Check ammo if not infinite
+    const capacity = this.options.ammoCapacity ?? 0;
+    if (capacity > 0 && this.currentAmmo <= 0) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Override this method to add custom reload conditions.
+   * @returns true if the weapon can reload, false otherwise
+   */
+  protected canReload(): boolean {
+    const capacity = this.options.ammoCapacity ?? 0;
+
+    // Can't reload infinite ammo weapons
+    if (capacity <= 0) {
+      return false;
+    }
+
+    // Can't reload if already reloading
+    if (this.isReloading) {
+      return false;
+    }
+
+    // Can't reload if already at full capacity
+    if (this.currentAmmo >= capacity) {
+      return false;
+    }
+
+    return true;
+  }
+
+  // Ammo management methods
+  public override beginFire(): boolean {
+    if (!this.canFire()) {
+      // Play empty fire sound if ammo is depleted
+      const capacity = this.options.ammoCapacity ?? 0;
+      if (capacity > 0 && this.currentAmmo <= 0 && this.soundComponent) {
+        this.soundComponent.play(WeaponSounds.EmptyFire, 1.0, true);
+      }
+      return false;
+    }
+
+    return super.beginFire();
+  }
+
+  public getCurrentAmmo(): number {
+    return this.currentAmmo;
+  }
+
+  public getMaxAmmo(): number {
+    return this.options.ammoCapacity ?? 0;
+  }
+
+  public isAmmoInfinite(): boolean {
+    return (this.options.ammoCapacity ?? 0) <= 0;
+  }
+
+  /**
+   * Sets the current ammo count directly without reloading.
+   * @param ammo The new ammo count
+   */
+  public setCurrentAmmo(ammo: number): void {
+    const capacity = this.options.ammoCapacity ?? 0;
+    if (capacity > 0) {
+      this.currentAmmo = Math.max(0, Math.min(ammo, capacity));
+    }
+  }
+
+  /**
+   * Implements IEquipment.reload() interface method.
+   * @returns true if reload was initiated, false otherwise
+   */
+  public override reload(): boolean {
+    if (this.canReload()) {
+      this.startReload();
+      return true;
+    }
+    return false;
+  }
+
+  protected startReload(): void {
+    if (!this.canReload()) {
+      return;
+    }
+
+    const capacity = this.options.ammoCapacity ?? 0;
+    this.isReloading = true;
+    console.log('Reloading weapon...');
+
+    // Emit reload started event
+    this.onReloadStarted.invoke();
+
+    // Play reload sound
+    if (this.soundComponent) {
+      this.soundComponent.play(WeaponSounds.Reload, 1.0, true);
+    }
+
+    // Start weapon rotation animation during reload
+    this.startReloadAnimation();
+
+    // Use timer system for reload
+    const world = this.getWorld();
+    if (world) {
+      world.timerSystem.setTimeout(() => {
+        this.currentAmmo = capacity;
+        this.isReloading = false;
+        console.log(`Reload complete - ${capacity} rounds ready`);
+
+        // Emit reload completed event
+        this.onReloadCompleted.invoke();
+      }, this.options.reloadTime ?? 2.0);
+    }
+  }
+
+  /**
+   * Starts weapon rotation animation during reload
+   */
+  protected startReloadAnimation(): void {
+    if (!this.weaponMesh) {
+      return;
+    }
+
+    const world = this.getWorld();
+    if (!world) {
+      return;
+    }
+
+    // Cancel any existing reload animation
+    if (this.reloadAnimationTimer) {
+      world.timerSystem.clearTimer(this.reloadAnimationTimer);
+    }
+
+    const reloadDuration = this.options.reloadTime ?? 2.0;
+    const startTime = world.getGameTime();
+
+    this.reloadAnimationTimer = world.timerSystem.setInterval(() => {
+      if (!this.weaponMesh || !this.isReloading) {
+        if (this.reloadAnimationTimer) {
+          world.timerSystem.clearTimer(this.reloadAnimationTimer);
+          this.reloadAnimationTimer = null;
+        }
+        return;
+      }
+
+      const currentTime = world.getGameTime();
+      const elapsed = currentTime - startTime;
+      const progress = Math.min(elapsed / reloadDuration, 1);
+
+      // Create a smooth rotation animation - rotate around Y axis (spin)
+      const rotationAmount = Math.sin(progress * Math.PI * 2) * 0.3; // Oscillating rotation
+      this.weaponMesh.rotation.y = this.originalWeaponRotation.y + rotationAmount;
+
+      // Also add a slight tilt animation
+      const tiltAmount = Math.sin(progress * Math.PI * 4) * 0.1; // Faster oscillation for tilt
+      this.weaponMesh.rotation.z = this.originalWeaponRotation.z + tiltAmount;
+
+      // Clean up when reload is complete
+      if (progress >= 1 || !this.isReloading) {
+        // Reset weapon to original rotation
+        this.weaponMesh.rotation.copy(this.originalWeaponRotation);
+        world.timerSystem.clearTimer(this.reloadAnimationTimer);
+        this.reloadAnimationTimer = null;
+      }
+    }, 1 / 60); // 60 FPS animation
+  }
+
+  /**
+   * Gets the target location by shooting a ray from the center of the camera
+   * @param maxDistance Maximum distance for the raycast
+   * @returns The world position where the ray intersects with objects, or null if no intersection is found
+   */
+  public getTargetLocationFromCamera(maxDistance: number): THREE.Vector3 | null {
+    const world = this.getWorld();
+    const actor = this.getActor();
+    if (!world || !actor) {
+      return null;
+    }
+
+    // Get the active camera
+    const camera = actor.getComponent(THREE.Camera);
+    if (!camera) {
+      return null;
+    }
+
+    const cameraPosition = camera.getWorldPosition();
+    const cameraDirection = new THREE.Vector3(0, 0, 0);
+    camera.getWorldDirection(cameraDirection);
+
+    const hitTestResult = this.getPhysicsEngine()?.performHitTest({
+      origin: cameraPosition,
+      direction: cameraDirection,
+      maxDistance: maxDistance,
+      stopOnFirstHit: true,
+      ignoredActors: [actor],
+    });
+
+    return hitTestResult?.[0]?.hitLocation ?? null;
+  }
+
+  /**
+   * Applies visual recoil effects including camera shake and weapon model animation
+   */
+  protected applyRecoilEffects(): void {
+    const recoilOptions = this.options.recoilOptions;
+    if (!recoilOptions) {
+      return;
+    }
+    const world = this.getWorld();
+    const actor = this.getActor();
+
+    if (!world || !actor) return;
+
+    // Apply weapon model recoil (can overlap for rapid fire effect)
+    this.applyWeaponRecoil(recoilOptions);
+  }
+
+  /**
+   * Applies weapon model recoil animation
+   */
+  protected applyWeaponRecoil(recoilOptions: RecoilOptions): void {
+    if (!this.weaponMesh) {
+      return;
+    }
+
+    const recoilDistance = recoilOptions.weaponRecoilDistance;
+    const recoilRotation = recoilOptions.weaponRecoilRotation;
+    const duration = recoilOptions.weaponRecoilDuration;
+    const world = this.getWorld();
+
+    if (!world || recoilDistance <= 0) {
+      return;
+    }
+
+    // Get current weapon position (might be mid-recoil from previous shot)
+    const currentPosition = this.weaponMesh.position.clone();
+    const currentRotation = this.weaponMesh.rotation.clone();
+
+    // Calculate recoil target position (move backward along local Z axis)
+    const recoilTargetPosition = this.originalWeaponPosition.clone();
+    recoilTargetPosition.z += recoilDistance;
+
+    // Calculate recoil target rotation (pitch up)
+    const recoilTargetRotation = this.originalWeaponRotation.clone();
+    recoilTargetRotation.x -= recoilRotation;
+
+    // Use faster animation for rapid fire (minimum 30fps for smoothness)
+    const minStepDuration = 1 / 30;
+    const animationSteps = Math.max(Math.floor(duration * 60), 2); // At least 2 steps
+    const stepDuration = Math.max(duration / animationSteps, minStepDuration);
+    let currentStep = 0;
+
+    const recoilTimer = world.timerSystem.setInterval(() => {
+      currentStep++;
+      const progress = currentStep / animationSteps;
+
+      if (progress <= 0.4) {
+        // First 40% of animation: quick snap to recoil position
+        const recoilProgress = progress / 0.4;
+        // Use ease-out for snappy recoil
+        const easedProgress = 1 - Math.pow(1 - recoilProgress, 2);
+        this.weaponMesh!.position.lerpVectors(currentPosition, recoilTargetPosition, easedProgress);
+        this.weaponMesh!.rotation.x = THREE.MathUtils.lerp(currentRotation.x, recoilTargetRotation.x, easedProgress);
+      } else {
+        // Remaining 60% of animation: smooth return to original position
+        const returnProgress = (progress - 0.4) / 0.6;
+        // Use ease-in for smooth return
+        const easedProgress = returnProgress * returnProgress;
+        this.weaponMesh!.position.lerpVectors(recoilTargetPosition, this.originalWeaponPosition, easedProgress);
+        this.weaponMesh!.rotation.x = THREE.MathUtils.lerp(recoilTargetRotation.x, this.originalWeaponRotation.x, easedProgress);
+      }
+
+      // Stop animation when complete
+      if (progress >= 1) {
+        world.timerSystem.clearTimer(recoilTimer);
+        // Ensure weapon is back to original position
+        this.weaponMesh!.position.copy(this.originalWeaponPosition);
+        this.weaponMesh!.rotation.copy(this.originalWeaponRotation);
+      }
+    }, stepDuration);
+  }
+
+  /**
+   * Consumes ammo and handles reload logic. Call this from doFire implementations.
+   */
+  protected consumeAmmo(): void {
+    // Consume ammo if not infinite
+    const capacity = this.options.ammoCapacity ?? 0;
+    if (capacity > 0) {
+      this.currentAmmo--;
+
+      if (this.currentAmmo <= 0) {
+        this.startReload();
+      }
+    }
+  }
+
+  /**
+   * Plays the fire sound. Call this from doFire implementations.
+   */
+  protected playFireSound(): void {
+    if (this.soundComponent) {
+      this.soundComponent.play(WeaponSounds.Fire, 1.0, true);
+    }
+  }
+
+  /**
+   * Gets the fire position and direction for this weapon.
+   * Override this method to customize spawn point offset from the component's transform.
+   */
+  protected getFirePositionAndDirection(): { position: THREE.Vector3, direction: THREE.Vector3 } {
+    const worldPosition = new THREE.Vector3();
+    const worldDirection = new THREE.Vector3();
+    this.getWorldPosition(worldPosition);
+
+    const camera = this.getActor()?.getComponent(THREE.Camera);
+    if (camera) {
+      camera.getWorldDirection(worldDirection);
+    } else {
+      this.getWorldDirection(worldDirection);
+    }
+
+    if (this.options.fireSpawnOffset) {
+      worldPosition.add(this.options.fireSpawnOffset.clone().applyQuaternion(this.getWorldQuaternion()));
+    }
+    return { position: worldPosition, direction: worldDirection };
+  }
+
+  /**
+   * Gets the effective target direction based on target position or camera aim.
+   */
+  protected getTargetDirection(): THREE.Vector3 | null {
+    const { position } = this.getFirePositionAndDirection();
+    const targetPosition = this.targetPosition ?? this.getTargetLocationFromCamera(this.options.range ?? 1000);
+    if (targetPosition) {
+      return targetPosition.clone().sub(position).normalize();
+    }
+    return null;
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_Weapon';
+  }
+}