acdream/src/AcDream.Core/Physics/ShadowShape.cs

using System.Numerics;

namespace AcDream.Core.Physics;

/// <summary>
/// One collision-bearing shape attached to a logical PhysicsObj.
/// The set is a DISPATCH, not a union (AP-152): a BSP door emits one shape
/// per physics-BSP part and no primitive; a primitive-only object emits its
/// CylSpheres, else its Spheres; a simple item zero. Positions and rotations are
/// LOCAL to the entity's origin so <see cref="ShadowObjectRegistry.UpdatePosition"/>
/// can re-transform them when the entity moves.
///
/// <para>
/// Retail anchor: <c>CPhysicsPart</c> + <c>CPhysicsPart::find_obj_collisions</c>
/// at <c>acclient_2013_pseudo_c.txt:275045-275055</c>. Each part stores its
/// own transform and dispatches per-part collision to its GfxObj.
/// </para>
///
/// <para>
/// CONSTRUCTION IS BY FACTORY ONLY (<see cref="Bsp"/>, <see cref="Cylinder"/>,
/// <see cref="Sphere"/>) and the constructor is private. That is the AP-156
/// invariant expressed at the type rather than only at the producer: a BSP
/// shape's radius, its bounding-sphere CENTRE, and its authored bounding BOX
/// arrive as one <see cref="ShadowPartGeometry"/> value and are scaled together
/// inside <see cref="Bsp"/>, so no call site — present or future — can take one
/// while dropping another. Those splits are exactly what produced AP-156 (the
/// centre dropped) and #334 (the box never resolved at all); with a public
/// positional constructor a new BSP producer could reintroduce either silently
/// and green.
/// </para>
/// </summary>
public readonly record struct ShadowShape
{
    private ShadowShape(
        uint gfxObjId,
        Vector3 localPosition,
        Quaternion localRotation,
        float scale,
        ShadowCollisionType collisionType,
        float radius,
        float cylHeight,
        Vector3 boundsCenter,
        Vector3 localBoundsMin,
        Vector3 localBoundsMax)
    {
        GfxObjId = gfxObjId;
        LocalPosition = localPosition;
        LocalRotation = localRotation;
        Scale = scale;
        CollisionType = collisionType;
        Radius = radius;
        CylHeight = cylHeight;
        BoundsCenter = boundsCenter;
        LocalBoundsMin = localBoundsMin;
        LocalBoundsMax = localBoundsMax;
    }

    /// <summary>Source GfxObj id, for the BSP walk and for diagnostics.</summary>
    public uint GfxObjId { get; }

    /// <summary>Part placement in the entity's own frame, entity-scaled.</summary>
    public Vector3 LocalPosition { get; }

    /// <summary>Part orientation in the entity's own frame.</summary>
    public Quaternion LocalRotation { get; }

    /// <summary>The entity (or part) scale already applied to the geometry.</summary>
    public float Scale { get; }

    public ShadowCollisionType CollisionType { get; }

    /// <summary>Collision radius, entity-scaled.</summary>
    public float Radius { get; }

    /// <summary>Cylinder height, entity-scaled; 0 for BSP and Sphere.</summary>
    public float CylHeight { get; }

    /// <summary>
    /// Center of the shape's bounding sphere IN THE SHAPE'S OWN LOCAL FRAME —
    /// the frame <see cref="LocalRotation"/> rotates out of and
    /// <see cref="Radius"/> is measured in — already multiplied by the entity
    /// scale, like <see cref="LocalPosition"/> and <see cref="Radius"/>.
    /// <c>Zero</c> for Cylinder/Sphere shapes, whose
    /// <see cref="LocalPosition"/> already IS their center.
    ///
    /// <para>
    /// BSP shapes need it because a GfxObj's physics BSP is authored in the
    /// GfxObj's own coordinates and its root bounding sphere is frequently NOT
    /// centered on that origin (376 of the 973 physics-BSP parts in the
    /// installed <c>client_portal.dat</c> sit further from it than half their
    /// own radius; worst 20.762 m on a 27.708 m sphere, gfx 0x010036DD).
    /// <see cref="ShadowObjectRegistry.RegisterMultiPart"/>'s flood needs the
    /// sphere's real position, not the part origin's.
    /// </para>
    ///
    /// <para>
    /// Retail anchor: <c>CGfxObj::physics_sphere</c> (<c>[gfxobj+0x74]</c>) is
    /// assigned <c>BSPTREE::GetSphere(physics_bsp)</c> @0x005397e0
    /// (<c>mov eax,[ecx]; add eax,4</c> — the root <c>BSPNODE</c>'s
    /// <c>CSphere sphere</c>, past its 4-byte vftable), so retail's per-part
    /// flood sphere IS the BSP root bounding sphere, origin included.
    /// <c>CEnvCell::find_transit_cells</c> @0x0052cae0 — the part-array overload
    /// reached from <c>CPhysicsObj::find_bbox_cell_list</c> @0x00510fc0 via
    /// <c>CPartArray::calc_cross_cells_static</c> @0x00518160's
    /// <c>[vtbl+0x7c]</c> dispatch — loads that sphere at
    /// <c>0x0052cb36 mov esi,[ecx+0x74]</c>, transforms its CENTER through the
    /// part's own <c>Position</c> at <c>[part+0x30]</c>
    /// (<c>0x0052cb4c add eax,0x30</c> / <c>0x0052cb5a call Position::localtolocal</c>),
    /// and only then reads the radius at <c>0x0052cb65 fadd [esi+0xc]</c>.
    /// </para>
    /// </summary>
    public Vector3 BoundsCenter { get; }

    /// <summary>
    /// The shape's AXIS-ALIGNED BOX in the same local frame as
    /// <see cref="BoundsCenter"/>, already entity-scaled. For a BSP shape this
    /// is retail's <c>CGfxObj::gfx_bound_box</c> — the AABB of the GfxObj's
    /// vertex array, which <c>CPhysicsPart::GetBoundingBox</c> @0x0050d600
    /// returns and which <c>CLandCell::add_all_outside_cells</c> @0x00533360
    /// divides by <c>square_length</c> to build the outdoor cell rectangle
    /// (#334). Primitive shapes carry their own radius/height box; they never
    /// reach that path, because <c>CPhysicsObj::calc_cross_cells</c>
    /// @0x00515230 routes only <c>HAS_PHYSICS_BSP_PS</c> objects to
    /// <c>find_bbox_cell_list</c>.
    /// </summary>
    public Vector3 LocalBoundsMin { get; }

    /// <inheritdoc cref="LocalBoundsMin"/>
    public Vector3 LocalBoundsMax { get; }

    /// <summary>
    /// One physics-BSP part. <paramref name="localGeometry"/> carries the part
    /// GfxObj's physics-BSP ROOT bounding sphere AND its vertex-array box in
    /// the GfxObj's OWN frame, unscaled — retail's
    /// <c>CGfxObj::physics_sphere</c> and <c>CGfxObj::gfx_bound_box</c>.
    /// Sphere radius, sphere centre, and both box corners are scaled together
    /// here, which is the whole point of taking them as one value: retail
    /// reads the sphere for the indoor portal reject and the box for the
    /// outdoor extent walk, and a producer that supplied one without the
    /// other would silently force a substitute at the other call site
    /// (AP-156, then #334).
    /// </summary>
    public static ShadowShape Bsp(
        uint gfxObjId,
        Vector3 localPosition,
        Quaternion localRotation,
        float scale,
        ShadowPartGeometry localGeometry)
        => new(
            gfxObjId,
            localPosition,
            localRotation,
            scale,
            ShadowCollisionType.BSP,
            localGeometry.Sphere.Radius * scale,
            0f,
            localGeometry.Sphere.Origin * scale,
            localGeometry.BoxMin * scale,
            localGeometry.BoxMax * scale);

    /// <summary>
    /// One Setup CylSphere. <paramref name="localPosition"/> already IS the
    /// shape's centre, so it carries no separate bounds centre.
    /// </summary>
    public static ShadowShape Cylinder(
        uint gfxObjId,
        Vector3 localPosition,
        Quaternion localRotation,
        float scale,
        float radius,
        float cylHeight)
        => new(
            gfxObjId,
            localPosition,
            localRotation,
            scale,
            ShadowCollisionType.Cylinder,
            radius,
            cylHeight,
            Vector3.Zero,
            new Vector3(-radius, -radius, 0f),
            new Vector3(radius, radius, cylHeight));

    /// <summary>
    /// One Setup Sphere. <paramref name="localPosition"/> already IS the
    /// shape's centre, so it carries no separate bounds centre.
    /// </summary>
    public static ShadowShape Sphere(
        uint gfxObjId,
        Vector3 localPosition,
        Quaternion localRotation,
        float scale,
        float radius)
        => new(
            gfxObjId,
            localPosition,
            localRotation,
            scale,
            ShadowCollisionType.Sphere,
            radius,
            0f,
            Vector3.Zero,
            new Vector3(-radius),
            new Vector3(radius));
}