FixedWingModel.ts

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (c) 2025-2026 Matthew Kissinger

import * as THREE from 'three';
import type { GameSystem } from '../../types';
import type { ITerrainRuntime, IHUDSystem, IPlayerController } from '../../types/SystemInterfaces';
import type { VehicleManager } from './VehicleManager';
import { Airframe } from './airframe/Airframe';
import type { AirframeIntent, AirframeTerrainProbe } from './airframe/types';
import { createFlatTerrainProbe, createRuntimeTerrainProbe } from './airframe/terrainProbe';
import {
  airframeConfigFromLegacy,
  airframeStateToFixedWingSnapshot,
  fixedWingFlightStateFromSnapshot,
} from './FixedWingTypes';
import type {
  FixedWingCommand,
  FixedWingFlightPhase,
  FixedWingFlightSnapshot,
  FixedWingFlightState,
} from './FixedWingTypes';
import { FixedWingAnimation } from './FixedWingAnimation';
import { FixedWingInteraction } from './FixedWingInteraction';
import { FixedWingVehicleAdapter } from './FixedWingVehicleAdapter';
import { shouldRenderAirVehicle, shouldSimulateAirVehicle } from './AirVehicleVisibility';
import {
  buildFixedWingPilotCommand,
  createIdleFixedWingPilotIntent,
  deriveFixedWingControlPhase,
} from './FixedWingControlLaw';
import type { FixedWingControlPhase, FixedWingPilotIntent } from './FixedWingControlLaw';
import { NPCFixedWingPilot } from './NPCFixedWingPilot';
import type { Mission as NPCPilotMission, TerrainProbe as NPCTerrainProbe } from './NPCFixedWingPilot';
import {
  deriveFixedWingOperationState,
  getFixedWingExitStatus,
} from './FixedWingOperations';
import type {
  FixedWingOperationState,
  FixedWingSpawnMetadata,
} from './FixedWingOperations';
import {
  FIXED_WING_CONFIGS,
  getFixedWingConfigKeyForModelPath,
  getFixedWingDisplayInfo,
} from './FixedWingConfigs';
import type { FixedWingDisplayInfo } from './FixedWingConfigs';
import type { VehicleExitOptions, VehicleExitPlan, VehicleExitResult } from './PlayerVehicleAdapter';
import { modelLoader } from '../assets/ModelLoader';
import { Faction } from '../combat/types';
import type { CombatantSystem } from '../combat/CombatantSystem';
import { TracerPool } from '../effects/TracerPool';
import { Logger } from '../../utils/Logger';
import { computeFixedWingShot, getFixedWingWeaponConfig } from './FixedWingArmament';
import type { FixedWingWeaponConfig } from './FixedWingArmament';
import { optimizeFixedWingStaticDrawCalls } from './FixedWingRenderOptimization';

const FIXED_WING_GUN_TRACER_RANGE = 500;

interface FixedWingWeaponState {
  /** Per-airframe armament config (geometry, spread, cadence, magazine). */
  config: FixedWingWeaponConfig;
  ammo: number;
  cooldownRemaining: number;
  roundsSinceTracer: number;
  /** Round-robin barrel cursor (paired wing cannons / broadside battery). */
  barrelIndex: number;
  isFiring: boolean;
  faction: Faction;
}

const _gunMuzzle = new THREE.Vector3();
const _gunForward = new THREE.Vector3();
const _gunTracerEnd = new THREE.Vector3();
const _gunRay = new THREE.Ray();
const _gunSpreadRight = new THREE.Vector3();
const _gunSpreadUp = new THREE.Vector3();

interface AircraftRuntime {
  airframe: Airframe;
  /**
   * Pending command fed to the Airframe each update. Latest gameplay-side
   * command, translated to an `AirframeIntent` at step time.
   */
  command: FixedWingCommand;
  worldHalfExtent: number;
}

type VehicleExitRequester = {
  requestVehicleExit?: (options?: VehicleExitOptions) => VehicleExitResult;
};

interface FixedWingFlightData {
  airspeed: number;
  heading: number;
  verticalSpeed: number;
  altitude: number;
  altitudeAGL: number;
  controlPhase: FixedWingControlPhase;
  operationState: FixedWingOperationState;
  phase: FixedWingFlightPhase;
  aoaDeg: number;
  sideslipDeg: number;
  throttle: number;
  brake: number;
  weightOnWheels: boolean;
  isStalled: boolean;
  flightState: FixedWingFlightState;
  stallSpeed: number;
  pitch: number;
  roll: number;
  orbitHoldEnabled: boolean;
  configKey: string | null;
}

function createIdleCommand(): FixedWingCommand {
  return {
    throttleTarget: 0,
    pitchCommand: 0,
    rollCommand: 0,
    yawCommand: 0,
    brake: 0,
    freeLook: false,
    stabilityAssist: false,
  };
}

/**
 * Translate a gameplay-side `FixedWingCommand` into an `AirframeIntent`.
 * `stabilityAssist` maps to `tier: 'assist' | 'raw'` (the `feel` config scales
 * are neutralized in `airframeConfigFromLegacy` so command values flow through
 * unchanged); `brake` is clamped at ground-tier by the Airframe command builder.
 */
function commandToAirframeIntent(cmd: FixedWingCommand): AirframeIntent {
  return {
    pitch: cmd.pitchCommand,
    roll: cmd.rollCommand,
    yaw: cmd.yawCommand,
    throttle: cmd.throttleTarget,
    brake: cmd.brake,
    tier: cmd.stabilityAssist ? 'assist' : 'raw',
  };
}

