feat(pathfinding2d): add route cost planning

Author: liuzqk

com.zerogamestudio.zeroengine.pathfinding2d/Runtime/Data/Platform2DPath.cs

@@ -54,6 +54,9 @@ public class Platform2DPath
         /// <summary>预计总耗时</summary>
         public float TotalDuration { get; private set; }
 
+        public PlatformRouteCost RouteCost { get; private set; } = PlatformRouteCost.Unreachable;
+        public bool CommandsValidated { get; private set; }
+
         /// <summary>是否还有剩余指令</summary>
         public bool HasNextCommand => CurrentIndex < Commands.Count;
 
@@ -136,6 +139,12 @@ public void SetStatus(PathStatus status)
             Status = status;
         }
 
+        public void SetRouteDiagnostics(PlatformRouteCost routeCost, bool commandsValidated)
+        {
+            RouteCost = routeCost;
+            CommandsValidated = commandsValidated;
+        }
+
         /// <summary>
         /// 检查路径是否过期
         /// </summary>

com.zerogamestudio.zeroengine.pathfinding2d/Runtime/Data/PlatformSurfaceSegment.cs

@@ -21,6 +21,9 @@ public class PlatformSurfaceSegment
         public int RightNodeId = -1;
         public readonly List<int> NodeIds = new List<int>();
 
+        public int Id => GroupId;
+        public float MinX => Left;
+        public float MaxX => Right;
         public float Width => Right - Left;
         public Vector2 Center => new Vector2((Left + Right) * 0.5f, Y);
 

com.zerogamestudio.zeroengine.pathfinding2d/Runtime/Platform2DPathfinder.cs

@@ -877,6 +877,37 @@ public bool TryGetSurfaceSegment(int surfaceGroupId, out PlatformSurfaceSegment
             return surfaceSegmentsById.TryGetValue(surfaceGroupId, out segment);
         }
 
+        public bool TryFindSurfaceSegmentAt(Vector3 position, float verticalTolerance, out PlatformSurfaceSegment segment)
+        {
+            foreach (var candidate in SurfaceSegments)
+            {
+                bool xInside = position.x >= candidate.MinX && position.x <= candidate.MaxX;
+                bool yClose = Mathf.Abs(position.y - candidate.Y) <= verticalTolerance;
+                if (!xInside || !yClose)
+                    continue;
+
+                segment = candidate;
+                return true;
+            }
+
+            segment = default;
+            return false;
+        }
+
+        public string BuildSurfaceSegmentDebug()
+        {
+            if (SurfaceSegments == null || SurfaceSegments.Count == 0)
+                return "none";
+
+            var parts = new List<string>(SurfaceSegments.Count);
+            foreach (var segment in SurfaceSegments)
+            {
+                parts.Add($"{segment.Id}:x=[{segment.MinX:F2},{segment.MaxX:F2}],y={segment.Y:F2},oneWay={segment.IsOneWay}");
+            }
+
+            return string.Join(" | ", parts);
+        }
+
         private void AttachExistingNodesToSegment(PlatformSurfaceSegment segment)
         {
             foreach (var node in Nodes)

com.zerogamestudio.zeroengine.pathfinding2d/Runtime/PlatformGraphGenerator.cs

@@ -14,6 +14,10 @@ public readonly struct PlatformNavigationSnapshot
         public readonly PlatformPathCompletionKind CompletionKind;
         public readonly string CommandDebug;
         public readonly string SurfaceSegmentDebug;
+        public readonly float RouteCost;
+        public readonly int CurrentSurfaceSegmentId;
+        public readonly int TargetSurfaceSegmentId;
+        public readonly bool CommandsValidated;
 
         public PlatformNavigationSnapshot(
             bool hasGraphGenerator,
@@ -27,7 +31,11 @@ public PlatformNavigationSnapshot(
             PlatformPathCompletionKind completionKind,
             string commandDebug,
             int surfaceSegmentCount = 0,
-            string surfaceSegmentDebug = null)
+            string surfaceSegmentDebug = null,
+            float routeCost = 0f,
+            int currentSurfaceSegmentId = -1,
+            int targetSurfaceSegmentId = -1,
+            bool commandsValidated = false)
         {
             HasGraphGenerator = hasGraphGenerator;
             IsGenerated = isGenerated;
@@ -41,6 +49,10 @@ public PlatformNavigationSnapshot(
             CompletionKind = completionKind;
             CommandDebug = commandDebug;
             SurfaceSegmentDebug = surfaceSegmentDebug ?? "none";
+            RouteCost = routeCost;
+            CurrentSurfaceSegmentId = currentSurfaceSegmentId;
+            TargetSurfaceSegmentId = targetSurfaceSegmentId;
+            CommandsValidated = commandsValidated;
         }
     }
 }

