@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/screenshot/ScreenshotToolSupport.cs

@@ -0,0 +1,196 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Security.Cryptography;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// screenshot 域 IUnityCliTool 共享的基础设施 helper:渲染纹理、contact sheet、内联 base64。
+    /// 仅供 screenshot 域自包含工具复用;复用 CameraToolSupport 的路径/格式/捕获 helper。
+    /// </summary>
+    public static class ScreenshotToolSupport
+    {
+        /// <summary>Unity 工程根目录。</summary>
+        public static string ProjectRoot()
+        {
+            return Directory.GetParent(Application.dataPath).FullName;
+        }
+
+        /// <summary>Assets/ 路径转工程内绝对路径。</summary>
+        public static string AssetFullPath(string assetPath)
+        {
+            return Path.Combine(ProjectRoot(), assetPath.Replace('/', Path.DirectorySeparatorChar));
+        }
+
+        /// <summary>解析截图输出绝对路径;相对路径解析到 Unity 工程根目录下。</summary>
+        public static string ResolveScreenshotOutputPath(string rawPath)
+        {
+            if (string.IsNullOrEmpty(rawPath))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_PATH_REQUIRED", "Screenshot requires a path.", "Pass --output <path> or a positional screenshot path.");
+            }
+            var normalized = rawPath.Replace('\\', Path.DirectorySeparatorChar).Replace('/', Path.DirectorySeparatorChar);
+            return Path.GetFullPath(Path.IsPathRooted(normalized) ? normalized : Path.Combine(ProjectRoot(), normalized));
+        }
+
+        /// <summary>创建截图输出目录(缺失时)。</summary>
+        public static void CreateScreenshotDirectory(string outputPath)
+        {
+            try { Directory.CreateDirectory(Path.GetDirectoryName(outputPath)); }
+            catch (Exception exception) { throw new UnityCliBridge.BridgeCommandException("E_IO_ERROR", "Failed to create screenshot output directory: " + exception.Message); }
+        }
+
+        /// <summary>写入截图后重新读取字节、校验格式并返回稳定 artifact proof。</summary>
+        public static ScreenshotArtifactProof WriteScreenshotBytes(string outputPath, byte[] bytes)
+        {
+            if (bytes == null || bytes.Length == 0)
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_ARTIFACT_EMPTY", "Screenshot encoder produced no image data.", "Check the camera and render settings, then retry the screenshot.");
+            try { File.WriteAllBytes(outputPath, bytes); }
+            catch (Exception exception) { throw new UnityCliBridge.BridgeCommandException("E_IO_ERROR", "Failed to write screenshot output: " + exception.Message); }
+            return VerifyScreenshotArtifact(outputPath, Path.GetExtension(outputPath).TrimStart('.'));
+        }
+
+        /// <summary>artifact proof 必须来自落盘后的 fresh readback，不能只检查 Exists。</summary>
+        public static ScreenshotArtifactProof VerifyScreenshotArtifact(string outputPath, string format)
+        {
+            if (!File.Exists(outputPath))
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_ARTIFACT_MISSING", "Screenshot artifact was not written: " + outputPath, "Check the output path and available disk space, then retry the screenshot.");
+            var bytes = File.ReadAllBytes(outputPath);
+            var normalized = NormalizeFormat(format, outputPath);
+            var valid = normalized == "png"
+                ? bytes.Length >= 8 && bytes[0] == 0x89 && bytes[1] == 0x50 && bytes[2] == 0x4e && bytes[3] == 0x47 && bytes[4] == 0x0d && bytes[5] == 0x0a && bytes[6] == 0x1a && bytes[7] == 0x0a
+                : bytes.Length >= 3 && bytes[0] == 0xff && bytes[1] == 0xd8 && bytes[2] == 0xff;
+            if (!valid)
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_ARTIFACT_INVALID", "Screenshot artifact is empty or does not match its requested format: " + outputPath, "Use a .png or .jpg output path and retry the capture.");
+            using (var sha = SHA256.Create())
+                return new ScreenshotArtifactProof { Path = outputPath, SizeBytes = bytes.LongLength, Sha256 = string.Concat(Array.ConvertAll(sha.ComputeHash(bytes), value => value.ToString("x2"))), Format = normalized };
+        }
+
+        /// <summary>推断图片格式:显式 format > 路径扩展名 > png;仅接受 png/jpg。</summary>
+        public static string NormalizeFormat(string rawFormat, string outputPath)
+        {
+            var fmt = string.IsNullOrEmpty(rawFormat) ? Path.GetExtension(outputPath).TrimStart('.').ToLowerInvariant() : rawFormat.ToLowerInvariant();
+            if (string.IsNullOrEmpty(fmt)) fmt = "png";
+            if (fmt == "jpeg") fmt = "jpg";
+            if (fmt != "png" && fmt != "jpg")
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_FORMAT_UNSUPPORTED", "Screenshot format must be png or jpg.");
+            }
+            return fmt;
+        }
+
+        /// <summary>渲染指定 Camera 到 Texture2D(不写文件),供 orbit/surround 复用。</summary>
+        public static Texture2D RenderScreenshotTexture(Camera camera, int width, int height)
+        {
+            var previousTarget = camera.targetTexture;
+            var previousActive = RenderTexture.active;
+            RenderTexture rt = null;
+            Texture2D texture = null;
+            try
+            {
+                rt = new RenderTexture(width, height, 24, RenderTextureFormat.ARGB32);
+                texture = new Texture2D(width, height, TextureFormat.RGB24, false);
+                camera.targetTexture = rt;
+                camera.Render();
+                RenderTexture.active = rt;
+                texture.ReadPixels(new Rect(0, 0, width, height), 0, 0);
+                texture.Apply();
+                return texture;
+            }
+            finally
+            {
+                RenderTexture.active = previousActive;
+                camera.targetTexture = previousTarget;
+                if (rt != null) { rt.Release(); UnityEngine.Object.DestroyImmediate(rt); }
+            }
+        }
+
+        /// <summary>计算 GameObject 的渲染 Bounds(含所有子 Renderer)。</summary>
+        public static Bounds TargetRenderBounds(GameObject go)
+        {
+            var renderers = go.GetComponentsInChildren<Renderer>();
+            if (renderers.Length == 0) return new Bounds(go.transform.position, Vector3.one);
+            var bounds = renderers[0].bounds;
+            for (var i = 1; i < renderers.Length; i++)
+            {
+                if (renderers[i] != null && renderers[i].gameObject.activeInHierarchy) bounds.Encapsulate(renderers[i].bounds);
+            }
+            return bounds;
+        }
+
+        /// <summary>组合 6 张截图到 3x2 contact sheet。</summary>
+        public static Texture2D ComposeScreenshotContactSheet(List<Texture2D> tiles, int tileWidth, int tileHeight)
+        {
+            var columns = 3;
+            var rows = 2;
+            var sheet = new Texture2D(tileWidth * columns, tileHeight * rows, TextureFormat.RGB24, false);
+            var fill = Enumerable.Repeat(new Color(0.05f, 0.05f, 0.05f, 1f), sheet.width * sheet.height).ToArray();
+            sheet.SetPixels(fill);
+            for (var i = 0; i < tiles.Count; i++)
+            {
+                var column = i % columns;
+                var row = rows - 1 - (i / columns);
+                sheet.SetPixels(column * tileWidth, row * tileHeight, tileWidth, tileHeight, tiles[i].GetPixels());
+            }
+            sheet.Apply();
+            return sheet;
+        }
+
+        // 内联 base64 上限
+        private const int InlineImageMaxBytes = 512 * 1024;
+
+        /// <summary>在图片字节小于上限时附带 inline base64 数据。</summary>
+        public static void MaybeAppendInline(ScreenshotCaptureResult result, byte[] bytes, int width, int height, string mimeType, bool inlineBase64)
+        {
+            if (inlineBase64 && bytes != null && bytes.Length <= InlineImageMaxBytes)
+            {
+                result.ImageBase64 = Convert.ToBase64String(bytes);
+                result.ImageWidth = width;
+                result.ImageHeight = height;
+                result.ImageMimeType = mimeType;
+            }
+        }
+    }
+
+    /// <summary>screenshot 域截图捕获结果 DTO。</summary>
+    public class ScreenshotCaptureResult
+    {
+        public string ScreenshotPath { get; set; }
+        public string ArtifactPath { get; set; }
+        public string Source { get; set; }
+        public string ImageBase64 { get; set; }
+        public long? ImageWidth { get; set; }
+        public long? ImageHeight { get; set; }
+        public string ImageMimeType { get; set; }
+        public long SizeBytes { get; set; }
+        public string Sha256 { get; set; }
+    }
+
+    /// <summary>screenshot 域 artifact 条目 DTO(orbit/surround 多图输出)。</summary>
+    public sealed class ScreenshotArtifactEntry
+    {
+        public string Source { get; set; }
+        public string Path { get; set; }
+        public string Camera { get; set; }
+        public long Width { get; set; }
+        public long Height { get; set; }
+        public string Format { get; set; }
+        public long SizeBytes { get; set; }
+        public string Sha256 { get; set; }
+    }
+
+    public sealed class ScreenshotArtifactProof
+    {
+        public string Path { get; set; }
+        public long SizeBytes { get; set; }
+        public string Sha256 { get; set; }
+        public string Format { get; set; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/screenshot/editor-element.cs

@@ -0,0 +1,87 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>捕获一个attached Unity Editor UI Toolkit element为bounded PNG artifact。</summary>
+    public sealed class ScreenshotEditorElementTool : IUnityCliTool<EditorElementCaptureRequest, EditorElementCaptureResult>
+    {
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "screenshot.editor-element",
+            Summary = "Capture one bounded Unity Editor UI Toolkit element as a verified PNG artifact.",
+            Description = "Unity 6000.7+ only. Selects an attached EditorWindow by exact type name or title, then resolves a UI Toolkit selector with up to 16 type/#id/.class descendant or child segments. The scan is capped at 10000 elements. Capture dimensions default to 2048x2048 maximum and cannot exceed 4096x4096; PNG bytes default to 8 MiB maximum and cannot exceed 32 MiB. The artifact is written only to the request artifact directory; inline or arbitrary output paths are not accepted.",
+            Group = "screenshot",
+            DestructiveHint = false,
+            SupportsDryRun = true,
+            SideEffects = new[] { "editor-ui-render", "artifact-write" },
+            Permissions = new[] { "artifact-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 120000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Capture the Scene view root element.", Input = new EditorElementCaptureRequest { Window = "SceneView", Selector = "*", MaxWidth = 2048, MaxHeight = 2048 } },
+                new ToolExample { Description = "Preview an Inspector selector without rendering an artifact.", Input = new EditorElementCaptureRequest { Window = "InspectorWindow", Selector = ".unity-inspector-element", MaxBytes = 8388608 }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        /// <summary>window、element、dimensions与byte ceiling均在唯一capture effect前冻结。</summary>
+        public System.Threading.Tasks.ValueTask<EditorElementCaptureResult> ExecuteAsync(EditorElementCaptureRequest request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ct.ThrowIfCancellationRequested();
+            var plan = EditorElementCaptureToolSupport.Prepare(request);
+            if (ctx.DryRun) return new System.Threading.Tasks.ValueTask<EditorElementCaptureResult>(EditorElementCaptureToolSupport.Preview(plan));
+            ctx.CommitEffect();
+            return new System.Threading.Tasks.ValueTask<EditorElementCaptureResult>(EditorElementCaptureToolSupport.Capture(plan, ctx));
+        }
+    }
+
+    public sealed class EditorElementCaptureRequest
+    {
+        [UnityCliRequired]
+        public string Window { get; set; }
+        [UnityCliRequired]
+        public string Selector { get; set; }
+        public long? MaxWidth { get; set; }
+        public long? MaxHeight { get; set; }
+        public long? MaxBytes { get; set; }
+    }
+
+    public sealed class EditorElementWindowIdentity
+    {
+        public string Type { get; set; }
+        public string Title { get; set; }
+        public long InstanceId { get; set; }
+    }
+
+    public sealed class EditorElementIdentity
+    {
+        public string Selector { get; set; }
+        public string Type { get; set; }
+        public string Name { get; set; }
+        public List<string> Classes { get; set; }
+    }
+
+    public sealed class EditorElementCapturePlannedEffect
+    {
+        public string Type { get; set; }
+        public long WindowInstanceId { get; set; }
+        public long Width { get; set; }
+        public long Height { get; set; }
+        public long MaxBytes { get; set; }
+    }
+
+    public sealed class EditorElementCaptureResult
+    {
+        public bool Available { get; set; }
+        public bool DryRun { get; set; }
+        public EditorElementIdentity Element { get; set; }
+        public long Width { get; set; }
+        public long Height { get; set; }
+        public ScreenshotArtifactProof Artifact { get; set; }
+        public List<EditorElementCapturePlannedEffect> PlannedEffects { get; set; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/screenshot/game-view.cs

@@ -0,0 +1,116 @@
+#if UNITY_EDITOR
+using System;
+using System.IO;
+using UnityEngine;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// screenshot.game-view — 模拟 Game View 渲染所有相机到文件。
+    /// </summary>
+    public class ScreenshotGameViewTool : IUnityCliTool<ScreenshotGameViewTool.Request, ScreenshotGameViewTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Path { get; set; }
+            public int? Width { get; set; }
+            public int? Height { get; set; }
+            public bool Overwrite { get; set; }
+            public bool InlineBase64 { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string ScreenshotPath { get; set; }
+            public string ArtifactPath { get; set; }
+            public string Format { get; set; }
+            public long Quality { get; set; }
+            public string Source { get; set; }
+            public string Target { get; set; }
+            public string ImageBase64 { get; set; }
+            public long? ImageWidth { get; set; }
+            public long? ImageHeight { get; set; }
+            public string ImageMimeType { get; set; }
+            public long SizeBytes { get; set; }
+            public string Sha256 { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "screenshot.game-view",
+            Summary = "Capture a Game View screenshot by rendering all active cameras to a PNG/JPG file.",
+            Description = "Capture a Game View screenshot by rendering all active cameras to a temporary RenderTexture and saving to a PNG/JPG file. Renders camera content only and does not include screen-space UI; use screenshot.screen for the final composited frame. Defaults to 1280x720.",
+            Group = "screenshot",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Capture game view", Input = new Request { Path = "Assets/Shots/game.png" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var outputPath = ScreenshotToolSupport.ResolveScreenshotOutputPath(request.Path);
+            if (File.Exists(outputPath) && !request.Overwrite)
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
+            ctx.CommitEffect();
+            ScreenshotToolSupport.CreateScreenshotDirectory(outputPath);
+            var width = Math.Max(1, request.Width ?? 1280);
+            var height = Math.Max(1, request.Height ?? 720);
+            var format = outputPath.EndsWith(".jpg", StringComparison.OrdinalIgnoreCase) ? "jpg" : "png";
+
+            var rt = new RenderTexture(width, height, 24);
+            var texture = new Texture2D(width, height, TextureFormat.RGB24, false);
+            byte[] bytes;
+            var previousActive = RenderTexture.active;
+            try
+            {
+                RenderTexture.active = rt;
+                var cameras = Camera.allCamerasCount > 0 ? Camera.allCameras : new Camera[0];
+                foreach (var cam in cameras)
+                {
+                    if (!cam.gameObject.activeInHierarchy) continue;
+                    var prevTarget = cam.targetTexture;
+                    try { cam.targetTexture = rt; cam.Render(); }
+                    finally { cam.targetTexture = prevTarget; }
+                }
+                texture.ReadPixels(new Rect(0, 0, width, height), 0, 0);
+                texture.Apply();
+                bytes = format == "jpg" ? texture.EncodeToJPG(95) : texture.EncodeToPNG();
+                ScreenshotToolSupport.WriteScreenshotBytes(outputPath, bytes);
+            }
+            finally
+            {
+                RenderTexture.active = previousActive;
+                UnityEngine.Object.DestroyImmediate(texture);
+                rt.Release();
+                UnityEngine.Object.DestroyImmediate(rt);
+            }
+
+            var artifact = ScreenshotToolSupport.VerifyScreenshotArtifact(outputPath, format);
+            var result = new Result
+            {
+                ScreenshotPath = outputPath, ArtifactPath = outputPath, Format = format,
+                Quality = 95, Source = "game-view", Target = "Camera.main/allCameras",
+                SizeBytes = artifact.SizeBytes, Sha256 = artifact.Sha256
+            };
+            MaybeAppendInline(result, bytes, width, height, format == "jpg" ? "image/jpeg" : "image/png", request.InlineBase64);
+            return new System.Threading.Tasks.ValueTask<Result>(result);
+        }
+
+        private static void MaybeAppendInline(Result result, byte[] bytes, int width, int height, string mimeType, bool inlineBase64)
+        {
+            if (inlineBase64 && bytes != null && bytes.Length <= 512 * 1024)
+            {
+                result.ImageBase64 = Convert.ToBase64String(bytes);
+                result.ImageWidth = width;
+                result.ImageHeight = height;
+                result.ImageMimeType = mimeType;
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/screenshot/isolated-object.cs

@@ -0,0 +1,93 @@
+#if UNITY_EDITOR
+using System;
+using System.IO;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// screenshot.isolated-object — 在临时相机中隔离渲染单个对象。
+    /// </summary>
+    public class ScreenshotIsolatedObjectTool : IUnityCliTool<ScreenshotIsolatedObjectTool.Request, ScreenshotIsolatedObjectTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            [UnityCliRequired] public string Path { get; set; }
+            public int? Width { get; set; }
+            public int? Height { get; set; }
+            public bool Orthographic { get; set; } = true;
+            public float? Size { get; set; }
+            public bool Overwrite { get; set; }
+            public bool InlineBase64 { get; set; }
+        }
+
+        public sealed class Result : ScreenshotCaptureResult { }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "screenshot.isolated-object",
+            Summary = "Render a single GameObject in isolation with a temporary camera to a PNG/JPG file.",
+            Description = "Render a single GameObject in isolation using a temporary camera with a solid background. Resolves the target by hierarchy path/name. Editor-only (creates a temporary Camera).",
+            Group = "screenshot",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Isolate an object", Input = new Request { Target = "Player", Path = "Assets/Shots/player.png" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(request.Target);
+            if (go == null)
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "screenshot.isolated-object requires a target GameObject.", "Pass --target <path>.");
+            var outputPath = ScreenshotToolSupport.ResolveScreenshotOutputPath(request.Path);
+            if (File.Exists(outputPath) && !request.Overwrite)
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Output exists: " + outputPath);
+            ctx.CommitEffect();
+            ScreenshotToolSupport.CreateScreenshotDirectory(outputPath);
+            var width = Math.Max(1, request.Width ?? 512);
+            var height = Math.Max(1, request.Height ?? 512);
+            var format = outputPath.EndsWith(".jpg", StringComparison.OrdinalIgnoreCase) ? "jpg" : "png";
+
+            var tempGo = new GameObject("__unitycli_isolated_cam__");
+            var cam = tempGo.AddComponent<Camera>();
+            cam.clearFlags = CameraClearFlags.SolidColor;
+            cam.backgroundColor = new Color(0.2f, 0.2f, 0.2f, 1f);
+            cam.orthographic = request.Orthographic;
+            cam.orthographicSize = request.Size ?? 2f;
+            var bounds = go.GetComponent<Renderer>() != null ? go.GetComponent<Renderer>().bounds : new Bounds(go.transform.position, Vector3.one);
+            tempGo.transform.position = bounds.center + new Vector3(0, 0, -5);
+            tempGo.transform.LookAt(bounds.center);
+
+            byte[] bytes;
+            try
+            {
+                var texture = ScreenshotToolSupport.RenderScreenshotTexture(cam, width, height);
+                try
+                {
+                    bytes = format == "jpg" ? texture.EncodeToJPG(95) : texture.EncodeToPNG();
+                    ScreenshotToolSupport.WriteScreenshotBytes(outputPath, bytes);
+                }
+                finally { UnityEngine.Object.DestroyImmediate(texture); }
+            }
+            finally
+            {
+                UnityEngine.Object.DestroyImmediate(tempGo);
+            }
+
+            var artifact = ScreenshotToolSupport.VerifyScreenshotArtifact(outputPath, format);
+            var result = new Result
+            {
+                ScreenshotPath = outputPath, ArtifactPath = outputPath, Source = "isolated-object",
+                SizeBytes = artifact.SizeBytes, Sha256 = artifact.Sha256
+            };
+            ScreenshotToolSupport.MaybeAppendInline(result, bytes, width, height, format == "jpg" ? "image/jpeg" : "image/png", request.InlineBase64);
+            return new System.Threading.Tasks.ValueTask<Result>(result);
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/screenshot/orbit.cs

@@ -0,0 +1,103 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// screenshot.orbit — 从多个角度环绕截图同一对象。
+    /// </summary>
+    public class ScreenshotOrbitTool : IUnityCliTool<ScreenshotOrbitTool.Request, ScreenshotOrbitTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            public string OutputDir { get; set; } = "Assets/Screenshots";
+            public int? Count { get; set; }
+            public float? Radius { get; set; }
+            public int? Width { get; set; }
+            public int? Height { get; set; }
+            public bool Overwrite { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public List<ScreenshotArtifactEntry> Artifacts { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "screenshot.orbit",
+            Summary = "Capture N orbital screenshots around a GameObject at evenly spaced angles.",
+            Description = "Capture N orbital screenshots (default 8, max 36) around a target GameObject at evenly spaced angles. Saves individual PNGs to an output directory. Editor-only.",
+            Group = "screenshot",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Orbit a target", Input = new Request { Target = "Player", Count = 8 } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(request.Target);
+            if (go == null)
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "screenshot.orbit requires a target GameObject.", "Pass --target <path>.");
+            var outputDir = request.OutputDir ?? "Assets/Screenshots";
+            var angleCount = Math.Max(2, Math.Min(request.Count ?? 8, 36));
+            var radius = request.Radius ?? 5f;
+            var width = Math.Max(1, request.Width ?? 512);
+            var height = Math.Max(1, request.Height ?? 512);
+            var center = go.transform.position;
+            var artifacts = new List<ScreenshotArtifactEntry>();
+            for (var i = 0; i < angleCount; i++)
+            {
+                var candidate = Path.Combine(ScreenshotToolSupport.AssetFullPath(outputDir), "orbit_" + i.ToString("00", CultureInfo.InvariantCulture) + ".png");
+                if (File.Exists(candidate) && !request.Overwrite)
+                    throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + candidate, "Pass overwrite=true or choose another outputDir.");
+            }
+
+            ctx.CommitEffect();
+            var cam = Camera.main;
+            var tempCreated = false;
+            if (cam == null)
+            {
+                var tempGo = new GameObject("__unitycli_orbit_cam__");
+                cam = tempGo.AddComponent<Camera>();
+                tempCreated = true;
+            }
+            var previousPosition = cam.transform.position;
+            var previousRotation = cam.transform.rotation;
+            try
+            {
+                for (var i = 0; i < angleCount; i++)
+                {
+                    var angle = (360f / angleCount) * i;
+                    var rad = angle * Mathf.Deg2Rad;
+                    cam.transform.position = center + new Vector3(Mathf.Cos(rad) * radius, 0, Mathf.Sin(rad) * radius);
+                    cam.transform.LookAt(center);
+                    var path = Path.Combine(ScreenshotToolSupport.AssetFullPath(outputDir), "orbit_" + i.ToString("00", CultureInfo.InvariantCulture) + ".png");
+                    ScreenshotToolSupport.CreateScreenshotDirectory(path);
+                    var texture = ScreenshotToolSupport.RenderScreenshotTexture(cam, width, height);
+                    ScreenshotArtifactProof proof;
+                    try { proof = ScreenshotToolSupport.WriteScreenshotBytes(path, texture.EncodeToPNG()); }
+                    finally { UnityEngine.Object.DestroyImmediate(texture); }
+                    artifacts.Add(new ScreenshotArtifactEntry { Source = "orbit", Path = path, Camera = "orbit:" + angle.ToString("F0", CultureInfo.InvariantCulture), Width = width, Height = height, Format = "png", SizeBytes = proof.SizeBytes, Sha256 = proof.Sha256 });
+                }
+            }
+            finally
+            {
+                if (tempCreated) UnityEngine.Object.DestroyImmediate(cam.gameObject);
+                else { cam.transform.position = previousPosition; cam.transform.rotation = previousRotation; }
+            }
+
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Artifacts = artifacts });
+        }
+    }
+}
+#endif