function sanitizeCommand(command: Partial<FixedWingCommand>, base: FixedWingCommand): FixedWingCommand {
  const next: FixedWingCommand = { ...base };
  if (command.throttleTarget !== undefined) {
    next.throttleTarget = THREE.MathUtils.clamp(command.throttleTarget, 0, 1);
  }
  if (command.pitchCommand !== undefined) {
    next.pitchCommand = THREE.MathUtils.clamp(command.pitchCommand, -1, 1);
  }
  if (command.rollCommand !== undefined) {
    next.rollCommand = THREE.MathUtils.clamp(command.rollCommand, -1, 1);
  }
  if (command.yawCommand !== undefined) {
    next.yawCommand = THREE.MathUtils.clamp(command.yawCommand, -1, 1);
  }
  if (command.brake !== undefined) {
    next.brake = THREE.MathUtils.clamp(command.brake, 0, 1);
  }
  if (command.freeLook !== undefined) {
    next.freeLook = command.freeLook;
  }
  if (command.stabilityAssist !== undefined) {
    next.stabilityAssist = command.stabilityAssist;
  }
  return next;
}

/**
 * Optional airborne-hint sink on the concrete HUD. Accessed structurally (the
 * same way the adapter reaches `updateFixedWingAmmo`) so the model does not
 * have to widen the fenced `IHUDSystem` for a UI-only nicety — a HUD that lacks
 * the method simply shows no hint.
 */
interface FixedWingAirborneHintSink {
  flashFixedWingAirborneHint?(): void;
}

/**
 * Orchestrates all fixed-wing aircraft instances.
 * Parallel to HelicopterModel; each airframe carries its own gun from the
 * armament table (A-1 wing cannons, F-4 nose rotary, AC-47 broadside; no door
 * gunners).
 */
export class FixedWingModel implements GameSystem {
  private static readonly IDLE_SIMULATION_SPEED = 0.5;
  private scene: THREE.Scene;
  private animation = new FixedWingAnimation();
  private interaction: FixedWingInteraction;

  // Per-aircraft state
  private groups = new Map<string, THREE.Group>();
  private runtimes = new Map<string, AircraftRuntime>();
  private configKeys = new Map<string, string>();
  private displayNames = new Map<string, string>();
  private collisionRegistered = new Set<string>();
  private spawnMetadata = new Map<string, FixedWingSpawnMetadata>();
  private lineupAircraft = new Set<string>();
  /**
   * Per-aircraft latched sim-cull state. `true` means we simulated last frame,
   * `false` means we were culled. Drives the hysteresis band in
   * `shouldSimulateAirVehicle`. Aircraft default to `true` (simulate) until we
   * have evidence they should be culled.
   */
  private simulating = new Map<string, boolean>();
  private pilotedAircraftId: string | null = null;
  /** NPC pilots attached to aircraft in our catalog. See `attachNPCPilot()`. */
  private npcPilots = new Map<string, NPCFixedWingPilot>();

  // Dependencies
  private terrainManager?: ITerrainRuntime;
  private terrainProbe: AirframeTerrainProbe = createFlatTerrainProbe(0);
  private playerController?: IPlayerController;
  private hudSystem?: IHUDSystem;
  private vehicleManager?: VehicleManager;
  private combatantSystem?: CombatantSystem;

  // Forward armament: per-aircraft weapon state + a small shared tracer pool.
  private weapons = new Map<string, FixedWingWeaponState>();
  private tracerPool?: TracerPool;

  // Airborne-gate feedback: set when the player holds the trigger while the
  // aircraft is still grounded (the gun silently no-ops there). The HUD reads
  // and clears this each frame to surface a transient "Airborne to fire" hint
  // instead of nothing. Internal signal only — not a fired round, not a gate
  // change.
  private groundedFireBlocked = false;

  // Controls from player input
  private currentPilotIntent: FixedWingPilotIntent = createIdleFixedWingPilotIntent();
  private currentCommand: FixedWingCommand = createIdleCommand();
  private pilotIntentActive = false;

  constructor(scene: THREE.Scene) {
    this.scene = scene;
    this.interaction = new FixedWingInteraction(this.groups, this.displayNames, this.configKeys);
  }

  // -- Dependency setters --

  setTerrainManager(terrainManager: ITerrainRuntime): void {
    this.terrainManager = terrainManager;
    this.terrainProbe = createRuntimeTerrainProbe(terrainManager);
    this.interaction.setTerrainManager(terrainManager);
  }

  setPlayerController(playerController: IPlayerController): void {
    this.playerController = playerController;
    this.interaction.setPlayerController(playerController);
  }

  setHUDSystem(hudSystem: IHUDSystem): void {
    this.hudSystem = hudSystem;
    this.interaction.setHUDSystem(hudSystem);
  }

  setVehicleManager(vehicleManager: VehicleManager): void {
    this.vehicleManager = vehicleManager;
  }

  setCombatantSystem(combatantSystem: CombatantSystem): void {
    this.combatantSystem = combatantSystem;
  }

  // -- GameSystem lifecycle --

  async init(): Promise<void> {
    Logger.info('fixedwing', 'FixedWingModel initialized');
  }

