Climbing.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
#include "climbing/ClimbingAnchorGraph.h"
#include "climbing/ClimbingAnchorAuthoring.h"
#include "climbing/ClimbingPrimitives.h"
#include "climbing/ClimbingTelemetry.h"
#include "common/Module.h"
#include "common/Result.h"
#include "common/SquirrelOwnership.h"
#include "common/StrongUint64.h"
#include "common/Time.h"
#include "common/Value.h"
#include "physics/OwnedQuery3D.h"
 
#include <cstddef>
#include <cstdint>
#include <array>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <unordered_set>
#include <vector>
 
namespace eve::animation {
class AnimClip;
}
 
namespace eve::physics {
class World3D;
}
 
namespace eve::climbing {
 
class ClimbingSelectionSystem;
class ClimbingServiceSelectionSystem;
 
enum class ClimbingActionKind : std::uint8_t {
    Vault,
    Mantle,
    LedgeGrab,
    ClimbUp,
    Shimmy,
    CornerInner,
    CornerOuter,
    LedgeJump,
    ClimbDown,
    LadderMount,
    LadderClimb,
    LadderDismount,
    WallRun,
    Slide,
    BeamBalance,
    PoleSwing,
    BarSwing
};
 
enum class ClimbingMovementMode : std::uint8_t { Grounded, Airborne, Climbing };
 
enum class ClimbingSourceMode : std::uint8_t {
    None     = 0,
    Grounded = 1u << 0u,
    Airborne = 1u << 1u,
    Climbing = 1u << 2u,
    Any      = 0x07
};
 
enum class ClimbingCommandRequirement : std::uint8_t { Any, Jump, Climb, Drop, Sprint, Crouch };
 
enum class ClimbingProbeRecipe : std::uint8_t { Automatic, Obstacle, Ledge, Wall, Ground, AnchorGraph };
 
enum class ClimbingTrajectoryKind : std::uint8_t { Automatic, BallisticArc, SurfaceFollow, AnchorToAnchor };
 
enum class ClimbingLandingPolicy : std::uint8_t { PreserveMomentum, MatchGround, Stop };
 
enum class ClimbingTerminalVelocityPolicy : std::uint8_t { Preserve, ClampDownward, Zero };
 
enum class ClimbingStaminaPolicy : std::uint8_t { Disabled, RequireProvider, UseWhenPresent };
 
enum class ClimbingInputMode : std::uint8_t { Flow, Precision };
 
struct ClimbingAnimationBinding {
    std::string clipId;
    std::string graphNodeId;
    std::string rootBone = "Root";
    bool        mirrored = false;
};
 
struct ClimbingBranchWindow {
    float       start = 0.f;
    float       end   = 1.f;
    std::string comboTag;
};
 
enum class ClimbingContactTarget : std::uint8_t { LeftHand, RightHand, LeftFoot, RightFoot, Pelvis };
 
struct ClimbingContactConstraint {
    ClimbingContactTarget target    = ClimbingContactTarget::LeftHand;
    float                 start     = 0.f;
    float                 end       = 1.f;
    float                 maxWeight = 1.f;
};
 
struct ClimbingScoreWeights {
    std::int32_t direction       = 1000;
    std::int32_t approachSpeed   = 1000;
    std::int32_t height          = 1000;
    std::int32_t distance        = 1000;
    std::int32_t warpTranslation = 1000;
    std::int32_t warpRotation    = 1000;
    std::int32_t intentMismatch  = 1000;
};
 
enum class HangSupport : std::uint8_t { None, Braced, Free };
 
enum class ClimbingCancelReason : std::uint8_t {
    PlayerRequest,
    DropRequested,
    LinkStale,
    AnchorStale,
    MotionBlocked,
    WarpBudgetExceeded,
    DefinitionReloaded
};
 
struct ClimbingWarpWindow {
    float start      = 0.f;
    float end        = 1.f;
    bool  horizontal = true;
    bool  vertical   = true;
    bool  facing     = true;
};
 
struct ClimbingActionDefinition {
    static constexpr std::string_view SchemaId = "evengine.climbing-action";
    static constexpr std::int64_t SchemaVersion = 4;
 
