@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/profiler/capture.cs

@@ -0,0 +1,188 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// profiler.capture — 采集 Profiler 帧数据到文件。
+    /// 多帧/跨帧采集通过统一 wait scheduler 驱动，并在同一次公开调用中返回最终结果。
+    /// </summary>
+    public class ProfilerCaptureTool : IUnityCliTool<ProfilerCaptureTool.Request, ProfilerCaptureTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Path { get; set; }
+            public bool Overwrite { get; set; }
+            public string Format { get; set; }
+            public int? DurationMs { get; set; }
+            public int? Frames { get; set; }
+            public string CaptureTag { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string ArtifactPath { get; set; }
+            public string ProfilerPath { get; set; }
+            public long DurationMs { get; set; }
+            public long RequestedDurationMs { get; set; }
+            public long StartFrame { get; set; }
+            public long EndFrame { get; set; }
+            public string MetadataSidecar { get; set; }
+            public ProfilerState Profiler { get; set; }
+            public List<ProfilerPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.capture",
+            Summary = "Capture profiler frame data to a file (single-frame or cross-frame) via the unified wait scheduler.",
+            Description = "Capture profiler frame data to a file. format=raw with durationMs>0 or frames>1 performs cross-frame capture through the framework wait scheduler; single-frame captures complete synchronously. Multi-frame raw artifacts can be large, so start with frames=1 and increase deliberately. startFrame/endFrame report Time.frameCount at the beginning and end of capture, so they advance naturally in Play Mode and may stay unchanged when Unity is only idling in the Editor. Pass captureTag to also write a <path>.metadata.json sidecar for archival and correlation.",
+            Group = "profiler",DestructiveHint = true, SideEffects = new[] { "persistent-artifact-write" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Capture one raw profiler snapshot with tag", Input = new Request { Path = "baseline.raw", Format = "raw", Frames = 1, CaptureTag = "baseline-before-opt" } } }
+        };
+
+        public async ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default)
+        {
+            var outputPath = ProfilerToolSupport.ResolveOutputPath(request.Path);
+            if (File.Exists(outputPath) && !request.Overwrite)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS",
+                    "Profiler artifact already exists: " + outputPath,
+                    "Pass overwrite=true or choose a different output path.");
+            }
+
+            ctx.CommitEffect();
+            Directory.CreateDirectory(Path.GetDirectoryName(outputPath));
+            if (File.Exists(outputPath))
+            {
+                try { File.Delete(outputPath); }
+                catch (Exception exception)
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_PROFILER_ARTIFACT_PREPARE_FAILED",
+                        "Failed to replace existing profiler artifact: " + exception.Message,
+                        "Close programs using the output file or choose a different path.");
+                }
+            }
+            var startedAt = DateTime.UtcNow;
+            var format = ProfilerToolSupport.NormalizeProfilerFormat(request.Format, outputPath);
+            var durationMs = Math.Max(0, request.DurationMs ?? 0);
+            var frames = Math.Max(0, request.Frames ?? 1);
+            var captureTag = request.CaptureTag;
+
+            if (format == "raw" && (durationMs > 0 || frames > 1))
+            {
+                var totalFrames = Math.Max(1, frames);
+                var startFrame = (long)Time.frameCount;
+                var internalDeadlineMs = Math.Max(durationMs, 30000);
+                var internalDeadline = startedAt.AddMilliseconds(internalDeadlineMs);
+                var previousLogFile = Profiler.logFile;
+                var previousEnabled = Profiler.enabled;
+                var previousBinaryLog = Profiler.enableBinaryLog;
+                Profiler.logFile = outputPath;
+                Profiler.enableBinaryLog = true;
+                Profiler.enabled = true;
+
+                var capturedFrames = 0;
+                try
+                {
+                    while (capturedFrames < totalFrames)
+                    {
+                        ct.ThrowIfCancellationRequested();
+                        if (DateTime.UtcNow > internalDeadline)
+                        {
+                            throw new UnityCliBridge.BridgeCommandException("E_PROFILER_CAPTURE_TIMEOUT",
+                                "Profiler capture did not complete all frames before the deadline.",
+                                "Reduce the requested frame count or duration, or check Unity Editor performance.");
+                        }
+
+                        Profiler.BeginSample("UnityCliProfilerCapture");
+                        Profiler.EndSample();
+                        capturedFrames += 1;
+
+                        if (capturedFrames < totalFrames)
+                        {
+                            await ctx.Wait.NextFrame(1, ct);
+                        }
+                    }
+                }
+                finally
+                {
+                    RestoreProfiler(previousLogFile, previousEnabled, previousBinaryLog);
+                }
+
+                ProfilerToolSupport.EnsureRawProfilerArtifact(outputPath);
+                var finishedAt = DateTime.UtcNow;
+                var endFrame = (long)Time.frameCount;
+                if (!string.IsNullOrEmpty(captureTag))
+                {
+                    ProfilerToolSupport.WriteCaptureMetadataSidecar(outputPath, ctx.RequestId, captureTag, startFrame, endFrame, startedAt, finishedAt);
+                }
+                return BuildResult(outputPath, format, durationMs, totalFrames, startFrame, endFrame, captureTag, startedAt, finishedAt);
+            }
+
+            if (format == "raw")
+            {
+                ProfilerToolSupport.CaptureRawProfilerSync(outputPath);
+            }
+            else
+            {
+                ProfilerToolSupport.WriteAndVerifyJsonProfilerArtifact(outputPath, BuildJsonArtifact(ctx.RequestId, startedAt, durationMs, frames));
+            }
+
+            var finishedSyncAt = DateTime.UtcNow;
+            var syncStartFrame = (long)Time.frameCount;
+            var syncEndFrame = syncStartFrame;
+            if (!string.IsNullOrEmpty(captureTag))
+            {
+                ProfilerToolSupport.WriteCaptureMetadataSidecar(outputPath, ctx.RequestId, captureTag, syncStartFrame, syncEndFrame, startedAt, finishedSyncAt);
+            }
+            return BuildResult(outputPath, format, durationMs, frames, syncStartFrame, syncEndFrame, captureTag, startedAt, finishedSyncAt);
+        }
+
+        private static void RestoreProfiler(string previousLogFile, bool previousEnabled, bool previousBinaryLog)
+        {
+            Profiler.enabled = previousEnabled;
+            Profiler.enableBinaryLog = previousBinaryLog;
+            Profiler.logFile = previousLogFile;
+        }
+
+        private static Result BuildResult(string outputPath, string format, int durationMs, long frames, long startFrame, long endFrame, string captureTag, DateTime startedAt, DateTime finishedAt)
+        {
+            return new Result
+            {
+                ArtifactPath = outputPath,
+                ProfilerPath = outputPath,
+                DurationMs = (long)(finishedAt - startedAt).TotalMilliseconds,
+                RequestedDurationMs = (long)durationMs,
+                StartFrame = startFrame,
+                EndFrame = endFrame,
+                MetadataSidecar = string.IsNullOrEmpty(captureTag) ? null : outputPath + ".metadata.json",
+                Profiler = ProfilerToolSupport.BuildProfilerState(),
+                PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.capture", Path = outputPath } }
+            };
+        }
+
+        private static string BuildJsonArtifact(string requestId, DateTime startedAt, int durationMs, int frames)
+        {
+            return UnityCliSerializer.Serialize(new ProfilerArtifactFile
+            {
+                RequestId = requestId,
+                StartedAt = startedAt.ToString("O", CultureInfo.InvariantCulture),
+                DurationMs = durationMs,
+                Frames = frames,
+                Profiler = ProfilerToolSupport.BuildProfilerState(),
+                Memory = ProfilerToolSupport.BuildProfilerMemory()
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/profiler/clear.cs

@@ -0,0 +1,57 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerClearTool : IUnityCliTool<ProfilerClearTool.Request, ProfilerClearTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public bool DryRun { get; set; } public bool Cleared { get; set; } public List<ProfilerPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.clear", Summary = "Clear all collected profiler data.",
+            Description = "Clear all collected profiler data from the current Editor session. Supports dry-run.",
+            Group = "profiler",DestructiveHint = false, SupportsDryRun = true, SideEffects = new[] { "profiler-data-clear" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Clear profiler data", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (ctx.DryRun)
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = true, PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.clear", SideEffects = "clears-profiler-data" } } });
+            // Unity 2022.3 通过 ClearAllFrames 清空当前 session，并以帧范围读回作为完成证明。
+            var driverType = FindType("UnityEditorInternal.ProfilerDriver");
+            var clearMethod = driverType?.GetMethod("ClearAllFrames", BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
+            if (clearMethod == null)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_CLEAR_UNSUPPORTED", "ProfilerDriver.ClearAllFrames is unavailable.", "Use a supported Unity Editor version that exposes ProfilerDriver.ClearAllFrames.");
+            ctx.CommitEffect();
+            clearMethod.Invoke(null, null);
+            var firstFrameIndex = ProfilerToolSupport.ProfilerDriverIntProperty("firstFrameIndex", -1);
+            var lastFrameIndex = ProfilerToolSupport.ProfilerDriverIntProperty("lastFrameIndex", -1);
+            if (firstFrameIndex >= 0 || lastFrameIndex >= 0)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_CLEAR_STATE_MISMATCH", "ProfilerDriver still exposes collected frames after clearing.", "Inspect the Profiler window and retry.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Cleared = true, PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.clear" } } });
+        }
+
+        private static Type FindType(string fullName)
+        {
+            foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
+            {
+                Type type = null;
+                try { type = assembly.GetType(fullName, false); } catch { }
+                if (type != null) return type;
+            }
+            return null;
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/profiler/counter.cs

@@ -0,0 +1,34 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerCounterTool : IUnityCliTool<ProfilerCounterTool.Request, ProfilerCounterTool.Result>
+    {
+        public sealed class Request { public string Category { get; set; } public string Counter { get; set; } }
+        public sealed class Result { public ProfilerState Profiler { get; set; } public List<ProfilerCounterEntry> Counters { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.counter", Summary = "Read current profiler counter values, optionally narrowed by category and counter name.",
+            Description = "Read current profiler counter values and available counter metadata, optionally narrowed by category and counter name. Read-only.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Read memory counters", Input = new Request { Category = "memory" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) => new System.Threading.Tasks.ValueTask<Result>(new Result
+        {
+            Profiler = ProfilerToolSupport.BuildProfilerState(),
+            Counters = ProfilerToolSupport.BuildProfilerCounters(request.Category, request.Counter)
+        });
+    }
+}
+#endif

package/unitypkg/Editor/Tools/profiler/deep.cs

@@ -0,0 +1,48 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerDeepTool : IUnityCliTool<ProfilerDeepTool.Request, ProfilerDeepTool.Result>
+    {
+        public sealed class Request { public bool? Enabled { get; set; } }
+        public sealed class Result { public bool DeepProfiling { get; set; } public bool Previous { get; set; } public bool Changed { get; set; } public ProfilerState Profiler { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.deep", Summary = "Read or toggle Unity Deep Profiling at runtime (must be stopped to change).",
+            Description = "Read or toggle Unity Deep Profiling. Pass enabled=true/false to change Profiler session state; omit enabled for a read. Toggling requires the Profiler to be stopped.",
+            Group = "profiler",DestructiveHint = false, SideEffects = new[] { "profiler-session-state" }, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Read deep profiling state", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var previous = ProfilerToolSupport.GetProfilerDeepProfiling();
+            var hasEnabled = request.Enabled.HasValue;
+            var sessionEnabled = ProfilerToolSupport.GetProfilerSessionEnabled();
+            if (hasEnabled && sessionEnabled)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_DEEP_REQUIRES_STOP",
+                    "Cannot change Deep Profiling while the Profiler is recording.",
+                    "Run tools run profiler.stop first, then set deep profiling, then profiler.start again.");
+            }
+            var applied = previous;
+            if (hasEnabled) { ctx.CommitEffect(); ProfilerToolSupport.SetProfilerDeepProfiling(request.Enabled.Value); applied = request.Enabled.Value; }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                DeepProfiling = applied, Previous = previous,
+                Changed = hasEnabled && applied != previous, Profiler = ProfilerToolSupport.BuildProfilerState()
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/profiler/export.cs

@@ -0,0 +1,85 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerExportTool : IUnityCliTool<ProfilerExportTool.Request, ProfilerExportTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Path { get; set; } public string Format { get; set; } public bool Overwrite { get; set; } public string CaptureTag { get; set; } }
+        public sealed class Result { public string ArtifactPath { get; set; } public string ProfilerPath { get; set; } public long DurationMs { get; set; } public long Frames { get; set; } public long StartFrame { get; set; } public long EndFrame { get; set; } public string MetadataSidecar { get; set; } public ProfilerState Profiler { get; set; } public List<ProfilerPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.export", Summary = "Export a profiler snapshot artifact in JSON or raw profiler format.",
+            Description = "Export a profiler snapshot artifact in JSON or raw profiler format to the requested path. Single-frame synchronous export.",
+            Group = "profiler",DestructiveHint = true, SideEffects = new[] { "persistent-artifact-write" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Export profiler JSON", Input = new Request { Path = "profile.json", Overwrite = true } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var outputPath = ResolveOutputPath(request.Path);
+            if (File.Exists(outputPath) && !request.Overwrite)
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Profiler artifact already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
+            ctx.CommitEffect();
+            Directory.CreateDirectory(Path.GetDirectoryName(outputPath));
+            var startedAt = DateTime.UtcNow;
+            var format = ProfilerToolSupport.NormalizeProfilerFormat(request.Format, outputPath);
+            if (format == "raw")
+            {
+                // 单帧同步采集
+                ProfilerToolSupport.CaptureRawProfilerSync(outputPath);
+            }
+            else
+            {
+                // JSON 格式:写入状态/内存/帧/计数器摘要
+                ProfilerToolSupport.WriteAndVerifyJsonProfilerArtifact(outputPath, BuildProfilerArtifactJson(ctx.RequestId, startedAt, 0, 1));
+            }
+            var finishedAt = DateTime.UtcNow;
+            var elapsedMs = (long)(finishedAt - startedAt).TotalMilliseconds;
+            var startFrame = (long)Time.frameCount;
+            var endFrame = startFrame;
+            var captureTag = request.CaptureTag;
+            if (!string.IsNullOrEmpty(captureTag))
+                ProfilerToolSupport.WriteCaptureMetadataSidecar(outputPath, ctx.RequestId, captureTag, startFrame, endFrame, startedAt, finishedAt);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                ArtifactPath = outputPath, ProfilerPath = outputPath, DurationMs = elapsedMs,
+                Frames = 1, StartFrame = startFrame, EndFrame = endFrame,
+                MetadataSidecar = string.IsNullOrEmpty(captureTag) ? null : outputPath + ".metadata.json",
+                Profiler = ProfilerToolSupport.BuildProfilerState(),
+                PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.export", Path = outputPath } }
+            });
+        }
+
+        private static string ResolveOutputPath(string rawPath)
+        {
+            if (string.IsNullOrEmpty(rawPath))
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_PATH_REQUIRED", "Profiler export requires a path.", "Pass --path <path>.");
+            var normalized = rawPath.Replace('\\', Path.DirectorySeparatorChar).Replace('/', Path.DirectorySeparatorChar);
+            return Path.GetFullPath(Path.IsPathRooted(normalized) ? normalized : Path.Combine(ProfilerToolSupport.ProjectRoot(), normalized));
+        }
+
+        private static string BuildProfilerArtifactJson(string requestId, DateTime startedAt, int durationMs, int frames)
+        {
+            return UnityCliSerializer.Serialize(new ProfilerArtifactFile
+            {
+                RequestId = requestId,
+                StartedAt = startedAt.ToString("O", System.Globalization.CultureInfo.InvariantCulture),
+                DurationMs = durationMs,
+                Frames = frames,
+                Profiler = ProfilerToolSupport.BuildProfilerState(),
+                Memory = ProfilerToolSupport.BuildProfilerMemory()
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,53 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerFrameDebuggerDisableTool : IUnityCliTool<ProfilerFrameDebuggerDisableTool.Request, ProfilerFrameDebuggerDisableTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public bool Enabled { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.frame-debugger.disable",
+            Summary = "Disable the Unity Frame Debugger.",
+            Description = "Disable the Unity Frame Debugger for the current Editor session. Use this after profiler.frame-debugger.events when draw-call inspection is complete; it returns enabled=false without modifying project assets.",
+            Group = "profiler",DestructiveHint = false, SideEffects = new[] { "frame-debugger-state" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Disable Frame Debugger", Input = new Request { } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            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.");
+            }
+            ctx.CommitEffect();
+            try { FrameDebuggerReflection.SetEnabled(false); }
+            catch (Exception ex)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_FRAME_DEBUGGER_FAILED",
+                    "Failed to disable Frame Debugger: " + ex.Message,
+                    "Check Unity Console.");
+            }
+            var stable = await ctx.Wait.UntilStable(
+                () => !FrameDebuggerReflection.GetEnabled(),
+                TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct: ct);
+            var enabled = FrameDebuggerReflection.GetEnabled();
+            if (!stable || enabled) throw new UnityCliBridge.BridgeCommandException("E_FRAME_DEBUGGER_STATE_MISMATCH", "Frame Debugger disable write did not produce a disabled readback.", "Check Frame Debugger availability and retry.");
+            return new Result { Enabled = enabled };
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,66 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerFrameDebuggerEnableTool : IUnityCliTool<ProfilerFrameDebuggerEnableTool.Request, ProfilerFrameDebuggerEnableTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public bool Enabled { get; set; } public long EventCount { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.frame-debugger.enable",
+            Summary = "Enable the Unity Frame Debugger to capture draw call events.",
+            Description = "Enable the Unity Frame Debugger to capture draw call events for the current Editor session. In Play Mode the game must be paused first with editor.pause; this opens the Frame Debugger window and returns the captured event count.",
+            Group = "profiler",DestructiveHint = false, SideEffects = new[] { "frame-debugger-state", "editor-window-state" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Enable Frame Debugger", Input = new Request { } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            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.");
+            }
+            // Play Mode 下必须暂停才能采集事件；验证通过后才可打开窗口。
+            if (EditorApplication.isPlaying && !EditorApplication.isPaused)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_FRAME_DEBUGGER_REQUIRES_PAUSE",
+                    "Game must be paused before enabling Frame Debugger.",
+                    "Pause the editor (editor.pause) first, then retry profiler.frame-debugger.enable.");
+            }
+            ctx.CommitEffect();
+            EditorApplication.ExecuteMenuItem("Window/Analysis/Frame Debugger");
+            try { FrameDebuggerReflection.SetEnabled(true); }
+            catch (Exception ex)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_FRAME_DEBUGGER_FAILED",
+                    "Failed to enable Frame Debugger: " + ex.Message,
+                    "Check Unity Console.");
+            }
+            var stable = await ctx.Wait.UntilStable(
+                () => FrameDebuggerReflection.GetEnabled(),
+                TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct: ct);
+            var enabled = FrameDebuggerReflection.GetEnabled();
+            if (!stable || !enabled) throw new UnityCliBridge.BridgeCommandException("E_FRAME_DEBUGGER_STATE_MISMATCH", "Frame Debugger enable write did not produce an enabled readback.", "Check Frame Debugger availability and retry.");
+            var eventCount = FrameDebuggerReflection.GetEventCount();
+            return new Result
+            {
+                Enabled = enabled,
+                EventCount = eventCount
+            };
+        }
+    }
+}
+#endif