  update(deltaTime: number): void {
    // Update interaction prompts
    this.interaction.checkPlayerProximity();

    const camera = this.playerController && typeof this.playerController.getCamera === 'function'
      ? this.playerController.getCamera()
      : null;

    for (const [aircraftId, runtime] of this.runtimes) {
      const group = this.groups.get(aircraftId);
      if (!group) {
        continue;
      }

      const isPiloted = aircraftId === this.pilotedAircraftId;
      const npcPilot = !isPiloted ? this.npcPilots.get(aircraftId) : undefined;
      const snapshot = this.buildSnapshot(runtime);
      const flightState = fixedWingFlightStateFromSnapshot(snapshot);
      const needsStep = isPiloted
        || npcPilot !== undefined
        || flightState !== 'grounded'
        || snapshot.airspeed > FixedWingModel.IDLE_SIMULATION_SPEED;

      // Distance cull gate: parked / idle unpiloted aircraft beyond the render
      // cull distance (plus hysteresis) are removed from the physics path
      // entirely. Airborne NPC aircraft stay simulated regardless of distance.
      const wasSimulating = this.simulating.get(aircraftId) ?? true;
      const withinSimRange = shouldSimulateAirVehicle({
        camera,
        scene: this.scene,
        vehiclePosition: group.position,
        isAirborne: flightState !== 'grounded',
        isPiloted,
        hasActiveNPCPilot: npcPilot !== undefined,
        currentlySimulating: wasSimulating,
      });
      const shouldSimulate = needsStep && withinSimRange;

      if (shouldSimulate !== wasSimulating) {
        this.simulating.set(aircraftId, shouldSimulate);
        if (!shouldSimulate) {
          // Freeze residual velocity so when sim resumes the airframe does not
          // jump on the first step. Position and quaternion are already the
          // last-simulated values; skipping step() leaves them untouched.
          runtime.airframe.getVelocity().set(0, 0, 0);
          Logger.debug('fixedwing', `simulation culled: ${aircraftId} (distance gate)`);
        } else {
          Logger.debug('fixedwing', `simulation resumed: ${aircraftId}`);
        }
      }

      if (isPiloted) {
        const configKey = this.configKeys.get(aircraftId);
        const config = configKey ? FIXED_WING_CONFIGS[configKey] : null;
        if (config && this.pilotIntentActive) {
          const position = runtime.airframe.getPosition();
          runtime.command = sanitizeCommand(
            buildFixedWingPilotCommand(
              snapshot,
              config.physics,
              config.pilotProfile,
              this.currentPilotIntent,
              { positionX: position.x, positionZ: position.z },
            ),
            runtime.command,
          );
        } else {
          runtime.command = sanitizeCommand(this.currentCommand, runtime.command);
        }
      } else if (npcPilot && shouldSimulate) {
        const configKey = this.configKeys.get(aircraftId);
        const config = configKey ? FIXED_WING_CONFIGS[configKey] : null;
        const airframeState = runtime.airframe.getState();
        const pilotIntent = npcPilot.update(deltaTime, airframeState);
        if (pilotIntent && config) {
          const position = runtime.airframe.getPosition();
          runtime.command = sanitizeCommand(
            buildFixedWingPilotCommand(
              snapshot,
              config.physics,
              config.pilotProfile,
              pilotIntent,
              { positionX: position.x, positionZ: position.z },
            ),
            runtime.command,
          );
        } else {
          runtime.command = sanitizeCommand({
            throttleTarget: 0,
            pitchCommand: 0,
            rollCommand: 0,
            yawCommand: 0,
            brake: 1,
          }, runtime.command);
        }
      } else if (shouldSimulate) {
        runtime.command = sanitizeCommand({
          throttleTarget: 0,
          pitchCommand: 0,
          rollCommand: 0,
          yawCommand: 0,
          brake: runtime.command.brake > 0 ? runtime.command.brake : 0,
        }, runtime.command);
      }

      if (shouldSimulate) {
        runtime.airframe.step(
          commandToAirframeIntent(runtime.command),
          this.terrainProbe,
          deltaTime,
        );

        const postSnapshot = this.buildSnapshot(runtime);
        const configKey = this.configKeys.get(aircraftId);
        const config = configKey ? FIXED_WING_CONFIGS[configKey] : null;
        if (config && (postSnapshot.airspeed > config.operation.taxiSpeedMax || !postSnapshot.weightOnWheels)) {
          this.lineupAircraft.delete(aircraftId);
        }

        const visualState = runtime.airframe.getInterpolatedState();
        group.position.copy(visualState.position);
        group.quaternion.copy(visualState.quaternion);
      }

      const currentSnapshot = shouldSimulate ? this.buildSnapshot(runtime) : snapshot;
      const currentFlightState = fixedWingFlightStateFromSnapshot(currentSnapshot);

      // Forward cannon: only the player-piloted aircraft can pull the trigger.
      // Gated to airborne flight so a parked aircraft can't strafe the apron.
      if (isPiloted) {
        this.updateForwardGun(
          aircraftId,
          group,
          currentFlightState !== 'grounded',
          deltaTime,
        );
        // Surface the airborne-gate feedback: if the player held the trigger
        // while grounded this frame, flash a transient HUD hint so the silent
        // no-op reads as "not yet" instead of a broken gun.
        if (this.consumeGroundedFireBlocked()) {
          (this.hudSystem as FixedWingAirborneHintSink | undefined)
            ?.flashFixedWingAirborneHint?.();
        }
      }

      const shouldRender = shouldRenderAirVehicle({
        camera,
        scene: this.scene,
        vehiclePosition: group.position,
        isAirborne: currentFlightState !== 'grounded',
        isPiloted,
        currentlyVisible: group.visible,
      });
      group.visible = shouldRender;

      if (shouldRender) {
        // Parked unpiloted aircraft (no pilot, grounded, near-zero airspeed) freeze
        // their propellers so flying past idle aircraft on the airfield doesn't show
        // them spinning.
        const isAircraftActive = isPiloted
          || npcPilot !== undefined
          || currentFlightState !== 'grounded'
          || currentSnapshot.airspeed > FixedWingModel.IDLE_SIMULATION_SPEED;
        this.animation.update(aircraftId, currentSnapshot.throttle, deltaTime, isAircraftActive);
      }

      if (isPiloted && this.playerController) {
        // Feed the interpolated visual pose (`group.position`), not raw physics,
        // so the camera, HUD readouts, and downstream consumers share one time
        // base — raw physics aliased the fixed-step sawtooth at high refresh.
        this.playerController.updatePlayerPosition(group.position);
      }
    }

    // Sweep expired tracers (no-op until the cannon has actually fired).
    this.tracerPool?.update();
  }