    std::string                     id;
    float                           minHeight                 = 0.f;
    float                           maxHeight                 = 1.f;
    float                           minSpeed                  = 0.f;
    eve::Duration                   duration                  = eve::Duration::fromNanoseconds(500000000);
    float                           landingForward            = 0.35f;
    float                           apexHeight                = 0.15f;
    int                             selectionBias             = 0;
    ClimbingActionKind              kind                      = ClimbingActionKind::Mantle;
    float                           hangBodyOffset            = 0.35f;
    float                           hangFeetBelowLedge        = 1.55f;
    float                           handSpacing               = 0.42f;
    float                           cancelWindowStart         = 0.f;
    float                           cancelWindowEnd           = 1.f;
    float                           rootMotionScaleMin        = 0.75f;
    float                           rootMotionScaleMax        = 1.35f;
    float                           maxTranslationWarpPerTick = 0.15f;
    float                           maxYawWarpRadiansPerTick  = 0.12f;
    float                           horizontalWarpBudget      = 0.6f;
    float                           verticalWarpBudget        = 0.6f;
    float                           facingWarpBudgetRadians   = 0.8f;
    std::vector<ClimbingWarpWindow> warpWindows;
    std::vector<std::string>        requiredNotifies;
    std::vector<std::string>        tags;
    ClimbingSourceMode              sourceModes = ClimbingSourceMode::Any;
    ClimbingCommandRequirement      requiredCommand = ClimbingCommandRequirement::Any;
    ClimbingProbeRecipe             probeRecipe = ClimbingProbeRecipe::Automatic;
    float                           minDepth = 0.f;
    float                           maxDepth = 1000.f;
    float                           minDistance = 0.f;
    float                           maxDistance = 1000.f;
    float                           minSurfaceNormalY = -1.f;
    float                           maxSlopeRadians = 3.1415927f;
    float                           maxCurvature = 1000.f;
    std::vector<std::string>        requiredSupportTags;
    ClimbingTrajectoryKind          trajectory = ClimbingTrajectoryKind::Automatic;
    ClimbingAnimationBinding        animation;
    std::vector<ClimbingBranchWindow> branchWindows;
    std::vector<ClimbingContactConstraint> contactConstraints;
    ClimbingLandingPolicy           landingPolicy = ClimbingLandingPolicy::MatchGround;
    ClimbingTerminalVelocityPolicy  terminalVelocityPolicy = ClimbingTerminalVelocityPolicy::Preserve;
    std::vector<std::string>        comboTags;
    std::int32_t                    repetitionPenalty = 0;
    std::vector<std::string>        requiredConditionTags;
    float                           staminaCost = 0.f;
    std::string                     cameraCue;
    std::vector<std::string>        eventMetadata;
    eve::Value::Object extensionMetadata;
};
 
struct ClimbingProfileDefinition {
    static constexpr std::string_view SchemaId = "evengine.climbing-profile";
    static constexpr std::int64_t SchemaVersion = 4;
 
