// Movement/Core/S_MovementState.ts

import type { E_MovementState } from '#root/Movement/Core/E_MovementState.ts';
import type { E_SurfaceType } from '#root/Movement/Surface/E_SurfaceType.ts';
import type { Float } from '#root/UE/Float.ts';
import type { HitResult } from '#root/UE/HitResult.ts';
import type { Rotator } from '#root/UE/Rotator.ts';
import type { Vector } from '#root/UE/Vector.ts';

/**
 * Complete movement state snapshot
 * Immutable data structure representing full character movement state
 *
 * @category Movement State
 */
export interface S_MovementState {
  // ═══════════════════════════════════════════════════════════════════
  //                         TRANSFORM
  // ═══════════════════════════════════════════════════════════════════

  /**
   * Character world location
   */
  Location: Vector;

  /**
   * Character rotation (yaw only)
   */
  Rotation: Rotator;

  // ═══════════════════════════════════════════════════════════════════
  //                         VELOCITY & PHYSICS
  // ═══════════════════════════════════════════════════════════════════

  /**
   * Current velocity vector (cm/s)
   */
  Velocity: Vector;

  /**
   * Horizontal speed (cm/s)
   */
  Speed: Float;

  // ═══════════════════════════════════════════════════════════════════
  //                         GROUND STATE
  // ═══════════════════════════════════════════════════════════════════

  /**
   * Whether character is on walkable ground
   */
  IsGrounded: boolean;

  /**
   * Ground trace hit result
   */
  GroundHit: HitResult;

  /**
   * Current surface type
   */
  SurfaceType: E_SurfaceType;

  // ═══════════════════════════════════════════════════════════════════
  //                         COLLISION STATE
  // ═══════════════════════════════════════════════════════════════════

  /**
   * Whether movement was blocked by collision
   */
  IsBlocked: boolean;

  /**
   * Number of collision checks this frame
   */
  CollisionCount: number;

  // ═══════════════════════════════════════════════════════════════════
  //                         ROTATION STATE
  // ═══════════════════════════════════════════════════════════════════

  /**
   * Whether character is actively rotating
   */
  IsRotating: boolean;

  /**
   * Remaining angular distance to target (degrees)
   */
  RotationDelta: Float;

  // ═══════════════════════════════════════════════════════════════════
  //                         MOVEMENT STATE
  // ═══════════════════════════════════════════════════════════════════

  /**
   * Current movement state (Idle, Walking, Airborne, etc.)
   */
  MovementState: E_MovementState;

  /**
   * Input magnitude (0-1)
   */
  InputMagnitude: Float;
}