@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/ui/render-preview.cs

@@ -0,0 +1,128 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.render-preview - 将 UIDocument 的真实 visual tree 渲染为 PNG。</summary>
+    public class UiRenderPreviewTool : IUnityCliTool<UiRenderPreviewTool.Request, UiRenderPreviewTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Output { get; set; }
+            public int? Width { get; set; }
+            public int? Height { get; set; }
+            public bool Overwrite { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool DryRun { get; set; }
+            public string OutputPath { get; set; }
+            public long SizeBytes { get; set; }
+            public string Sha256 { get; set; }
+            public List<UiPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        // 描述真实的 UIDocument 离屏渲染及文件覆盖约束。
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "ui.render-preview",
+            Summary = "Render a UIDocument visual tree to a PNG file through a temporary target texture; dry-run supported.",
+            Description = "Render the current visual tree of a UIDocument GameObject to a PNG through a temporary PanelSettings target texture. Defaults to 1280x720. Refuses to overwrite an existing file unless overwrite=true; dry-run returns the planned output without rendering or writing.",
+            Group = "ui",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "file-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample
+                {
+                    Description = "Preview a UIDocument without writing",
+                    Input = new Request { Target = "UIDocument", Output = "Assets/UI/Preview.png", Width = 1280, Height = 720 },
+                    Execution = new ToolExampleExecution { DryRun = true }
+                },
+                new ToolExample
+                {
+                    Description = "Render and overwrite a UIDocument preview",
+                    Input = new Request { Target = "UIDocument", Output = "Assets/UI/Preview.png", Width = 1280, Height = 720, Overwrite = true }
+                }
+            }
+        };
+
+        /// <summary>临时接管 PanelSettings 目标纹理，等待 UI 完成布局后写出 PNG，并始终恢复原状态。</summary>
+        public async ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default)
+        {
+            request = request ?? new Request();
+            var go = UiToolSupport.ResolveGameObjectTarget(request.Target);
+            var document = go.GetComponent<UIDocument>();
+            if (document == null) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_NOT_FOUND", "No UIDocument on target.", "Pass a GameObject containing UIDocument.");
+
+            var width = Mathf.Max(1, request.Width ?? 1280);
+            var height = Mathf.Max(1, request.Height ?? 720);
+            var outputPath = ScreenshotToolSupport.ResolveScreenshotOutputPath(request.Output ?? "Assets/UI/preview.png");
+            if (File.Exists(outputPath) && !request.Overwrite)
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "UI preview output already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
+
+            var effects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.render-preview", Target = request.Target, Path = outputPath } };
+            if (ctx.DryRun)
+            {
+                return new Result { DryRun = true, OutputPath = outputPath, PlannedEffects = effects };
+            }
+
+            ctx.CommitEffect();
+            var originalPanelSettings = document.panelSettings;
+            var originalEnabled = document.enabled;
+            var renderTexture = new RenderTexture(width, height, 24, RenderTextureFormat.ARGB32);
+            var panelSettings = ScriptableObject.CreateInstance<PanelSettings>();
+            Texture2D texture = null;
+            var previousActive = RenderTexture.active;
+            try
+            {
+                renderTexture.Create();
+                panelSettings.targetTexture = renderTexture;
+                panelSettings.scaleMode = PanelScaleMode.ConstantPixelSize;
+                document.panelSettings = panelSettings;
+                document.enabled = true;
+                await ctx.Wait.NextFrame(2, ct);
+                ct.ThrowIfCancellationRequested();
+
+                RenderTexture.active = renderTexture;
+                texture = new Texture2D(width, height, TextureFormat.RGBA32, false);
+                texture.ReadPixels(new Rect(0, 0, width, height), 0, 0, false);
+                texture.Apply(false, false);
+                var bytes = texture.EncodeToPNG();
+                ScreenshotToolSupport.WriteScreenshotBytes(outputPath, bytes);
+                var artifact = ScreenshotToolSupport.VerifyScreenshotArtifact(outputPath, "png");
+                return new Result
+                {
+                    DryRun = false,
+                    OutputPath = outputPath,
+                    SizeBytes = artifact.SizeBytes,
+                    Sha256 = artifact.Sha256,
+                    PlannedEffects = effects
+                };
+            }
+            finally
+            {
+                RenderTexture.active = previousActive;
+                document.panelSettings = originalPanelSettings;
+                document.enabled = originalEnabled;
+                if (texture != null) Object.DestroyImmediate(texture);
+                renderTexture.Release();
+                Object.DestroyImmediate(renderTexture);
+                Object.DestroyImmediate(panelSettings);
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/text/create.cs

@@ -0,0 +1,45 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+using UiButton = UnityEngine.UI.Button;
+using UiCanvasScaler = UnityEngine.UI.CanvasScaler;
+using UiGraphicRaycaster = UnityEngine.UI.GraphicRaycaster;
+using UiImage = UnityEngine.UI.Image;
+using UiText = UnityEngine.UI.Text;
+
+namespace UnityCli
+{
+    /// <summary>ui.text.create — 创建 uGUI Text 元素。</summary>
+    public class UiTextCreateTool : IUnityCliTool<UiTextCreateTool.Request, UiTextCreateTool.Result>
+    {
+        public sealed class Request { public string Name { get; set; } public string Parent { get; set; } public string Text { get; set; } public int? FontSize { get; set; } public string Color { get; set; } public float? Width { get; set; } public float? Height { get; set; } public float? X { get; set; } public float? Y { get; set; } }
+        public sealed class Result { public UiElementRef Element { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.text.create", Summary = "Create a uGUI Text element under a Canvas/RectTransform parent.", Description = "Create a Text element with LegacyRuntime font, configurable text/fontSize/color and RectTransform.", Group = "ui",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create Text", Input = new Request { Parent = "Canvas", Text = "Hello" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var parent = UiToolSupport.ResolveUiParent(r.Parent);
+            if (parent == null) throw new UnityCliBridge.BridgeCommandException("E_UI_PARENT_NOT_FOUND", "UI parent Canvas or RectTransform not found: " + r.Parent, "Create a Canvas first.");
+            var name = string.IsNullOrEmpty(r.Name) ? "Text" : r.Name;
+            var requestedColor = string.IsNullOrEmpty(r.Color) ? Color.black : GraphicsToolSupport.ParseColor(r.Color);
+            UiToolSupport.ValidateUguiRequest(r.FontSize, r.Width, r.Height, r.X, r.Y);
+            ctx.CommitEffect();
+            var go = new GameObject(name, typeof(RectTransform));
+            go.transform.SetParent(parent.transform, false);
+            var text = go.AddComponent<UiText>();
+            text.text = string.IsNullOrEmpty(r.Text) ? name : r.Text;
+            text.font = Resources.GetBuiltinResource<Font>("LegacyRuntime.ttf");
+            text.fontSize = r.FontSize ?? 24;
+            text.color = requestedColor;
+            UiRectHelper.ApplyRect(go.GetComponent<RectTransform>(), r.Width, r.Height, r.X, r.Y);
+            var observedGo = EditorUtility.InstanceIDToObject(go.GetInstanceID()) as GameObject;
+            var observedText = observedGo == null ? null : observedGo.GetComponent<UiText>();
+            var observedRect = observedGo == null ? null : observedGo.GetComponent<RectTransform>();
+            if (observedGo == null || observedGo.transform.parent != parent.transform || observedRect == null || (r.Width.HasValue && !Mathf.Approximately(observedRect.sizeDelta.x, r.Width.Value)) || (r.Height.HasValue && !Mathf.Approximately(observedRect.sizeDelta.y, r.Height.Value)) || (r.X.HasValue && !Mathf.Approximately(observedRect.anchoredPosition.x, r.X.Value)) || (r.Y.HasValue && !Mathf.Approximately(observedRect.anchoredPosition.y, r.Y.Value)) || observedText == null || observedText.text != text.text || observedText.fontSize != text.fontSize || observedText.color != requestedColor)
+                throw new UnityCliBridge.BridgeCommandException("E_UI_TEXT_READBACK_FAILED", "Created Text does not match the requested values.", "Check Unity Console for scene mutation errors.");
+            Selection.activeGameObject = go;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Element = UiToolSupport.BuildUiElementRef(go, "Text"), PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.text.create", Target = GameObjectToolSupport.HierarchyPath(go) } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/update-panel-settings.cs

@@ -0,0 +1,49 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.update-panel-settings — 更新 PanelSettings 资产。</summary>
+    public class UiUpdatePanelSettingsTool : IUnityCliTool<UiUpdatePanelSettingsTool.Request, UiUpdatePanelSettingsTool.Result>
+    {
+        public sealed class Request { public string Path { get; set; } public string ScaleMode { get; set; } public int? ReferenceWidth { get; set; } public int? ReferenceHeight { get; set; } public int? SortingOrder { get; set; } }
+        public sealed class Result { public UiPanelSettingsInfo PanelSettings { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.update-panel-settings", Summary = "Update an existing PanelSettings asset.", Description = "Modify scale mode, reference resolution, or sorting order of an existing PanelSettings. dryRun=true previews.", Group = "ui",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Update PanelSettings", Input = new Request { Path = "Assets/UI/Panel.asset", ReferenceWidth = 1280 } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            UiToolSupport.EnsureEditorNotBusy("ui.update-panel-settings");
+            var path = AssetToolSupport.RequireAssetPath(r.Path);
+            if (!path.EndsWith(".asset", System.StringComparison.OrdinalIgnoreCase)) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_NOT_FOUND", "Pass an Assets/*.asset PanelSettings path.", "Pass a canonical Assets/*.asset path.");
+            if (string.IsNullOrEmpty(r.ScaleMode) && !r.ReferenceWidth.HasValue && !r.ReferenceHeight.HasValue && !r.SortingOrder.HasValue) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_REQUEST_EMPTY", "ui.update-panel-settings requires at least one setting.", "Pass scaleMode, referenceWidth, referenceHeight, or sortingOrder.");
+            var panel = AssetDatabase.LoadAssetAtPath<PanelSettings>(path);
+            if (panel == null) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_NOT_FOUND", "PanelSettings asset not found: " + path, "Create it with ui.create-panel-settings first.");
+            if (!string.IsNullOrEmpty(r.ScaleMode) && !string.Equals(r.ScaleMode, "constantpixelsize", System.StringComparison.OrdinalIgnoreCase) && !string.Equals(r.ScaleMode, "scalewithscreensize", System.StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_SCALE_MODE_INVALID", "ScaleMode must be ConstantPixelSize or ScaleWithScreenSize.", "Pass a documented PanelScaleMode value.");
+            if ((r.ReferenceWidth.HasValue && r.ReferenceWidth.Value <= 0) || (r.ReferenceHeight.HasValue && r.ReferenceHeight.Value <= 0))
+                throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_RANGE_INVALID", "Reference dimensions must be positive.", "Pass positive referenceWidth/referenceHeight values.");
+            var nextScaleMode = string.IsNullOrEmpty(r.ScaleMode) ? panel.scaleMode : (string.Equals(r.ScaleMode, "constantpixelsize", System.StringComparison.OrdinalIgnoreCase) ? PanelScaleMode.ConstantPixelSize : PanelScaleMode.ScaleWithScreenSize);
+            var nextResolution = new Vector2Int(r.ReferenceWidth ?? panel.referenceResolution.x, r.ReferenceHeight ?? panel.referenceResolution.y);
+            var nextSortingOrder = r.SortingOrder ?? panel.sortingOrder;
+            var dryRun = ctx.DryRun;
+            if (dryRun) return new System.Threading.Tasks.ValueTask<Result>(new Result { PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.update-panel-settings", Path = path } } });
+            ctx.CommitEffect();
+            panel.scaleMode = nextScaleMode;
+            panel.referenceResolution = nextResolution;
+            panel.sortingOrder = nextSortingOrder;
+            EditorUtility.SetDirty(panel); AssetDatabase.SaveAssets();
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+            var observed = AssetDatabase.LoadAssetAtPath<PanelSettings>(path);
+            if (observed == null) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_READBACK_FAILED", "Updated PanelSettings could not be reloaded: " + path, "Check Unity Console for asset import errors.");
+            if (observed.scaleMode != nextScaleMode ||
+                observed.referenceResolution != nextResolution ||
+                observed.sortingOrder != nextSortingOrder)
+                throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_READBACK_FAILED", "Updated PanelSettings does not match the requested values: " + path, "Check Unity Console for asset serialization errors.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { PanelSettings = new UiPanelSettingsInfo { Path = AssetDatabase.GetAssetPath(observed), ScaleMode = observed.scaleMode.ToString(), ReferenceWidth = observed.referenceResolution.x, ReferenceHeight = observed.referenceResolution.y, SortingOrder = observed.sortingOrder }, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.update-panel-settings", Path = path } } });
+        }
+    }
+}
+#endif