    float                                 capsuleRadius          = 0.3f;
    float                                 capsuleHeight          = 1.8f;
    float                                 compactCapsuleHeight   = 1.2f;
    float                                 skin                   = 0.03f;
    float                                 maxProbeDistance       = 1.2f;
    float                                 maxObstacleHeight      = 1.8f;
    float                                 minTopNormalY          = 0.65f;
    float                                 maxWarpResidual        = 0.2f;
    float                                 maxPlatformSpeed       = 8.f;
    float                                 dropInitialSpeed       = 1.5f;
    std::uint64_t                         inputBufferTicks       = 8;
    std::uint64_t                         coyoteTicks            = 6;
    std::uint32_t                         pathValidationSegments = 12;
    float                                 maxPelvisDeviation     = 0.35f;
    float                                 groundAcceleration     = 28.f;
    float                                 groundBraking          = 32.f;
    float                                 airControl             = 0.45f;
    float                                 gravity                = 24.f;
    float                                 jumpSpeed              = 7.f;
    std::uint32_t                         probeSectors           = 8;
    std::uint32_t                         maxCandidates          = 8;
    float                                 autoAssistStrength     = 0.65f;
    ClimbingScoreWeights                  scoreWeights;
    float                                 maxTotalWarpBudget     = 1.2f;
    std::vector<std::string>              defaultActionIds;
    std::vector<std::string>              allowedActionTags;
    std::vector<std::string>              deniedActionTags;
    ClimbingStaminaPolicy                 staminaPolicy = ClimbingStaminaPolicy::Disabled;
    std::string                           staminaAdapter;
    std::string                           cameraCueProfile;
    physics::QueryFilter3D                queryFilter{};
    std::vector<ClimbingActionDefinition> actions;
    eve::Value::Object extensionMetadata;
};
 
struct ClimbingLocomotionPolicy {
    float                  groundAcceleration = 28.f;
    float                  groundBraking      = 32.f;
    float                  airControl          = 0.45f;
    float                  gravity             = 24.f;
    float                  jumpSpeed           = 7.f;
    std::uint64_t          coyoteTicks         = 6;
    physics::QueryFilter3D queryFilter{};
};
 
using ClimbingProfile = ClimbingProfileDefinition;
 
struct ClimbingPose {
    Vec3  feet;
    Vec3  forward{0.f, 0.f, 1.f};
    float speed         = 0.f;
    int   ignoredBodyId = -1;
    float verticalSpeed = 0.f;
    bool  grounded      = true;
    Vec3  moveIntent;
    Vec3  lookIntent{0.f, 0.f, 1.f};
    ClimbingInputMode inputMode = ClimbingInputMode::Flow;
};
 
struct ClimbingCandidate {
    std::string                 actionId;
    std::uint64_t               definitionGeneration = 1;
    physics::PhysicsWorldHandle world           = physics::PhysicsWorldHandle::invalid();
    physics::PhysicsBodyHandle  obstacleBody    = physics::PhysicsBodyHandle::invalid();
    physics::PhysicsShapeHandle obstacleShape   = physics::PhysicsShapeHandle::invalid();
    int                         obstacleBodyId  = -1;
    int                         obstacleShapeId = -1;
    int                         ignoredBodyId   = -1;
    Vec3                        frontPoint;
    Vec3                        topPoint;
    Vec3                        landingFeet;
    Vec3                        surfaceNormal;
    Vec3                        surfaceTangent;
    Vec3                        leftHandAnchor;
    Vec3                        rightHandAnchor;
    Vec3                        bodyLocalTop;
    Vec3                        bodyLocalLanding;
    float                       obstacleHeight = 0.f;
    float                       obstacleDepth  = 0.f;
    float                       gapDistance    = 0.f;
    float                       clearanceHeight = 0.f;
    float                       slopeRadians   = 0.f;
    float                       curvature      = 0.f;
    int                         supportShapeTag = 0;
    int                         supportMaterialId = 0;
    ClimbingProbeRecipe         probeRecipe = ClimbingProbeRecipe::Automatic;
    std::int64_t                score          = 0;
    ClimbingActionKind          kind           = ClimbingActionKind::Mantle;
    HangSupport                 support        = HangSupport::None;
};
 
class ClimbingCandidateSet {
public:
    static constexpr std::size_t Capacity = 8;
 