com.zerogamestudio.zeroengine.pathfinding2d/Runtime/PlatformNavigationSnapshot.cs

@@ -11,6 +11,7 @@ public enum PlatformPathFailureReason
         EndNodeNotFound,
         PathNotFound,
         PartialPath,
-        PartialPathUnavailable
+        PartialPathUnavailable,
+        InvalidCommand
     }
 }

com.zerogamestudio.zeroengine.pathfinding2d/Runtime/PlatformPathFailureReason.cs

@@ -9,19 +9,27 @@ public readonly struct PlatformPathRequest
         public readonly bool ForceRequest;
         public readonly bool ProjectTargetToGround;
         public readonly float ProjectionDistance;
+        public readonly bool? AllowPartialPathOverride;
 
         public PlatformPathRequest(
             Vector3 start,
             Vector3 target,
             bool forceRequest = false,
             bool projectTargetToGround = false,
-            float projectionDistance = 1.5f)
+            float projectionDistance = 1.5f,
+            bool? allowPartialPathOverride = null)
         {
             Start = start;
             Target = target;
             ForceRequest = forceRequest;
             ProjectTargetToGround = projectTargetToGround;
             ProjectionDistance = projectionDistance;
+            AllowPartialPathOverride = allowPartialPathOverride;
+        }
+
+        public bool ShouldAllowPartialPath(bool configDefault)
+        {
+            return AllowPartialPathOverride ?? configDefault;
         }
     }
 }

com.zerogamestudio.zeroengine.pathfinding2d/Runtime/PlatformPathRequest.cs

@@ -0,0 +1,42 @@
+namespace ZeroEngine.Pathfinding2D
+{
+    public readonly struct PlatformRouteCost
+    {
+        public readonly float Total;
+        public readonly float HorizontalDistance;
+        public readonly float VerticalDistance;
+        public readonly int JumpCount;
+        public readonly int FallCount;
+        public readonly int DropDownCount;
+        public readonly int CommandCount;
+
+        public PlatformRouteCost(
+            float total,
+            float horizontalDistance,
+            float verticalDistance,
+            int jumpCount,
+            int fallCount,
+            int dropDownCount,
+            int commandCount)
+        {
+            Total = total;
+            HorizontalDistance = horizontalDistance;
+            VerticalDistance = verticalDistance;
+            JumpCount = jumpCount;
+            FallCount = fallCount;
+            DropDownCount = dropDownCount;
+            CommandCount = commandCount;
+        }
+
+        public static PlatformRouteCost Unreachable => new PlatformRouteCost(
+            float.PositiveInfinity,
+            0f,
+            0f,
+            0,
+            0,
+            0,
+            0);
+
+        public bool IsReachable => !float.IsPositiveInfinity(Total);
+    }
+}

com.zerogamestudio.zeroengine.pathfinding2d/Runtime/PlatformRouteCost.cs

@@ -0,0 +1,24 @@
+using UnityEngine;
+
+namespace ZeroEngine.Pathfinding2D
+{
+    public readonly struct PlatformRouteQuery
+    {
+        public readonly Vector3 StartPosition;
+        public readonly Vector3 TargetPosition;
+        public readonly bool ProjectTargetToGround;
+        public readonly bool AllowPartialPath;
+
+        public PlatformRouteQuery(
+            Vector3 startPosition,
+            Vector3 targetPosition,
+            bool projectTargetToGround = true,
+            bool allowPartialPath = false)
+        {
+            StartPosition = startPosition;
+            TargetPosition = targetPosition;
+            ProjectTargetToGround = projectTargetToGround;
+            AllowPartialPath = allowPartialPath;
+        }
+    }
+}