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>
/// </summary>
/// <param name="BoundsCenter">
/// 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>
/// </param>
public readonly record struct ShadowShape(
    uint                GfxObjId,
    Vector3             LocalPosition,
    Quaternion          LocalRotation,
    float               Scale,
    ShadowCollisionType CollisionType,
    float               Radius,
    float               CylHeight,
    Vector3             BoundsCenter = default);