    void clear() noexcept { size_ = 0; }
    void consider(ClimbingCandidate candidate);
    void considerWithActionId(ClimbingCandidate candidate, std::string_view actionId);
    void sortAndLimit(std::size_t limit);
    void swap(ClimbingCandidateSet& other) noexcept;
    [[nodiscard]] bool empty() const noexcept { return size_ == 0; }
    [[nodiscard]] std::size_t size() const noexcept { return size_; }
    [[nodiscard]] const ClimbingCandidate& front() const noexcept { return values_[0]; }
    [[nodiscard]] ClimbingCandidate takeFront() noexcept { return std::move(values_[0]); }
    [[nodiscard]] const ClimbingCandidate& operator[](std::size_t index) const noexcept { return values_[index]; }
    [[nodiscard]] const ClimbingCandidate* begin() const noexcept { return values_.data(); }
    [[nodiscard]] const ClimbingCandidate* end() const noexcept { return values_.data() + size_; }
    [[nodiscard]] std::span<const ClimbingCandidate> values() const noexcept { return {values_.data(), size_}; }
 
private:
    std::array<ClimbingCandidate, Capacity> values_{};
    std::size_t                             size_ = 0;
};
 
namespace detail {
struct ClimbingPredictionSequenceTag {};
}
 
using ClimbingPredictionSequence = eve::detail::StrongUint64<detail::ClimbingPredictionSequenceTag>;
 
struct ClimbingCandidateKey {
    std::string             actionId;
    ClimbingActionKind      kind = ClimbingActionKind::Mantle;
    std::uint64_t           definitionGeneration = 0;
    std::uint32_t           sortedRank = 0;
    std::uint64_t           fingerprint = 0;
    friend bool operator==(const ClimbingCandidateKey&, const ClimbingCandidateKey&) noexcept = default;
};
 
[[nodiscard]] EVENGINE_API_DOMAINS ClimbingCandidateKey makeClimbingCandidateKey(const ClimbingCandidate& candidate,
                                                                                 std::uint32_t sortedRank) noexcept;
 
struct ClimbingPredictionRequest {
    static constexpr std::string_view SchemaId = "evengine.climbing-prediction-request";
    static constexpr std::int64_t SchemaVersion = 1;
 
    ClimbingPredictionSequence sequence = ClimbingPredictionSequence::zero();
    eve::SimulationTick        clientTick = eve::SimulationTick::zero();
    ClimbingCandidateKey       candidate;
    eve::Value::Object         extensionMetadata;
};
 
enum class ClimbingPredictionDisposition : std::uint8_t { Accepted, Corrected, Rejected };
 
enum class ClimbingPredictionReason : std::uint8_t {
    None,
    CandidateMismatch,
    NoCandidate,
    TickTooFarAhead,
    RuntimeBusy,
    InvalidRequest
};
 
struct ClimbingPredictionDecision {
    static constexpr std::string_view SchemaId = "evengine.climbing-prediction-decision";
    static constexpr std::int64_t SchemaVersion = 1;
 
