using System.Collections.Generic;

using Syntriax.Engine.Core;

namespace Syntriax.Engine.Physics2D;

/// <summary>
/// Represents a 2D physics engine.
/// </summary>
public interface IPhysicsEngine2D
{
    /// <summary>
    /// Event triggered when the <see cref="IPhysicsEngine2D"/> has done a single physics iteration.
    /// </summary>
    Event<IPhysicsEngine2D, float> OnPhysicsIteration { get; }

    /// <summary>
    /// Event triggered when the <see cref="IPhysicsEngine2D"/> has done a full physics step/>.
    /// </summary>
    Event<IPhysicsEngine2D, float> OnPhysicsStep { get; }

    /// <summary>
    /// The number of iterations the <see cref="IPhysicsEngine2D"/> performs per step.
    /// </summary>
    int IterationPerStep { get; set; }

    /// <summary>
    /// Advances the physics simulation by the specified time.
    /// </summary>
    /// <param name="deltaTime">The time step.</param>
    void Step(float deltaTime);

    /// <summary>
    /// Advances the physics simulation by the specified time on a single <see cref="IRigidBody2D"/>.
    /// </summary>
    /// <param name="rigidBody">The <see cref="IRigidBody2D"/> to be progressed individually.</param>
    /// <param name="deltaTime">The time step.</param>
    void StepIndividual(IRigidBody2D rigidBody, float deltaTime);

    /// <summary>
    /// Casts a <see cref="Ray2D"/> into the scene and returns the closest <see cref="RaycastResult"/> it hits, if any.
    /// </summary>
    /// <param name="ray">The <see cref="Ray2D"/> to cast.</param>
    /// <param name="length">The maximum distance to check for intersections. Defaults to <see cref="float.MaxValue"/>.</param>
    /// <returns>
    /// A <see cref="RaycastResult"/> containing information about the hit, or <see cref="null"/> if no hit was detected.
    /// </returns>
    RaycastResult? Raycast(Ray2D ray, float length = float.MaxValue);

    /// <summary>
    /// Casts a <see cref="Ray2D"/> into the scene and stores all hit results in the provided list.
    /// </summary>
    /// <param name="ray">The <see cref="Ray2D"/> to cast.</param>
    /// <param name="results">
    /// A list to which all <see cref="RaycastResult"/>s will be added. The list will be populated with zero or more <see cref="RaycastResult"/> objects.
    /// </param>
    /// <param name="length">The maximum distance to check for intersections. Defaults to <see cref="float.MaxValue"/>.</param>
    void Raycast(Ray2D ray, IList<RaycastResult> results, float length = float.MaxValue);

    readonly record struct PhysicsIterationArguments(IPhysicsEngine2D Sender, float IterationDeltaTime);
    readonly record struct PhysicsStepArguments(IPhysicsEngine2D Sender, float StepDeltaTime);
}