feat(combat): port retail held weapon parenting

Select the default combat mode from ordered equipped objects so bows request missile stance. Parse CreateObject parent metadata and ParentEvent, then render held objects as separate children composed from setup holding locations and placement frames each animation tick.

src/AcDream.Core/Meshing/EquippedChildAttachment.cs

@@ -0,0 +1,85 @@
+using System.Numerics;
+using AcDream.Core.World;
+using DatReaderWriter.DBObjs;
+using DatReaderWriter.Enums;
+using DatReaderWriter.Types;
+
+namespace AcDream.Core.Meshing;
+
+/// <summary>
+/// Retail held-object transform composition. A weapon is a separate child
+/// physics object: the parent's <see cref="Setup.HoldingLocations"/> selects
+/// a hand part and a frame relative to it, while the child's placement frame
+/// poses the weapon's own setup parts.
+///
+/// Sources: <c>CPhysicsObj::add_child @ 0x0050F870</c>,
+/// <c>CPhysicsObj::UpdateChild @ 0x00512D50</c>,
+/// <c>CPartArray::SetPlacementFrame @ 0x005193D0</c>, and
+/// <c>Frame::combine @ 0x005122E0</c>.
+/// </summary>
+public static class EquippedChildAttachment
+{
+    public static bool TryCompose(
+        Setup parentSetup,
+        IReadOnlyList<MeshRef> currentParentPose,
+        Setup childSetup,
+        ParentLocation parentLocation,
+        Placement placement,
+        IReadOnlyList<MeshRef> childPartTemplate,
+        float childScale,
+        out IReadOnlyList<MeshRef> attachedParts)
+    {
+        ArgumentNullException.ThrowIfNull(parentSetup);
+        ArgumentNullException.ThrowIfNull(currentParentPose);
+        ArgumentNullException.ThrowIfNull(childSetup);
+        ArgumentNullException.ThrowIfNull(childPartTemplate);
+
+        if (!parentSetup.HoldingLocations.TryGetValue(parentLocation, out LocationType? holding))
+        {
+            attachedParts = Array.Empty<MeshRef>();
+            return false;
+        }
+
+        Matrix4x4 parentPart = holding.PartId >= 0
+            && holding.PartId < currentParentPose.Count
+                ? currentParentPose[holding.PartId].PartTransform
+                : Matrix4x4.Identity;
+        Matrix4x4 holdingFrame = ToMatrix(holding.Frame);
+        Matrix4x4 childRoot = holdingFrame * parentPart;
+
+        // Retail CPartArray::SetPlacementFrame falls back specifically to
+        // placement 0 (Default), then installs null if Default is absent.
+        AnimationFrame? placementFrame = null;
+        if (!childSetup.PlacementFrames.TryGetValue(placement, out placementFrame))
+            childSetup.PlacementFrames.TryGetValue(Placement.Default, out placementFrame);
+
+        int partCount = Math.Min(childSetup.Parts.Count, childPartTemplate.Count);
+        var result = new MeshRef[partCount];
+        for (int i = 0; i < partCount; i++)
+        {
+            Frame partFrame = placementFrame is not null && i < placementFrame.Frames.Count
+                ? placementFrame.Frames[i]
+                : new Frame { Orientation = Quaternion.Identity };
+            Vector3 scale = i < childSetup.DefaultScale.Count
+                ? childSetup.DefaultScale[i]
+                : Vector3.One;
+            Matrix4x4 childPart = Matrix4x4.CreateScale(scale)
+                * ToMatrix(partFrame);
+            if (childScale != 1.0f)
+                childPart *= Matrix4x4.CreateScale(childScale);
+
+            MeshRef template = childPartTemplate[i];
+            result[i] = new MeshRef(template.GfxObjId, childPart * childRoot)
+            {
+                SurfaceOverrides = template.SurfaceOverrides,
+            };
+        }
+
+        attachedParts = result;
+        return true;
+    }
+
+    private static Matrix4x4 ToMatrix(Frame frame) =>
+        Matrix4x4.CreateFromQuaternion(frame.Orientation)
+        * Matrix4x4.CreateTranslation(frame.Origin);
+}