    ClimbingPredictionSequence    sequence = ClimbingPredictionSequence::zero();
    eve::SimulationTick           clientTick = eve::SimulationTick::zero();
    eve::SimulationTick           serverTick = eve::SimulationTick::zero();
    ClimbingPredictionDisposition disposition = ClimbingPredictionDisposition::Rejected;
    ClimbingPredictionReason      reason = ClimbingPredictionReason::InvalidRequest;
    ClimbingCandidateKey          authoritativeCandidate;
    eve::Value                    authoritativeSnapshot;
    eve::Value::Object            extensionMetadata;
};
 
[[nodiscard]] EVENGINE_API_DOMAINS eve::Result<eve::Value> encodeClimbingPredictionRequest(
    const ClimbingPredictionRequest& request);
[[nodiscard]] EVENGINE_API_DOMAINS eve::Result<ClimbingPredictionRequest> decodeClimbingPredictionRequest(
    const eve::Value& value);
[[nodiscard]] EVENGINE_API_DOMAINS eve::Result<eve::Value> encodeClimbingPredictionDecision(
    const ClimbingPredictionDecision& decision);
[[nodiscard]] EVENGINE_API_DOMAINS eve::Result<ClimbingPredictionDecision> decodeClimbingPredictionDecision(
    const eve::Value& value);
 
struct ClimbingStart {
    ClimbingExecutionId executionId = ClimbingExecutionId::zero();
    ClimbingCandidate   candidate;
};
 
enum class ClimbingPhase : std::uint8_t {
    Idle,
    Requested,
    Aligning,
    Launching,
    Climbing,
    Landing,
    Recovering,
    Hanging,
    Dropping,
    Completed,
    Cancelled,
    Failed,
    Balanced,
    Swinging
};
 
enum class ClimbingEventKind : std::uint8_t {
    Started,
    AnchorTransitionStarted,
    AnchorReached,
    ContactLeftHand,
    ContactRightHand,
    Landed,
    Hanging,
    Dropped,
    Completed,
    Cancelled,
    Failed
};
 
enum class ClimbingNotifyKind : std::uint8_t {
    ContactLeftHand,
    ContactRightHand,
    CollisionCompact,
    BranchOpen,
    BranchClose,
    Land
};
 
struct ClimbingEvent {
    ClimbingEventKind   kind = ClimbingEventKind::Started;
    std::string         actionId;
    eve::SimulationTick tick        = eve::SimulationTick::zero();
    ClimbingExecutionId executionId = ClimbingExecutionId::zero();
    std::vector<std::string> metadata;
};
 
enum class ClimbingRootMotionPolicy { ApplyActionWarp, PreserveSuppliedDelta };
enum class ClimbingObstacleCollision { Collide, IgnoreTraversedShape };
 
struct ClimbingMotionInput {
    Vec3  rootTranslation;
    Vec3  facing{0.f, 0.f, 1.f};
    Vec3  pelvisOffset;
    float rootYawRadians = 0.f;
    bool  hasRootMotion  = false;
    std::vector<ClimbingNotifyKind> notifies;
    ClimbingRootMotionPolicy        rootMotionPolicy  = ClimbingRootMotionPolicy::ApplyActionWarp;
    ClimbingObstacleCollision       obstacleCollision = ClimbingObstacleCollision::Collide;
};
 
struct ClimbingAdvance {
    ClimbingPhase              phase = ClimbingPhase::Idle;
    std::string                actionId;
    Vec3                       feet;
    Vec3                       desiredDelta;
    Vec3                       actualDelta;
    Vec3                       warpResidual;
    float                      normalizedTime = 0.f;
    bool                       constrained    = false;
    bool                       grounded       = false;
    HangSupport                support        = HangSupport::None;
    Vec3                       leftHandAnchor;
    Vec3                       rightHandAnchor;
    float                      contactWeight = 0.f;
    float                      leftHandWeight = 0.f;
    float                      rightHandWeight = 0.f;
    bool                       compactCollisionRequested = false;
    bool                       compactCollisionActive = false;
    bool                       branchWindowOpen = false;
    std::string                branchComboTag;
    ClimbingExecutionId        executionId   = ClimbingExecutionId::zero();
    Vec3                       appliedWarp;
    float                      desiredYawDelta = 0.f;
    std::string                cameraCueProfile;
    std::string                cameraCue;
    std::string                animationClipId;
    std::string                animationGraphNodeId;
    bool                       animationMirrored = false;
    float                      leftFootWeight = 0.f;
    float                      rightFootWeight = 0.f;
    float                      pelvisWeight = 0.f;
    Vec3                       terminalVelocity;
    bool                       hasTerminalVelocity = false;
};
 
enum class ClimbingDebugCapture : std::uint8_t { Disabled, Enabled };
 
struct ClimbingDebugQuery {
    std::string actionId;
    std::string code;
    Vec3        start;
    Vec3        end;
    float       radius = 0.f;
    float       height = 0.f;
};
 
struct ClimbingCandidateEvidence {
    std::string  actionId;
    std::string  code;
    std::int64_t biasCost     = 0;
    std::int64_t heightCost   = 0;
    std::int64_t distanceCost = 0;
    std::int64_t totalCost    = 0;
};
 
struct ClimbingMotionEvidence {
    eve::SimulationTick tick = eve::SimulationTick::zero();
    Vec3                plannedFeet;
    Vec3                actualFeet;
    Vec3                residual;
    float               capsuleHeight = 0.f;
    bool                constrained = false;
};
 
struct ClimbingDebugSnapshot {
    ClimbingPhase                  phase = ClimbingPhase::Idle;
    std::vector<ClimbingCandidate> candidates;
    Vec3                           accumulatedWarpResidual;
    std::uint32_t                  broadPhaseQueryCount = 0;
    std::uint32_t                  broadPhaseHitCount = 0;
    std::uint32_t                  queryCount = 0;
    std::string                    terminalCode;
    ClimbingExecutionId            executionId = ClimbingExecutionId::zero();
    std::vector<ClimbingDebugQuery> queries;
    std::vector<ClimbingCandidateEvidence> evidence;
    std::vector<ClimbingMotionEvidence> motion;
};
 
class EVENGINE_API_DOMAINS ClimbingRuntime {
public:
    static constexpr std::string_view SnapshotSchemaId = "evengine.climbing-runtime";
    static constexpr std::int64_t SnapshotSchemaVersion = 4;
    static constexpr std::size_t PendingEventCapacity = 64;
 
