using System.Numerics;

namespace AcDream.Core.Physics;

/// <summary>
/// Result of <see cref="PhysicsEngine.Resolve"/>: the validated
/// position after collision, the cell the entity ended up in,
/// and whether they're standing on a surface.
///
/// <para>
/// L.3a (2026-04-30): added optional collision-normal fields so the
/// caller (typically <see cref="AcDream.App.Input.PlayerMovementController"/>)
/// can apply retail's velocity-reflection bounce
/// (<c>v_new = v - (1 + elasticity) * dot(v, n) * n</c>) to the
/// PhysicsBody after the geometric resolve completes. ACE port mirror:
/// <c>references/ACE/Source/ACE.Server/Physics/PhysicsObj.cs:2692-2697</c>;
/// retail equivalent: <c>CPhysicsObj::handle_all_collisions</c> at
/// <c>acclient_2013_pseudo_c.txt:282699-282715</c>.
/// </para>
/// </summary>
public readonly record struct ResolveResult(
    Vector3 Position,
    uint CellId,
    bool IsOnGround,
    /// <summary>True when a wall collision occurred during this resolve
    /// and <see cref="CollisionNormal"/> is meaningful.</summary>
    bool CollisionNormalValid = false,
    /// <summary>Outward surface normal of the wall the sphere hit. Used
    /// by the velocity-reflection step. Pointing away from the wall.</summary>
    Vector3 CollisionNormal = default,
    /// <summary>Render Residual A — whether the underlying
    /// <c>FindTransitionalPosition</c> found a valid position (retail
    /// <c>find_valid_position != 0</c>, pc:273898). False when the sweep had no
    /// start cell or was immediately stuck. The camera <c>SweepEye</c> reads this
    /// to trigger <c>SmartBox::update_viewer</c>'s fallbacks. Default <c>true</c>
    /// so existing callers are unaffected.</summary>
    bool Ok = true);