@alpsckr/unitycli 0.4.3 → 0.4.5

package/unitypkg/Editor/Tools/scene/gameobject-support.cs

@@ -5,11 +5,25 @@ using System.Globalization;
 using System.Reflection;
 using UnityEditor;
 using UnityEngine;
+using UnityEngine.SceneManagement;
 
 namespace UnityCli
 {
     public static partial class UnityCliBridge
     {
+        private sealed class SceneTransformFrame
+        {
+            internal Transform Parent;
+            internal int NextChildIndex;
+        }
+
+        /// <summary>统一在 Unity getter 调用前计费。</summary>
+        private static T ConsumeSceneGetter<T>(UnityCliRequestBudget budget, Func<T> getter)
+        {
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            return getter();
+        }
+
         // 按 id、path、target 顺序解析场景对象；只读层级，不修改 Selection。
         private static GameObject ResolveSceneContextGameObject(string target, int? id, string path)
         {
@@ -32,6 +46,82 @@ namespace UnityCli
             return gameObject;
         }
 
+        /// <summary>只读 Tool 使用的预算化解析；exact path 与名称遍历均在每个 Unity getter 前计费。</summary>
+        private static GameObject ResolveSceneContextGameObject(string target, int? id, string path, UnityCliRequestBudget budget)
+        {
+            if (budget == null) throw new ArgumentNullException("budget");
+            if (id.HasValue)
+            {
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var byId = EditorUtility.InstanceIDToObject(id.Value) as GameObject;
+                if (byId != null) return byId;
+            }
+            else if (!string.IsNullOrEmpty(path))
+            {
+                var byPath = ObjectRefResolver.FindGameObjectByExactPath(path, budget);
+                if (byPath != null) return byPath;
+            }
+            else if (!string.IsNullOrEmpty(target))
+            {
+                var byTarget = target.IndexOf('/') >= 0 ? ObjectRefResolver.FindGameObjectByExactPath(target, budget) : FindUniqueSceneObjectByName(target, budget);
+                if (byTarget != null) return byTarget;
+            }
+            throw new BridgeCommandException("E_TARGET_NOT_FOUND", "GameObject context target not found.", "Pass input target, path, or id. Use scene.hierarchy to discover reusable scene object references.");
+        }
+
+        /// <summary>用 `(parent,nextChildIndex)` 深度优先遍历；任何 child 读取前先扣预算。</summary>
+        private static GameObject FindUniqueSceneObjectByName(string name, UnityCliRequestBudget budget)
+        {
+            GameObject match = null;
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var sceneCount = SceneManager.sceneCount;
+            for (var sceneIndex = 0; sceneIndex < sceneCount; sceneIndex++)
+            {
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var scene = SceneManager.GetSceneAt(sceneIndex);
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                if (!scene.isLoaded) continue;
+                foreach (var root in ObjectRefResolver.BoundedSceneRoots(scene, budget))
+                {
+                    if (!budget.TryConsumeNode() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    if (string.Equals(root.name, name, StringComparison.Ordinal))
+                    {
+                        if (match != null) throw new BridgeCommandException("E_TARGET_AMBIGUOUS", "Multiple GameObjects matched context target: " + name, "Pass a hierarchy path or instance id for disambiguation.");
+                        match = root;
+                    }
+                    if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    var stack = new Stack<SceneTransformFrame>();
+                    stack.Push(new SceneTransformFrame { Parent = root.transform, NextChildIndex = 0 });
+                    while (stack.Count > 0)
+                    {
+                        var frame = stack.Peek();
+                        if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                        var childCount = frame.Parent.childCount;
+                        if (frame.NextChildIndex >= childCount) { stack.Pop(); continue; }
+                        if (!budget.TryConsumeScannedRecord() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                        var child = frame.Parent.GetChild(frame.NextChildIndex++);
+                        if (!budget.TryConsumeNode() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                        if (string.Equals(child.name, name, StringComparison.Ordinal))
+                        {
+                            if (match != null) throw new BridgeCommandException("E_TARGET_AMBIGUOUS", "Multiple GameObjects matched context target: " + name, "Pass a hierarchy path or instance id for disambiguation.");
+                            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                            match = child.gameObject;
+                        }
+                        stack.Push(new SceneTransformFrame { Parent = child, NextChildIndex = 0 });
+                    }
+                }
+            }
+            return match;
+        }
+
+        /// <summary>按组件类型解析单个组件；类型查找与 Unity getter 均使用同一请求预算。</summary>
+        private static Component ResolveSceneContextComponent(GameObject gameObject, string componentName, UnityCliRequestBudget budget)
+        {
+            var type = GameObjectToolSupport.ResolveComponentType(componentName, budget);
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            return gameObject.GetComponent(type);
+        }
+
         /// <summary>构造同 session 内稳定的场景资源 claim；GlobalObjectId 不可用时绑定 scene handle 与 instance id。</summary>
         private static UnityCliProofResourceClaim SceneProofResource(GameObject gameObject, Component component = null)
         {
@@ -56,17 +146,21 @@ namespace UnityCli
         }
 
         // 读取单个组件的公开属性预览；getter 失败时跳过该属性。
-        private static Dictionary<string, object> SceneContextComponentReadableProperties(Component component)
+        private static Dictionary<string, object> SceneContextComponentReadableProperties(Component component, UnityCliRequestBudget budget)
         {
             var values = new Dictionary<string, object>();
-            foreach (var property in component.GetType().GetProperties(BindingFlags.Instance | BindingFlags.Public))
+            if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            foreach (var property in UnityCliReflectionSnapshot.DeclaredProperties(component.GetType(), budget, ObjectSerializer.AbsoluteMaxMembers))
             {
+                if (!budget.TryConsumeScannedRecord() || !budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
                 if (!property.CanRead || property.GetIndexParameters().Length > 0) continue;
                 try
                 {
+                    if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
                     var value = property.GetValue(component, null);
                     values[property.Name] = value == null ? null : Convert.ToString(value, CultureInfo.InvariantCulture);
                 }
+                catch (UnityCliRequestBudgetExceededException) { throw; }
                 catch
                 {
                     // Unity getter 可能依赖不可用的内部状态，属性级失败不影响其余只读结果。
@@ -76,22 +170,24 @@ namespace UnityCli
         }
 
         // 直接构造组件 DTO，避免读取路径出现序列化往返。
-        private static List<SceneGameObjectComponentsTool.ComponentInfo> SceneContextComponentDetails(GameObject gameObject, bool includeProperties)
+        private static List<SceneGameObjectComponentsTool.ComponentInfo> SceneContextComponentDetails(GameObject gameObject, bool includeProperties, UnityCliRequestBudget budget)
         {
             var items = new List<SceneGameObjectComponentsTool.ComponentInfo>();
-            foreach (var component in gameObject.GetComponents<Component>())
+            foreach (var component in ObjectRefResolver.BoundedComponents(gameObject, budget))
             {
                 if (component == null)
                 {
                     items.Add(new SceneGameObjectComponentsTool.ComponentInfo { Type = "MissingScript", Enabled = false });
                     continue;
                 }
+                if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var componentType = component.GetType();
                 items.Add(new SceneGameObjectComponentsTool.ComponentInfo
                 {
-                    Type = component.GetType().Name,
-                    FullName = component.GetType().FullName,
-                    Enabled = ComponentEnabled(component),
-                    Properties = includeProperties ? SceneContextComponentReadableProperties(component) : null
+                    Type = componentType.Name,
+                    FullName = componentType.FullName,
+                    Enabled = GameObjectToolSupport.ComponentEnabled(component, budget),
+                    Properties = includeProperties ? SceneContextComponentReadableProperties(component, budget) : null
                 });
             }
             return items;

package/unitypkg/Editor/Tools/scene/gameobject.cs

@@ -9,12 +9,14 @@ namespace UnityCli
         /// <summary>scene.gameobject 只读 Tool：只读单个 GameObject 摘要。</summary>
         public sealed class SceneGameObjectTool : IUnityCliTool<SceneGameObjectTool.Request, SceneGameObjectTool.Result>
         {
-            public sealed class Request { public string Target { get; set; } public int Id { get; set; } public string Path { get; set; } public bool IncludeComponents { get; set; } = true; }
+            public sealed class Request { public string Target { get; set; } public int Id { get; set; } public string Path { get; set; } public bool IncludeComponents { get; set; } = true; public UnityCliReadBudgetInput Budget { get; set; } }
             public sealed class Result { public GameObjectInfo GameObject { get; set; } }
             public sealed class GameObjectInfo
             {
                 public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } public bool Active { get; set; } public string Tag { get; set; } public long Layer { get; set; }
-                public TransformInfo Transform { get; set; } public List<ComponentInfo> Components { get; set; } public List<GameObjectRef> Children { get; set; }
+                public TransformInfo Transform { get; set; }
+                [UnityCliItemsRange(0, ObjectRefResolver.AbsoluteMaxBatchItems)] public List<ComponentInfo> Components { get; set; }
+                [UnityCliItemsRange(0, 100000)] public List<GameObjectRef> Children { get; set; }
             }
             public sealed class GameObjectRef { public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } }
             public sealed class TransformInfo { public VectorInfo Position { get; set; } public VectorInfo Rotation { get; set; } public VectorInfo Scale { get; set; } }
@@ -25,8 +27,8 @@ namespace UnityCli
             public ToolDescriptor Describe() => new()
             {
                 Name = "scene.gameobject", Summary = "Read one GameObject summary by id, hierarchy path, or name without modifying the scene.",
-                Description = "Read one GameObject's lightweight scene summary by id, hierarchy path, or name. Use this before go.inspect, component.get, object.get-data, or mutation tools to confirm the stable path/id. Does not modify the scene; set includeComponents=false when only the reusable GameObject reference is needed.",
-                DestructiveHint = false,
+                Description = "Read one GameObject's lightweight scene summary by id, hierarchy path, or name in Edit or Play mode. Use this after scene.hierarchy or go.find discovery and before component.get, object.get-data, or mutation tools to confirm a stable path/id. Does not modify the scene; set includeComponents=false when only the reusable reference is needed.",
+                DestructiveHint = false,
                 Group = "scene", Target = "editor", PlayModeSupport = "supported",
                 Examples = new[] { new ToolExample { Description = "Read the main camera object", Input = new Request { Target = "Main Camera", IncludeComponents = true } }, new ToolExample { Description = "Read only the reusable object reference", Input = new Request { Target = "Main Camera", IncludeComponents = false } } }
             };
@@ -42,33 +44,52 @@ namespace UnityCli
             public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
             {
                 request = request ?? new Request();
-                var gameObject = ResolveSceneContextGameObject(request.Target, request.Id == 0 ? (int?)null : request.Id, request.Path);
-                return new System.Threading.Tasks.ValueTask<Result>(new Result { GameObject = SceneGameObjectInfoFrom(gameObject, request.IncludeComponents) });
+                var budget = ctx.UseReadBudget(request.Budget);
+                var gameObject = ResolveSceneContextGameObject(request.Target, request.Id == 0 ? (int?)null : request.Id, request.Path, budget);
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { GameObject = SceneGameObjectInfoFrom(gameObject, request.IncludeComponents, budget) });
             }
         }
 
         // 构造 GameObject DTO；includeComponents=false 时组件列表保持空集合。
-        private static SceneGameObjectTool.GameObjectInfo SceneGameObjectInfoFrom(GameObject gameObject, bool includeComponents)
+        private static SceneGameObjectTool.GameObjectInfo SceneGameObjectInfoFrom(GameObject gameObject, bool includeComponents, UnityCliRequestBudget budget)
         {
+            if (!budget.TryConsumeGetters(6)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var transform = gameObject.transform;
             var info = new SceneGameObjectTool.GameObjectInfo
             {
-                Id = gameObject.GetInstanceID(), Name = gameObject.name, Path = HierarchyPath(gameObject), Active = gameObject.activeSelf, Tag = gameObject.tag, Layer = gameObject.layer,
-                Transform = new SceneGameObjectTool.TransformInfo
-                {
-                    Position = SceneVectorInfoFrom(gameObject.transform.position), Rotation = SceneVectorInfoFrom(gameObject.transform.eulerAngles), Scale = SceneVectorInfoFrom(gameObject.transform.localScale)
-                },
+                Id = gameObject.GetInstanceID(), Name = gameObject.name, Path = GameObjectToolSupport.HierarchyPath(gameObject, budget), Active = gameObject.activeSelf, Tag = gameObject.tag, Layer = gameObject.layer,
+                Transform = new SceneGameObjectTool.TransformInfo(),
                 Components = new List<SceneGameObjectTool.ComponentInfo>(), Children = new List<SceneGameObjectTool.GameObjectRef>()
             };
+            if (!budget.TryConsumeGetters(3)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            info.Transform.Position = SceneVectorInfoFrom(transform.position);
+            info.Transform.Rotation = SceneVectorInfoFrom(transform.eulerAngles);
+            info.Transform.Scale = SceneVectorInfoFrom(transform.localScale);
             if (includeComponents)
             {
-                foreach (var component in gameObject.GetComponents<Component>())
+                foreach (var component in ObjectRefResolver.BoundedComponents(gameObject, budget))
                 {
-                    info.Components.Add(new SceneGameObjectTool.ComponentInfo { Type = component == null ? "MissingScript" : component.GetType().Name, FullName = component == null ? null : component.GetType().FullName, Enabled = component != null && ComponentEnabled(component) });
+                    if (component == null)
+                    {
+                        info.Components.Add(new SceneGameObjectTool.ComponentInfo { Type = "MissingScript", Enabled = false });
+                        continue;
+                    }
+                    if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    var componentType = component.GetType();
+                    info.Components.Add(new SceneGameObjectTool.ComponentInfo { Type = componentType.Name, FullName = componentType.FullName, Enabled = GameObjectToolSupport.ComponentEnabled(component, budget) });
                 }
             }
-            foreach (Transform child in gameObject.transform)
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var childCount = transform.childCount;
+            if (childCount > budget.RemainingScannedRecords) throw new UnityCliRequestBudgetExceededException("scannedRecords");
+            for (var index = 0; index < childCount; index++)
             {
-                info.Children.Add(new SceneGameObjectTool.GameObjectRef { Id = child.gameObject.GetInstanceID(), Name = child.gameObject.name, Path = HierarchyPath(child.gameObject) });
+                if (!budget.TryConsumeScannedRecord() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var child = transform.GetChild(index);
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var childObject = child.gameObject;
+                if (!budget.TryConsumeGetters(2)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                info.Children.Add(new SceneGameObjectTool.GameObjectRef { Id = childObject.GetInstanceID(), Name = childObject.name, Path = GameObjectToolSupport.HierarchyPath(childObject, budget) });
             }
             return info;
         }