    ClimbingRuntime() = default;
    ClimbingRuntime(const ClimbingRuntime&) = delete;
    ClimbingRuntime& operator=(const ClimbingRuntime&) = delete;
    ClimbingRuntime(ClimbingRuntime&&) noexcept = default;
    ClimbingRuntime& operator=(ClimbingRuntime&&) noexcept = default;
    ~ClimbingRuntime() noexcept;
 
    [[nodiscard]] eve::Result<void> setProfile(ClimbingProfile profile);
    [[nodiscard]] eve::Result<void> reloadProfile(ClimbingProfile profile);
    [[nodiscard]] eve::Result<void> setProfileJson(std::string_view json);
    [[nodiscard]] eve::Result<void> reloadProfileJson(std::string_view json);
    [[nodiscard]] eve::Result<void> upsertAction(ClimbingActionDefinition action);
    [[nodiscard]] eve::Result<void> validateAnimationBinding(std::string_view           actionId,
                                                             const animation::AnimClip& clip);
    [[nodiscard]] eve::Result<ClimbingCandidateSet> probe(physics::World3D& world,
                                                          const ClimbingPose& pose) const;
    [[nodiscard]] eve::Result<void> probeInto(physics::World3D& world, const ClimbingPose& pose,
                                               ClimbingCandidateSet& output,
                                               eve::SimulationTick tick = eve::SimulationTick::zero()) const;
    [[nodiscard]] eve::Result<ClimbingCandidate> tryBegin(physics::World3D& world, const ClimbingPose& pose,
                                                          eve::SimulationTick tick);
    [[nodiscard]] eve::Result<ClimbingPredictionDecision> tryBeginPredicted(
        physics::World3D& world, const ClimbingPose& pose, const ClimbingPredictionRequest& request,
        eve::SimulationTick serverTick, std::uint64_t maxClientTickLead);
    [[nodiscard]] eve::Result<ClimbingCandidate> tryBeginAnchor(
        physics::World3D& world, ClimbingAnchorGraphHandleRef graph, const ClimbingAnchorNodeRef& node,
        ClimbingAnchorAgentId agentId, std::string_view actionId, const ClimbingPose& pose,
        eve::SimulationTick tick);
    [[nodiscard]] eve::Result<void> transitionAnchor(physics::World3D& world,
                                                      const ClimbingAnchorNodeRef& target,
                                                      ClimbingAnchorEdgeKind edgeKind,
                                                      std::string_view actionId,
                                                      eve::SimulationTick tick);
    [[nodiscard]] eve::Result<ClimbingAdvance> advance(physics::World3D& world, eve::SimulationStep step);
    [[nodiscard]] eve::Result<ClimbingAdvance> advance(physics::World3D& world, eve::SimulationStep step,
                                                       const ClimbingMotionInput& motion);
    [[nodiscard]] eve::Result<void> drop(eve::SimulationTick tick);
    [[nodiscard]] eve::Result<void> climbUp(eve::SimulationTick tick);
    [[nodiscard]] eve::Result<void> cancel(ClimbingCancelReason reason, eve::SimulationTick tick);
    [[nodiscard]] eve::Result<std::vector<ClimbingEvent>> drainEvents();
    [[nodiscard]] std::size_t pendingEventCount() const noexcept { return pendingEvents_.size(); }
    [[nodiscard]] ClimbingDebugSnapshot inspect() const;
    [[nodiscard]] ClimbingRuntimeCounters counters() const noexcept { return lastCounters_; }
    [[nodiscard]] const ClimbingTelemetryBuffer& telemetry() const noexcept { return telemetry_; }
    [[nodiscard]] ClimbingLocomotionPolicy locomotionPolicy() const noexcept;
    void clearTelemetry() noexcept { telemetry_.clear(); }
    void recordOrdinaryTick(eve::SimulationTick tick, std::uint32_t queryCount = 0,
                            std::uint32_t moverIterations = 0,
                            std::uint64_t elapsedNanoseconds = 0) noexcept;
    void setDebugCapture(ClimbingDebugCapture capture) noexcept;
    [[nodiscard]] eve::Result<eve::Value> snapshot() const;
    [[nodiscard]] eve::Result<std::string> snapshotJson() const;
    [[nodiscard]] eve::Result<void> restore(const eve::Value& value, physics::World3D& world);
    [[nodiscard]] eve::Result<void> restoreJson(std::string_view json, physics::World3D& world);
    [[nodiscard]] ClimbingPhase phase() const noexcept { return phase_; }
    [[nodiscard]] ClimbingExecutionId executionId() const noexcept {
        return execution_ ? execution_->executionId : ClimbingExecutionId::zero();
    }
    [[nodiscard]] std::uint64_t definitionGeneration() const noexcept { return definitionGeneration_; }
    [[nodiscard]] eve::Result<ClimbingAnchorNodeRef> currentAnchor() const;
 
private:
    friend class ClimbingSelectionSystem;
    friend class ClimbingServiceSelectionSystem;
 
