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

using System.Collections.Generic;

namespace AcDream.Core.Physics;

/// <summary>
/// L.2g S2 — supporting types for the inbound CMotionInterp funnel
/// (deviation DEV-1). Spec:
/// docs/research/2026-07-02-s2-inbound-funnel-pseudocode.md; decomp:
/// MovementManager::unpack_movement 0x00524440,
/// CMotionInterp::move_to_interpreted_state 0x005289c0,
/// apply_interpreted_movement 0x00528600, DoInterpretedMotion 0x00528360 —
/// dispatch order validated against a LIVE retail-observer cdb trace
/// (tools/cdb/l2g-observer.cdb).
/// </summary>
public interface IInterpretedMotionSink
{
    /// <summary>
    /// The <c>CPhysicsObj::DoInterpretedMotion → … →
    /// CMotionTable::GetObjectSequence</c> backend — called for every motion
    /// that passes <c>contact_allows_move</c>, in retail dispatch order
    /// (style → forward-or-Falling → sidestep → turn → actions). R2-Q5: the
    /// production implementation is <c>Motion.MotionTableDispatchSink</c>,
    /// which dispatches straight into the entity's motion-table stack
    /// (<c>PerformMovement</c> → GetObjectSequence + is_allowed decide) —
    /// no sink-side axis pick or fallback chain.
    /// </summary>
    /// <returns>
    /// R3-W5: retail's own <c>CPhysicsObj::DoInterpretedMotion</c> RETURNS a
    /// result (<c>result == 0</c> = the motion table found a cycle for this
    /// id; nonzero = <c>MotionTableManagerError.MotionFailed</c>/no-table) —
    /// <c>CMotionInterp::DoInterpretedMotion</c>'s caller (raw 305591-305610)
    /// gates BOTH the <c>add_to_queue</c> call AND the
    /// <c>InterpretedMotionState::ApplyMotion</c> state-write on that result.
    /// This matters concretely for the very first dispatch of every
    /// <c>apply_interpreted_movement</c> call — the STYLE/stance id
    /// (<c>current_style</c>, always <c>&gt;= 0x80000000</c>) has no
    /// locomotion <c>MotionData</c> entry in the dat, so
    /// <c>CMotionTable::DoObjectMotion</c> genuinely fails for it; if that
    /// failure isn't propagated, the state-write's negative-motion branch
    /// (<see cref="InterpretedMotionState.ApplyMotion"/>: <c>arg2 &lt; 0 →
    /// forward_command = 0x41000003</c>) clobbers <c>ForwardCommand</c>
    /// BEFORE the very next line reads it for the real forward dispatch —
    /// confirmed regression against the 183-case live retail-observer trace
    /// (<c>RetailObserverTraceConformanceTests</c>) when this was <c>void</c>.
    /// Return <c>true</c> when the underlying <c>PerformMovement</c> call
    /// succeeded (<c>MotionTableManagerError.Success</c>).
    /// </returns>
    bool ApplyMotion(uint motion, float speed);

    /// <summary>
    /// <c>StopInterpretedMotion</c> notification for an axis the incoming
    /// state cleared (sidestep 0x6500000F / turn 0x6500000D). Unconditional
    /// (no contact gate) per apply_interpreted_movement.
    /// </summary>
    /// <returns>Same result-propagation rationale as <see cref="ApplyMotion"/>
    /// — retail's <c>CPhysicsObj::StopInterpretedMotion</c> also returns a
    /// result that gates the post-stop <c>add_to_queue</c> + state-removal.</returns>
    bool StopMotion(uint motion);

    /// <summary>
    /// R4-V5 wedge fix — retail <c>CPhysicsObj::StopCompletely_Internal</c>
    /// (0x0050ead0) → <c>CPartArray::StopCompletelyInternal</c> (0x00518890)
    /// → <c>MotionTableManager::PerformMovement(MovementStruct{type=5})</c>:
    /// the ANIMATION-side full stop dispatched from the middle of
    /// <c>CMotionInterp::StopCompletely</c> (raw @00527e90). The manager
    /// queues its pending_animations entry UNCONDITIONALLY for type 5, and
    /// that entry's AnimationDone → MotionDone is the matched pop for the A9
    /// pending_motions node <c>StopCompletely</c> enqueues right after this
    /// call — without it the A9 node is an orphan and <c>MotionsPending</c>
    /// never drains at idle (the 2026-07-03 moveto wedge). Default
    /// implementation returns <c>true</c> (the null-sink "no animation
    /// backend" posture — bare tests and sink-less interps are unaffected).
    /// </summary>
    bool StopCompletely() => true;
}

/// <summary>
/// One entry of the inbound action list (retail <c>MotionItem</c> /
/// <c>InterpretedMotionState.actions</c>): a one-shot command with the
/// 15-bit server action stamp + autonomy bit
/// (<c>u16 ((stamp &amp; 0x7FFF) | (autonomous ? 0x8000 : 0))</c>).
/// </summary>
public readonly record struct InboundMotionAction(
    uint Command, int Stamp, bool Autonomous, float Speed);

/// <summary>
/// A fully-decoded inbound <c>InterpretedMotionState</c>: wire fields where
/// present, retail UnPack defaults where absent
/// (<c>InterpretedMotionState::UnPack</c> 0x0051f400 /
/// ctor 0x0051e8d0). A flags=0 "empty" UM decodes to exactly
/// <see cref="Default"/> — a retail-verbatim full stop.
/// </summary>
public struct InboundInterpretedState
{
    public uint CurrentStyle;
    public uint ForwardCommand;
    public float ForwardSpeed;
    public uint SideStepCommand;
    public float SideStepSpeed;
    public uint TurnCommand;
    public float TurnSpeed;
    public IReadOnlyList<InboundMotionAction>? Actions;

    public static InboundInterpretedState Default() => new()
    {
        CurrentStyle    = 0x8000003Du,
        ForwardCommand  = 0x41000003u,
        ForwardSpeed    = 1.0f,
        SideStepCommand = 0u,
        SideStepSpeed   = 1.0f,
        TurnCommand     = 0u,
        TurnSpeed       = 1.0f,
        Actions         = null,
    };
}