@alpsckr/unitycli 0.4.3 → 0.4.4

package/unitypkg/Editor/Tools/profiler/frame-debugger/events.cs

@@ -2,33 +2,42 @@
 using System;
 using System.Collections.Generic;
 using System.Globalization;
-using System.IO;
-using System.Reflection;
-using UnityEditor;
-using UnityEngine;
-using UnityEngine.Profiling;
 
 namespace UnityCli
 {
+    /// <summary>profiler.frame-debugger.events — 逐个 raw event 读取，不复制完整事件数组。</summary>
     public class ProfilerFrameDebuggerEventsTool : IUnityCliTool<ProfilerFrameDebuggerEventsTool.Request, ProfilerFrameDebuggerEventsTool.Result>
     {
-        public sealed class Request { public int? PageSize { get; set; } public int? Cursor { get; set; } }
+        public sealed class Request
+        {
+            [UnityCliRange(1L, 500L)] public int? PageSize { get; set; }
+            public string Cursor { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
+        }
 
         public sealed class Result
         {
             public long TotalEvents { get; set; }
-            public List<FrameDebuggerEvent> Events { get; set; }
-            public string Note { get; set; }
-            public long? NextCursor { get; set; }
+            [UnityCliItemsRange(0, 500)] public List<FrameDebuggerEvent> Events { get; set; }
+            public PageInfo PageInfo { get; set; }
+            public UnityCliRequestBudgetUsage Budget { get; set; }
+        }
+
+        public sealed class PageInfo
+        {
+            public long ReturnedCount { get; set; }
+            public long PageSize { get; set; }
+            public string Cursor { get; set; }
+            public string NextCursor { get; set; }
+            public bool Complete { get; set; }
+            public bool Truncated { get; set; }
+            public string Generation { get; set; }
         }
 
-        // 单个 draw call 事件:字段按 FrameDebuggerUtility 反射可用性填充(不可用字段省略)
         public sealed class FrameDebuggerEvent
         {
             public long Index { get; set; }
             public string Name { get; set; }
-            public string EventType { get; set; }
-            public string GameObjectInstanceID { get; set; }
             public string ShaderName { get; set; }
             public string PassName { get; set; }
             public string VertexCount { get; set; }
@@ -40,100 +49,92 @@ namespace UnityCli
         public ToolDescriptor Describe() => new()
         {
             Name = "profiler.frame-debugger.events",
-            Summary = "Read draw call events captured by the Frame Debugger, paginated.",
-            Description = "Read draw call events captured by the Frame Debugger, paginated. Returns shaderName, vertexCount, indexCount and similar fields per event when available.",
-            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            Summary = "Page one bounded Frame Debugger capture from stable raw event indices.",
+            Description = "Read raw Frame Debugger event indices directly without copying the full event array. pageSize is 1..500 (default 50); pass pageInfo.nextCursor unchanged to continue the same capture. The opaque cursor binds the Editor listener, CLI enable/disable generation, event count and capture boundary signature; a changed or deleted capture returns E_CONTINUATION_STALE. Event reflection, getters, scans, elapsed main-thread time and UTF-8 output share the documented request budget. Read-only in Edit and Play Mode.",
+            Group = "profiler", DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
             DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
-            Examples = new[] { new ToolExample { Description = "Read first page of events", Input = new Request { PageSize = 50, Cursor = 0 } } }
+            Examples = new[] { new ToolExample { Description = "Read first raw event page", Input = new Request { PageSize = 50 } } }
         };
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
+            request = request ?? new Request();
             if (!FrameDebuggerReflection.Available)
-            {
-                throw new UnityCliBridge.BridgeCommandException("E_FRAME_DEBUGGER_UNAVAILABLE",
-                    "FrameDebuggerUtility not found via reflection.",
-                    "Run in a Unity Editor with Frame Debugger support.");
-            }
-            var pageSize = request.PageSize ?? 50;
-            var cursor = request.Cursor ?? 0;
-            var totalEvents = FrameDebuggerReflection.GetEventCount();
-
-            if (totalEvents == 0)
-            {
-                return new System.Threading.Tasks.ValueTask<Result>(new Result
-                {
-                    TotalEvents = 0,
-                    Events = new List<FrameDebuggerEvent>(),
-                    Note = "Frame Debugger has no events. Is it enabled?"
-                });
-            }
+                throw new UnityCliBridge.BridgeCommandException("E_FRAME_DEBUGGER_UNAVAILABLE", "FrameDebuggerUtility is unavailable.", "Use a Unity Editor with Frame Debugger support.");
+            return new System.Threading.Tasks.ValueTask<Result>(ReadPage(request, ctx.UseReadBudget(request.Budget)));
+        }
 
-            // 反射读取事件描述数组(含 type/name 信息)
-            object[] frameEvents = null;
-            if (FrameDebuggerReflection.GetEventsMethod != null)
+        /// <summary>按 raw event index 推进；只有成功 materialize 的事件才会移动 continuation。</summary>
+        internal static Result ReadPage(Request request, UnityCliRequestBudget budget)
+        {
+            var pageSize = request.PageSize ?? 50;
+            var total = FrameDebuggerReflection.GetEventCount(budget);
+            var generation = FrameDebuggerReflection.CaptureGeneration(total, budget);
+            var index = 0;
+            if (!string.IsNullOrEmpty(request.Cursor))
             {
-                try
-                {
-                    var raw = FrameDebuggerReflection.GetEventsMethod.Invoke(null, null);
-                    if (raw is Array arr) { frameEvents = new object[arr.Length]; arr.CopyTo(frameEvents, 0); }
-                }
-                catch { /* 忽略,逐个读取 */ }
+                string position;
+                if (!UnityCliContinuationToken.TryParse(request.Cursor, "profiler.frame-debugger.events", generation, out position)
+                    || !int.TryParse(position, NumberStyles.None, CultureInfo.InvariantCulture, out index)
+                    || index < 0 || index >= total)
+                    throw Stale();
             }
 
-            var end = Math.Min(cursor + pageSize, totalEvents);
             var events = new List<FrameDebuggerEvent>();
-            for (int i = cursor; i < end; i++)
+            while (index < total && events.Count < pageSize)
             {
-                var entry = new FrameDebuggerEvent { Index = i };
-                if (FrameDebuggerReflection.EventNameMethod != null)
-                {
-                    try { entry.Name = (string)FrameDebuggerReflection.EventNameMethod.Invoke(null, new object[] { i }); }
-                    catch { /* 跳过 name */ }
-                }
-                if (frameEvents != null && i < frameEvents.Length)
-                {
-                    entry.EventType = FrameDebuggerReflection.ReadField(frameEvents[i], "type");
-                    entry.GameObjectInstanceID = FrameDebuggerReflection.ReadField(frameEvents[i], "gameObjectInstanceID");
-                }
-                if (FrameDebuggerReflection.GetEventDataMethod != null)
+                var current = index;
+                if (!budget.TryConsumeScannedRecord() || !budget.TryConsumeNode()) break;
+                try
                 {
-                    try
+                    var entry = new FrameDebuggerEvent { Index = current, Name = FrameDebuggerReflection.EventName(current, budget) };
+                    var data = FrameDebuggerReflection.EventData(current, budget);
+                    if (data != null)
                     {
-                        var paramInfos = FrameDebuggerReflection.GetEventDataMethod.GetParameters();
-                        object eventData;
-                        if (paramInfos.Length == 2 && FrameDebuggerReflection.EventDataType != null)
-                        {
-                            eventData = Activator.CreateInstance(FrameDebuggerReflection.EventDataType);
-                            var args = new object[] { i, eventData };
-                            var ok = FrameDebuggerReflection.GetEventDataMethod.Invoke(null, args);
-                            eventData = (ok is true) ? args[1] : null;
-                        }
-                        else
-                        {
-                            eventData = FrameDebuggerReflection.GetEventDataMethod.Invoke(null, new object[] { i });
-                        }
-                        if (eventData != null)
-                        {
-                            entry.ShaderName = FrameDebuggerReflection.ReadField(eventData, "shaderName");
-                            entry.PassName = FrameDebuggerReflection.ReadField(eventData, "passName");
-                            entry.VertexCount = FrameDebuggerReflection.ReadField(eventData, "vertexCount");
-                            entry.IndexCount = FrameDebuggerReflection.ReadField(eventData, "indexCount");
-                            entry.InstanceCount = FrameDebuggerReflection.ReadField(eventData, "instanceCount");
-                            entry.MeshName = FrameDebuggerReflection.ReadField(eventData, "meshName");
-                        }
+                        entry.ShaderName = FrameDebuggerReflection.ReadField(data, "shaderName", budget);
+                        entry.PassName = FrameDebuggerReflection.ReadField(data, "passName", budget);
+                        entry.VertexCount = FrameDebuggerReflection.ReadField(data, "vertexCount", budget);
+                        entry.IndexCount = FrameDebuggerReflection.ReadField(data, "indexCount", budget);
+                        entry.InstanceCount = FrameDebuggerReflection.ReadField(data, "instanceCount", budget);
+                        entry.MeshName = FrameDebuggerReflection.ReadField(data, "meshName", budget);
                     }
-                    catch { /* 跳过该事件详细数据 */ }
+                    if (!budget.TryReserveSerializedUtf8(entry.Name) || !budget.TryReserveSerializedUtf8(entry.ShaderName)
+                        || !budget.TryReserveSerializedUtf8(entry.PassName) || !budget.TryReserveSerializedUtf8(entry.VertexCount)
+                        || !budget.TryReserveSerializedUtf8(entry.IndexCount) || !budget.TryReserveSerializedUtf8(entry.InstanceCount)
+                        || !budget.TryReserveSerializedUtf8(entry.MeshName)) break;
+                    events.Add(entry);
+                    index++;
                 }
-                events.Add(entry);
+                catch (UnityCliRequestBudgetExceededException) { break; }
             }
-
-            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            if (events.Count == 0 && index < total) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension ?? "scannedRecords");
+            var nextCursor = index < total
+                ? UnityCliContinuationToken.Create("profiler.frame-debugger.events", generation, index.ToString(CultureInfo.InvariantCulture))
+                : null;
+            return new Result
             {
-                TotalEvents = totalEvents,
+                TotalEvents = total,
                 Events = events,
-                NextCursor = end < totalEvents ? (long?)end : null
-            });
+                PageInfo = new PageInfo
+                {
+                    ReturnedCount = events.Count,
+                    PageSize = pageSize,
+                    Cursor = request.Cursor,
+                    NextCursor = nextCursor,
+                    Complete = nextCursor == null,
+                    Truncated = nextCursor != null,
+                    Generation = generation
+                },
+                Budget = budget.Usage()
+            };
+        }
+
+        private static UnityCliBridge.BridgeCommandException Stale()
+        {
+            return new UnityCliBridge.BridgeCommandException(
+                "E_CONTINUATION_STALE",
+                "The Frame Debugger continuation no longer identifies the same capture.",
+                "Start a new profiler.frame-debugger.events read without cursor.");
         }
     }
 }