    struct PreparedBegin {
        ClimbingExecutionId      executionId = ClimbingExecutionId::zero();
        ClimbingCandidate        candidate;
        ClimbingActionDefinition action;
        Vec3                     startFeet;
        eve::SimulationTick      tick = eve::SimulationTick::zero();
        bool                     conditionsSatisfied = false;
    };
 
    struct Execution {
        ClimbingExecutionId executionId = ClimbingExecutionId::zero();
        std::uint64_t       definitionGeneration = 1;
        ClimbingCandidate   candidate;
        ClimbingActionDefinition action;
        Vec3                     startFeet;
        Vec3                     currentFeet;
        Vec3                     lastPlannedFeet;
        eve::Duration            elapsed  = eve::Duration::zero();
        eve::Duration            duration = eve::Duration::zero();
        eve::SimulationTick      lastTick = eve::SimulationTick::zero();
        Vec3                     velocity;
        Vec3                     accumulatedResidual;
        float                    horizontalWarpUsed  = 0.f;
        float                    verticalWarpUsed    = 0.f;
        float                    facingWarpUsed      = 0.f;
        bool                     leftContactEmitted  = false;
        bool                     rightContactEmitted = false;
        bool                     landContactReleased = false;
        bool                     compactCollisionActive = false;
        bool                     branchWindowOpen = false;
        ClimbingAnchorGraphHandleRef anchorGraph;
        ClimbingAnchorNodeRef        anchorNode;
        ClimbingAnchorReservation    anchorReservation;
    };
 