  dispose(): void {
    for (const [id, group] of this.groups) {
      if (this.collisionRegistered.has(id)) {
        this.terrainManager?.unregisterCollisionObject(id);
      }
      this.scene.remove(group);
      group.traverse((node) => {
        if (!(node instanceof THREE.Mesh)) {
          return;
        }
        if (node.userData.generatedMergedGeometry === true) {
          node.geometry.dispose();
          if (Array.isArray(node.material)) {
            node.material.forEach((material) => material.dispose());
          } else {
            node.material.dispose();
          }
        }
      });
      this.animation.dispose(id);
    }
    this.groups.clear();
    this.runtimes.clear();
    this.configKeys.clear();
    this.displayNames.clear();
    this.collisionRegistered.clear();
    this.spawnMetadata.clear();
    this.lineupAircraft.clear();
    this.simulating.clear();
    this.weapons.clear();
    this.tracerPool?.dispose();
    this.tracerPool = undefined;
    for (const pilot of this.npcPilots.values()) pilot.clearMission();
    this.npcPilots.clear();
  }

  // -- Aircraft creation --

  /**
   * Create an interactive fixed-wing aircraft at a parking spot.
   * Called by the airfield layout system instead of placing a static model.
   */
  async createAircraftAtSpot(
    id: string,
    modelPath: string,
    worldPosition: THREE.Vector3,
    heading: number,
    metadata?: FixedWingSpawnMetadata,
  ): Promise<boolean> {
    const configKey = getFixedWingConfigKeyForModelPath(modelPath);
    if (!configKey) {
      Logger.warn('fixedwing', `No config for model path: ${modelPath}`);
      return false;
    }

    const config = FIXED_WING_CONFIGS[configKey];
    if (!config) {
      Logger.warn('fixedwing', `No physics config for key: ${configKey}`);
      return false;
    }

    const display = getFixedWingDisplayInfo(configKey);
    if (!display) return false;

    try {
      const { scene: innerModel, animations } = await modelLoader.loadAnimatedModel(modelPath);
      // Most GLBs face +Z but physics forward is -Z, so default to a 180° Y flip.
      // Per-aircraft override (`modelYawOffset` on FixedWingDisplayInfo) handles
      // GLBs authored facing -Z (e.g. A-1 Skyraider) — they override to 0.
      innerModel.rotation.y = display.modelYawOffset ?? Math.PI;
      this.optimizeLoadedAircraft(innerModel, configKey);

      // Outer group is driven by physics quaternion (position + attitude).
      // Inner model handles the visual-to-physics rotation offset.
      const group = new THREE.Group();
      group.add(innerModel);
      group.position.copy(worldPosition);

      // Ensure Y is on terrain (use physics gearClearance instead of hardcoded offset)
      if (this.terrainManager) {
        const h = this.terrainManager.getHeightAt(worldPosition.x, worldPosition.z);
        group.position.y = h + config.physics.gearClearance;
        worldPosition.y = h + config.physics.gearClearance;
      }

      this.scene.add(group);
      this.groups.set(id, group);
      this.configKeys.set(id, configKey);
      this.displayNames.set(id, display.displayName);
      if (metadata) {
        this.spawnMetadata.set(id, {
          standId: metadata.standId,
          taxiRoute: metadata.taxiRoute.map((point) => point.clone()),
          runwayStart: metadata.runwayStart
            ? {
                id: metadata.runwayStart.id,
                position: metadata.runwayStart.position.clone(),
                heading: metadata.runwayStart.heading,
                holdShortPosition: metadata.runwayStart.holdShortPosition?.clone(),
                shortFinalDistance: metadata.runwayStart.shortFinalDistance,
                shortFinalAltitude: metadata.runwayStart.shortFinalAltitude,
              }
            : undefined,
        });
      }
      if (this.terrainManager) {
        this.terrainManager.registerCollisionObject(id, group, { dynamic: true });
        this.collisionRegistered.add(id);
      }

      // Build the airframe instance (starts parked on the ground).
      const airframe = new Airframe(worldPosition.clone(), airframeConfigFromLegacy(config.physics));
      // Set initial heading on the airframe quaternion.
      const q = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), heading);
      airframe.getQuaternion().copy(q);
      // Sync group to initial physics state so parked aircraft face the right way.
      group.quaternion.copy(q);

      let worldHalfExtent = 0;
      if (this.terrainManager) {
        worldHalfExtent = this.terrainManager.getPlayableWorldSize() / 2;
        airframe.setWorldHalfExtent(worldHalfExtent);
      }

      this.runtimes.set(id, {
        airframe,
        command: createIdleCommand(),
        worldHalfExtent,
      });

      // Forward armament: each airframe pulls its own weapon config from the
      // armament table (A-1 wing cannons, F-4 nose rotary, AC-47 broadside).
      // US-owned (matching the adapter faction) so friend-or-foe filtering
      // spares allies.
      const weaponConfig = getFixedWingWeaponConfig(configKey);
      this.weapons.set(id, {
        config: weaponConfig,
        ammo: weaponConfig.ammoCapacity,
        cooldownRemaining: 0,
        roundsSinceTracer: 0,
        barrelIndex: 0,
        isFiring: false,
        faction: Faction.US,
      });