    [[nodiscard]] eve::Result<PreparedBegin> prepareBegin(physics::World3D& world, const ClimbingPose& pose,
                                                          eve::SimulationTick tick);
    [[nodiscard]] eve::Result<PreparedBegin> prepareBeginCandidate(physics::World3D& world,
                                                                   const ClimbingPose& pose,
                                                                   eve::SimulationTick tick,
                                                                   ClimbingCandidate candidate);
    [[nodiscard]] eve::Result<ClimbingStart> commitBegin(PreparedBegin prepared);
    [[nodiscard]] eve::Result<void> publishProfile(ClimbingProfile profile, bool allowActiveExecution);
    [[nodiscard]] eve::Result<void> requireEventCapacity(std::size_t count, eve::SimulationTick tick) const;
    [[nodiscard]] eve::Result<void> releaseAnchorReservation();
    void enqueueEvent(ClimbingEvent event);
 
    ClimbingProfile                        profile_;
    ClimbingPhase                          phase_ = ClimbingPhase::Idle;
    std::optional<Execution>               execution_;
    mutable std::vector<ClimbingCandidate> lastCandidates_;
    mutable ClimbingCandidateSet            probeScratch_;
    mutable std::uint32_t                  lastQueryCount_ = 0;
    mutable ClimbingRuntimeCounters         lastCounters_;
    mutable ClimbingTelemetryBuffer         telemetry_;
    ClimbingDebugCapture                   debugCapture_ = ClimbingDebugCapture::Enabled;
    mutable std::vector<ClimbingDebugQuery> lastDebugQueries_;
    mutable std::vector<ClimbingCandidateEvidence> lastEvidence_;
    std::vector<ClimbingMotionEvidence>     motionEvidence_;
    std::string                            terminalCode_;
    std::unordered_set<std::string>        validatedAnimationActions_;
    std::string                            previousActionId_;
    std::uint64_t                          nextExecutionId_ = 1;
    std::uint64_t                          definitionGeneration_ = 1;
    std::vector<ClimbingEvent>             pendingEvents_;
};
 
struct ClimbingRuntimeHandleTag {};
using ClimbingRuntimeHandleRef = eve::script::RuntimeHandleRef<ClimbingRuntimeHandleTag>;
 
class EVENGINE_API_DOMAINS Climbing : public Module {
public:
    Module_REG(Climbing);
    [[nodiscard]] static eve::Result<ClimbingRuntimeHandleRef> newRuntime();
    [[nodiscard]] static eve::script::Borrowed<ClimbingRuntime> resolve(ClimbingRuntimeHandleRef reference) noexcept;
    [[nodiscard]] static eve::Result<void> release(ClimbingRuntimeHandleRef reference);
    [[nodiscard]] static bool isStale(ClimbingRuntimeHandleRef reference) noexcept;
    [[nodiscard]] static eve::Result<ClimbingAnchorGraphHandleRef> newAnchorGraph(
        ClimbingAnchorGraphDefinition graph, physics::World3D& world, physics::PhysicsBodyHandle body);
    [[nodiscard]] static eve::script::Borrowed<ClimbingAnchorGraphInstance> resolveAnchorGraph(
        ClimbingAnchorGraphHandleRef reference) noexcept;
    [[nodiscard]] static eve::Result<void> releaseAnchorGraph(ClimbingAnchorGraphHandleRef reference);
    [[nodiscard]] static bool isAnchorGraphStale(ClimbingAnchorGraphHandleRef reference) noexcept;
 
private:
    eve::script::RuntimeObjectRegistry<ClimbingAnchorGraphInstance, ClimbingAnchorGraphHandleTag> anchorGraphs_;
    eve::script::RuntimeObjectRegistry<ClimbingRuntime, ClimbingRuntimeHandleTag> runtimes_;
};
 
}  // namespace eve::climbing