      // Wire animation on the inner model (where propeller nodes live)
      this.animation.initialize(id, configKey, innerModel, animations);

      // Register with VehicleManager
      if (this.vehicleManager) {
        const adapter = new FixedWingVehicleAdapter(id, configKey, Faction.US, this);
        this.vehicleManager.register(adapter);
      }

      Logger.info('fixedwing', `Created ${display.displayName} at (${worldPosition.x.toFixed(0)}, ${worldPosition.z.toFixed(0)})`);
      return true;
    } catch (err) {
      Logger.warn('fixedwing', `Failed to load model ${modelPath}: ${err}`);
      return false;
    }
  }

  private optimizeLoadedAircraft(innerModel: THREE.Group, configKey: string): void {
    const display = getFixedWingDisplayInfo(configKey);
    const propellerNames = new Set(
      (display?.propellerNodes ?? []).map((name) => name.toLowerCase()),
    );
    const result = optimizeFixedWingStaticDrawCalls(innerModel, configKey, propellerNames);

    if (result.sourceMeshCount > 0) {
      Logger.info(
        'fixedwing',
        `Optimized ${configKey} draw calls: ${result.sourceMeshCount} leaf meshes -> ${result.mergedMeshCount} batches`,
      );
    }
  }

  // -- Player interaction --

  tryEnterAircraft(): boolean {
    return this.interaction.tryEnterAircraft();
  }

  getPlayerExitPlan(aircraftId: string | null, options: VehicleExitOptions = {}): VehicleExitPlan | null {
    if (!aircraftId) {
      return { canExit: false, message: 'Cannot find aircraft for exit.' };
    }

    const group = this.groups.get(aircraftId);
    if (!group) {
      return { canExit: false, message: 'Cannot find aircraft for exit.' };
    }

    const normalPosition = this.buildAircraftExitPosition(group, false);
    if (options.force) {
      return { canExit: true, mode: 'force_cleanup', position: normalPosition };
    }

    const flightData = this.getFlightData(aircraftId);
    const configKey = this.configKeys.get(aircraftId);
    const config = configKey ? FIXED_WING_CONFIGS[configKey] : null;
    if (!flightData || !config) {
      return { canExit: true, mode: 'normal', position: normalPosition };
    }

    const exitStatus = getFixedWingExitStatus({
      weightOnWheels: flightData.weightOnWheels,
      airspeed: flightData.airspeed,
      altitudeAGL: flightData.altitudeAGL,
    }, config);
    if (exitStatus.canExit) {
      return { canExit: true, mode: 'normal', position: normalPosition };
    }

    if (options.allowEject) {
      return {
        canExit: true,
        mode: 'emergency_eject',
        position: this.buildAircraftEjectionPosition(group),
        message: 'Emergency bailout.',
      };
    }

    return {
      canExit: false,
      message: exitStatus.message ?? 'Cannot exit aircraft yet.',
      position: normalPosition,
    };
  }

  exitAircraft(): void {
    const exitRequester = this.playerController as (IPlayerController & VehicleExitRequester) | undefined;
    if (typeof exitRequester?.requestVehicleExit === 'function') {
      const result = exitRequester.requestVehicleExit({ allowEject: false, reason: 'fixed-wing-model' });
      if (result.exited || result.reason === 'blocked') {
        return;
      }
    }

    if (this.pilotedAircraftId) {
      const flightData = this.getFlightData(this.pilotedAircraftId);
      const configKey = this.configKeys.get(this.pilotedAircraftId);
      const config = configKey ? FIXED_WING_CONFIGS[configKey] : null;
      if (flightData && config) {
        const exitStatus = getFixedWingExitStatus({
          weightOnWheels: flightData.weightOnWheels,
          airspeed: flightData.airspeed,
          altitudeAGL: flightData.altitudeAGL,
        }, config);
        if (!exitStatus.canExit) {
          this.hudSystem?.showMessage(exitStatus.message ?? 'Cannot exit aircraft yet.', 2000);
          return;
        }
      }
    }
    this.pilotedAircraftId = null;
    this.currentCommand = createIdleCommand();
    this.currentPilotIntent = createIdleFixedWingPilotIntent();
    this.pilotIntentActive = false;
    this.interaction.exitAircraft();
  }

  private buildAircraftExitPosition(group: THREE.Group, projectToGround: boolean): THREE.Vector3 {
    const exitPosition = group.position.clone();
    const rightVector = new THREE.Vector3(1, 0, 0).applyQuaternion(group.quaternion);
    const aftVector = new THREE.Vector3(0, 0, 1).applyQuaternion(group.quaternion);
    exitPosition.addScaledVector(rightVector, projectToGround ? 7 : 4);
    if (projectToGround) {
      exitPosition.addScaledVector(aftVector, 6);
    }

    if (this.terrainManager) {
      const terrainHeight = this.terrainManager.getEffectiveHeightAt(exitPosition.x, exitPosition.z);
      exitPosition.y = projectToGround
        ? terrainHeight + 1.5
        : Math.max(exitPosition.y, terrainHeight + 1.5);
    }

    return exitPosition;
  }

  private buildAircraftEjectionPosition(group: THREE.Group): THREE.Vector3 {
    const exitPosition = group.position.clone();
    const rightVector = new THREE.Vector3(1, 0, 0).applyQuaternion(group.quaternion);
    const aftVector = new THREE.Vector3(0, 0, 1).applyQuaternion(group.quaternion);
    exitPosition.addScaledVector(rightVector, 7);
    exitPosition.addScaledVector(aftVector, 6);

    if (this.terrainManager) {
      const terrainHeight = this.terrainManager.getEffectiveHeightAt(exitPosition.x, exitPosition.z);
      exitPosition.y = Math.max(exitPosition.y, terrainHeight + 1.5);
    }

    return exitPosition;
  }

  setPilotedAircraft(aircraftId: string | null): void {
    this.pilotedAircraftId = aircraftId;
    this.currentCommand = createIdleCommand();
    this.currentPilotIntent = createIdleFixedWingPilotIntent();
    this.pilotIntentActive = false;

    // Reset physics for parked aircraft to prevent stale micro-drift
    if (aircraftId) {
      const runtime = this.runtimes.get(aircraftId);
      if (runtime) {
        const snapshot = this.buildSnapshot(runtime);
        if (snapshot.phase === 'parked') {
          runtime.airframe.resetToGround(runtime.airframe.getPosition());
          runtime.command = createIdleCommand();
          if (runtime.worldHalfExtent > 0) {
            runtime.airframe.setWorldHalfExtent(runtime.worldHalfExtent);
          }
          // Restore heading from the group quaternion
          const group = this.groups.get(aircraftId);
          if (group) {
            runtime.airframe.getQuaternion().copy(group.quaternion);
          }
        }
      }
    }
  }

  setFixedWingCommand(command: FixedWingCommand): void {
    this.pilotIntentActive = false;
    this.currentCommand = { ...command };
  }

  setFixedWingControls(controls: { throttle: number; pitch: number; roll: number; yaw: number }): void {
    this.pilotIntentActive = false;
    this.currentCommand = {
      throttleTarget: controls.throttle,
      pitchCommand: controls.pitch,
      rollCommand: controls.roll,
      yawCommand: controls.yaw,
      brake: 0,
      freeLook: false,
      stabilityAssist: false,
    };
  }

  setFixedWingPilotIntent(intent: FixedWingPilotIntent): void {
    this.currentPilotIntent = { ...intent };
    this.pilotIntentActive = true;
  }

  // -- Forward armament --

  /**
   * Begin firing the airframe's gun for the given aircraft. Held trigger: the
   * gun keeps firing each update while `isFiring` is set and ammo remains.
   */
  startFiring(aircraftId: string): void {
    const weapon = this.weapons.get(aircraftId);
    if (weapon) weapon.isFiring = true;
  }

  stopFiring(aircraftId: string): void {
    const weapon = this.weapons.get(aircraftId);
    if (weapon) weapon.isFiring = false;
  }

  /**
   * Number of armament installations the player fires as a unit. The fleet
   * fires its barrels as one trigger group (round-robin), so this is 1 when an
   * aircraft is armed — the multi-barrel detail is the table's, not the count's.
   */
  getWeaponCount(aircraftId: string): number {
    return this.weapons.has(aircraftId) ? 1 : 0;
  }

  /** Forward / broadside gun ammo remaining for this airframe. */
  getWeaponAmmo(aircraftId: string): number {
    return this.weapons.get(aircraftId)?.ammo ?? 0;
  }

  /** Gun magazine capacity (full load) for this airframe's armament. */
  getWeaponAmmoCapacity(aircraftId: string): number {
    return this.weapons.get(aircraftId)?.config.ammoCapacity ?? 0;
  }

  /** HUD-facing weapon name for this airframe's armament. */
  getWeaponName(aircraftId: string): string {
    return this.weapons.get(aircraftId)?.config.name ?? '';
  }

  /**
   * Reads and clears the airborne-gate feedback flag: returns `true` once for
   * each frame in which the player pulled the trigger while grounded (the gun
   * fired nothing). The HUD polls this to flash a transient "Airborne to fire"
   * hint so the silence is explained rather than mysterious. Consume-on-read so
   * the hint naturally fades when the player stops trying or lifts off.
   */
  consumeGroundedFireBlocked(): boolean {
    const blocked = this.groundedFireBlocked;
    this.groundedFireBlocked = false;
    return blocked;
  }

  /**
   * Advance the airframe's gun for one frame. Fires as many rounds as the
   * fire-rate budget allows while the trigger is held, routing each shot
   * through the shared combatant fire path so friend-or-foe filtering and
   * damage resolution match the helicopter and player weapons. Fire geometry
   * (origin / direction / spread / cadence / magazine) comes from the airframe
   * armament table: A-1 and F-4 fire forward; the AC-47 fires its broadside
   * battery 90° to the left of the nose. Only fires for airborne / moving
   * aircraft (no ground strafing of the parking apron).
   */
  private updateForwardGun(
    aircraftId: string,
    group: THREE.Group,
    isAirborne: boolean,
    deltaTime: number,
  ): void {
    const weapon = this.weapons.get(aircraftId);
    if (!weapon) return;

    if (weapon.cooldownRemaining > 0) {
      weapon.cooldownRemaining -= deltaTime;
    }

    // Holding the trigger on the ground produces no rounds (the gate below).
    // Record it so the HUD can explain the silence with an "Airborne to fire"
    // hint instead of leaving the player guessing whether the gun is broken.
    if (weapon.isFiring && !isAirborne && weapon.ammo > 0) {
      this.groundedFireBlocked = true;
    }

    if (!weapon.isFiring || !isAirborne || weapon.ammo <= 0) {
      return;
    }
    if (!this.combatantSystem) {
      return;
    }

    const gun = weapon.config;
    const interval = 1 / gun.fireRate;
    let rounds = 0;
    // Fire as many rounds as the dt budget allows, capped against a runaway loop.
    while (weapon.cooldownRemaining <= 0 && weapon.ammo > 0 && rounds < 32) {
      weapon.cooldownRemaining += interval;
      weapon.ammo--;
      weapon.roundsSinceTracer++;
      rounds++;

      // Resolve muzzle origin + fire direction from the airframe armament table.
      // Round-robins across the barrels (paired wing cannons / broadside trio).
      computeFixedWingShot(
        gun,
        group.position,
        group.quaternion,
        weapon.barrelIndex,
        _gunMuzzle,
        _gunForward,
      );
      weapon.barrelIndex++;

      this.applyGunSpread(_gunForward, gun.spreadDeg);

      _gunRay.origin.copy(_gunMuzzle);
      _gunRay.direction.copy(_gunForward);
      const result = this.combatantSystem.handlePlayerShot(
        _gunRay,
        () => gun.damage,
        'fixedwing_gun',
        weapon.faction,
      );

      if (result.hit) {
        this.combatantSystem.impactEffectsPool?.spawn(result.point, _gunForward);
      }

      if (weapon.roundsSinceTracer >= gun.tracerInterval) {
        weapon.roundsSinceTracer = 0;
        if (result.hit) {
          _gunTracerEnd.copy(result.point);
        } else {
          _gunTracerEnd.copy(_gunMuzzle).addScaledVector(_gunForward, FIXED_WING_GUN_TRACER_RANGE);
        }
        this.ensureTracerPool().spawn(_gunMuzzle, _gunTracerEnd, 120);
      }
    }
  }

  /** Lazily create the shared tracer pool (only when something actually fires). */
  private ensureTracerPool(): TracerPool {
    if (!this.tracerPool) {
      this.tracerPool = new TracerPool(this.scene, 24);
    }
    return this.tracerPool;
  }

  /** Apply a random cone spread to a normalized forward direction in place. */
  private applyGunSpread(direction: THREE.Vector3, spreadDeg: number): void {
    if (spreadDeg <= 0) return;
    const spreadRad = (spreadDeg * Math.PI) / 180;
    const angle = Math.random() * spreadRad;
    const rotation = Math.random() * Math.PI * 2;

    const up = _gunSpreadUp.set(0, 1, 0);
    const right = _gunSpreadRight.crossVectors(direction, up);
    if (right.lengthSq() < 0.001) {
      up.set(1, 0, 0);
      right.crossVectors(direction, up);
    }
    right.normalize();
    up.crossVectors(right, direction).normalize();

    direction
      .addScaledVector(right, Math.sin(angle) * Math.cos(rotation))
      .addScaledVector(up, Math.sin(angle) * Math.sin(rotation))
      .normalize();
  }

  // -- NPC pilot hooks --

  /**
   * Attach an NPC pilot to an aircraft in this catalog. The pilot owns the
   * aircraft's runtime command whenever the aircraft is not player-piloted.
   * Returns false if the aircraftId is unknown.
   */
  attachNPCPilot(aircraftId: string, mission: NPCPilotMission): boolean {
    if (!this.runtimes.has(aircraftId)) {
      return false;
    }
    const terrainProbe: NPCTerrainProbe | null = this.terrainManager
      ? { getHeightAt: (x: number, z: number) => this.terrainManager!.getHeightAt(x, z) }
      : null;
    const existing = this.npcPilots.get(aircraftId);
    const pilot = existing ?? new NPCFixedWingPilot(undefined, terrainProbe);
    pilot.setMission(mission);
    this.npcPilots.set(aircraftId, pilot);
    Logger.info('fixedwing', `NPC pilot attached to ${aircraftId} (mission.kind=${mission.kind})`);
    return true;
  }

  detachNPCPilot(aircraftId: string): void {
    const pilot = this.npcPilots.get(aircraftId);
    if (!pilot) return;
    pilot.clearMission();
    this.npcPilots.delete(aircraftId);
  }

  getNPCPilot(aircraftId: string): NPCFixedWingPilot | null {
    return this.npcPilots.get(aircraftId) ?? null;
  }

  // -- Queries --

  getFlightData(aircraftId: string): FixedWingFlightData | null {
    const runtime = this.runtimes.get(aircraftId);
    if (!runtime) return null;

    const configKey = this.configKeys.get(aircraftId);
    const config = configKey ? FIXED_WING_CONFIGS[configKey] : null;
    const snapshot = this.buildSnapshot(runtime);

    const controlPhase = config ? deriveFixedWingControlPhase(snapshot, config.physics) : 'flight';
    const orbitHoldEnabled = this.isOrbitHoldActive(aircraftId);
    return {
      airspeed: snapshot.airspeed,
      heading: snapshot.headingDeg,
      verticalSpeed: snapshot.verticalSpeed,
      altitude: snapshot.altitude,
      altitudeAGL: snapshot.altitudeAGL,
      controlPhase,
      operationState: config
        ? deriveFixedWingOperationState(snapshot, controlPhase, config, {
            orbitHoldEnabled,
            lineupActive: this.lineupAircraft.has(aircraftId),
          })
        : 'cruise',
      phase: snapshot.phase,
      aoaDeg: snapshot.aoaDeg,
      sideslipDeg: snapshot.sideslipDeg,
      throttle: snapshot.throttle,
      brake: snapshot.brake,
      weightOnWheels: snapshot.weightOnWheels,
      isStalled: snapshot.isStalled,
      flightState: fixedWingFlightStateFromSnapshot(snapshot),
      stallSpeed: config?.physics.stallSpeed ?? 40,
      pitch: snapshot.pitchDeg,
      roll: snapshot.rollDeg,
      orbitHoldEnabled,
      configKey: configKey ?? null,
    };
  }

  getDisplayInfo(aircraftId: string): FixedWingDisplayInfo | null {
    const configKey = this.configKeys.get(aircraftId);
    return configKey ? getFixedWingDisplayInfo(configKey) : null;
  }

  getAircraftPositionTo(id: string, target: THREE.Vector3): boolean {
    const group = this.groups.get(id);
    if (!group) return false;
    target.copy(group.position);
    return true;
  }

  getAircraftQuaternionTo(id: string, target: THREE.Quaternion): boolean {
    const group = this.groups.get(id);
    if (!group) return false;
    target.copy(group.quaternion);
    return true;
  }

  getAircraftVelocityTo(id: string, target: THREE.Vector3): boolean {
    const runtime = this.runtimes.get(id);
    if (!runtime) return false;
    target.copy(runtime.airframe.getVelocity());
    return true;
  }

  getConfigKey(aircraftId: string): string | null {
    return this.configKeys.get(aircraftId) ?? null;
  }

  getAircraftIds(): string[] {
    return Array.from(this.groups.keys());
  }

  getSpawnMetadata(aircraftId: string): FixedWingSpawnMetadata | null {
    return this.spawnMetadata.get(aircraftId) ?? null;
  }

  positionAircraftAtRunwayStart(aircraftId: string): boolean {
    const metadata = this.spawnMetadata.get(aircraftId);
    const runwayStart = metadata?.runwayStart;
    const runtime = this.runtimes.get(aircraftId);
    const group = this.groups.get(aircraftId);
    const configKey = this.configKeys.get(aircraftId);
    const config = configKey ? FIXED_WING_CONFIGS[configKey] : null;
    if (!runwayStart || !runtime || !group || !config) {
      return false;
    }
    this.resetPilotedCommandState(aircraftId);

    const position = runwayStart.position.clone();
    if (this.terrainManager) {
      position.y = this.terrainManager.getHeightAt(position.x, position.z) + config.physics.gearClearance;
    }

    runtime.airframe.resetToGround(position);
    runtime.command = createIdleCommand();
    if (runtime.worldHalfExtent > 0) {
      runtime.airframe.setWorldHalfExtent(runtime.worldHalfExtent);
    }
    runtime.airframe.getQuaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), runwayStart.heading);
    group.position.copy(runtime.airframe.getPosition());
    group.quaternion.copy(runtime.airframe.getQuaternion());
    this.lineupAircraft.add(aircraftId);
    return true;
  }

  positionAircraftOnApproach(aircraftId: string): boolean {
    const metadata = this.spawnMetadata.get(aircraftId);
    const runwayStart = metadata?.runwayStart;
    const runtime = this.runtimes.get(aircraftId);
    const group = this.groups.get(aircraftId);
    const configKey = this.configKeys.get(aircraftId);
    const config = configKey ? FIXED_WING_CONFIGS[configKey] : null;
    if (!runwayStart || !runtime || !group || !config) {
      return false;
    }
    this.resetPilotedCommandState(aircraftId);

    const quaternion = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), runwayStart.heading);
    const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(quaternion);
    const position = runwayStart.position.clone().addScaledVector(forward, -(runwayStart.shortFinalDistance ?? 160));
    let groundHeight = 0;
    if (this.terrainManager) {
      groundHeight = this.terrainManager.getHeightAt(position.x, position.z);
      position.y = groundHeight + (runwayStart.shortFinalAltitude ?? 40);
    } else {
      position.y += runwayStart.shortFinalAltitude ?? 40;
    }

    runtime.airframe.resetAirborne(
      position,
      quaternion,
      Math.max(config.operation.approachSpeed, config.physics.v2Speed * 0.9),
      -5,
      groundHeight,
    );
    if (runtime.worldHalfExtent > 0) {
      runtime.airframe.setWorldHalfExtent(runtime.worldHalfExtent);
    }
    group.position.copy(runtime.airframe.getPosition());
    group.quaternion.copy(runtime.airframe.getQuaternion());
    this.lineupAircraft.delete(aircraftId);
    return true;
  }

  getDebugTelemetry(aircraftId: string): Record<string, unknown> | null {
    const flightData = this.getFlightData(aircraftId);
    if (!flightData) {
      return null;
    }
    const metadata = this.spawnMetadata.get(aircraftId);
    return {
      aircraftId,
      configKey: flightData.configKey,
      operationState: flightData.operationState,
      controlPhase: flightData.controlPhase,
      airspeed: Number(flightData.airspeed.toFixed(2)),
      altitudeAGL: Number(flightData.altitudeAGL.toFixed(2)),
      pitch: Number(flightData.pitch.toFixed(2)),
      roll: Number(flightData.roll.toFixed(2)),
      weightOnWheels: flightData.weightOnWheels,
      isStalled: flightData.isStalled,
      orbitHoldEnabled: flightData.orbitHoldEnabled,
      standId: metadata?.standId ?? null,
      runwayStartId: metadata?.runwayStart?.id ?? null,
    };
  }

  hasAircraft(): boolean {
    return this.groups.size > 0;
  }

  /** Check if a model path corresponds to a fixed-wing aircraft */
  static isFixedWingModelPath(modelPath: string): boolean {
    return getFixedWingConfigKeyForModelPath(modelPath) !== null;
  }

  private buildSnapshot(runtime: AircraftRuntime): FixedWingFlightSnapshot {
    return airframeStateToFixedWingSnapshot(runtime.airframe.getState());
  }

  private isOrbitHoldActive(aircraftId: string): boolean {
    return this.pilotedAircraftId === aircraftId && this.currentPilotIntent.orbitHoldEnabled;
  }

  private resetPilotedCommandState(aircraftId: string): void {
    if (this.pilotedAircraftId !== aircraftId) {
      return;
    }
    this.currentCommand = createIdleCommand();
    this.currentPilotIntent = createIdleFixedWingPilotIntent();
    this.pilotIntentActive = false;
  }
}