@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/physics/force.cs

@@ -0,0 +1,127 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.force — 对目标 Rigidbody 施加力/扭矩/爆炸力。
+    /// </summary>
+    public class PhysicsForceTool : IUnityCliTool<PhysicsForceTool.Request, PhysicsForceTool.Result>
+    {
+        private enum ForceApplicationType { Normal, Explosion }
+
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public float X { get; set; }
+            public float Y { get; set; }
+            public float Z { get; set; }
+            public string Mode { get; set; }
+            public string ForceType { get; set; }
+            public float? TorqueX { get; set; }
+            public float TorqueY { get; set; }
+            public float TorqueZ { get; set; }
+            public float ExplosionX { get; set; }
+            public float ExplosionY { get; set; }
+            public float ExplosionZ { get; set; }
+            public float ExplosionRadius { get; set; } = 10f;
+            public float ExplosionForce { get; set; } = 500f;
+            public float UpwardsModifier { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public Vector3Data Force { get; set; }
+            public Vector3Data Velocity { get; set; }
+            public Vector3Data Position { get; set; }
+            public List<PhysicsPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.force",
+            Summary = "Apply force, torque, or explosion force to a target Rigidbody.",
+            Description = "Resolve a target GameObject with a Rigidbody, then apply force (x/y/z), torque, or explosion force (forceType=explosion). mode defaults to Force.",
+            Group = "physics",DestructiveHint = false, SideEffects = new[] { "scene-modify" },
+            Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Apply upward force", Input = new Request { Target = "Player", Y = 100f } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var target = GameObjectToolSupport.ResolveUniqueTarget(request.Target, "physics.force requires --target.");
+            var rigidbody = target.GetComponent<Rigidbody>();
+            if (rigidbody == null)
+                throw new UnityCliBridge.BridgeCommandException("E_RIGIDBODY_NOT_FOUND", "Target has no Rigidbody: " + target.name, "Run physics.rigidbody to add/configure a Rigidbody first.");
+            var force = new Vector3(request.X, request.Y, request.Z);
+            var torque = new Vector3(request.TorqueX.GetValueOrDefault(), request.TorqueY, request.TorqueZ);
+            var explosionPosition = new Vector3(request.ExplosionX, request.ExplosionY, request.ExplosionZ);
+            ValidateFinite(force, "force");
+            ValidateFinite(torque, "torque");
+            ValidateFinite(explosionPosition, "explosion position");
+            ValidateFinite(request.ExplosionRadius, "explosionRadius");
+            ValidateFinite(request.ExplosionForce, "explosionForce");
+            ValidateFinite(request.UpwardsModifier, "upwardsModifier");
+            if (request.ExplosionRadius < 0f)
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_FORCE_VALUE_INVALID", "explosionRadius must be non-negative.", "Pass an explosionRadius of zero or greater.");
+            ForceMode mode;
+            if (!Enum.TryParse(request.Mode ?? ForceMode.Force.ToString(), true, out mode) || !Enum.IsDefined(typeof(ForceMode), mode))
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_FORCE_MODE_INVALID", "mode must be a declared ForceMode value.", "Use Force, Acceleration, Impulse, or VelocityChange.");
+            ForceApplicationType forceType;
+            if (!Enum.TryParse(request.ForceType ?? ForceApplicationType.Normal.ToString(), true, out forceType) || !Enum.IsDefined(typeof(ForceApplicationType), forceType))
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_FORCE_TYPE_INVALID", "forceType must be normal or explosion.", "Pass forceType=normal or forceType=explosion.");
+            if (rigidbody.isKinematic)
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_FORCE_KINEMATIC", "Cannot prove force on a kinematic Rigidbody.", "Set isKinematic=false with physics.rigidbody before applying force.");
+            var requestedNonZero = forceType == ForceApplicationType.Explosion
+                ? request.ExplosionForce != 0f || (request.TorqueX.HasValue && torque.sqrMagnitude > 0f)
+                : force.sqrMagnitude > 0f || (request.TorqueX.HasValue && torque.sqrMagnitude > 0f);
+            if (!requestedNonZero)
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_FORCE_VALUE_INVALID", "physics.force requires a non-zero force, explosion force, or torque.", "Pass at least one non-zero force component.");
+            var targetId = target.GetInstanceID();
+            var rigidbodyId = rigidbody.GetInstanceID();
+            ctx.CommitEffect();
+            // AddForce 的速度积分发生在后续 physics step；先强制 sleep，再以同步 wake 状态证明 API 已接受非零请求。
+            rigidbody.Sleep();
+            if (!rigidbody.IsSleeping())
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_FORCE_STATE_UNPROVABLE", "Rigidbody did not enter the proof sleep state before applying force.", "Inspect the target Rigidbody and retry after the Editor is idle.");
+            if (forceType == ForceApplicationType.Explosion)
+                rigidbody.AddExplosionForce(request.ExplosionForce, explosionPosition, request.ExplosionRadius, request.UpwardsModifier, mode);
+            else rigidbody.AddForce(force, mode);
+            if (request.TorqueX.HasValue) rigidbody.AddTorque(torque, mode);
+            UnityCliSceneMutation.MarkSceneDirty(target.scene);
+            var observedTarget = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+            Rigidbody observedRigidbody = null;
+            if (observedTarget != null)
+                foreach (var candidate in observedTarget.GetComponents<Rigidbody>())
+                    if (candidate != null && candidate.GetInstanceID() == rigidbodyId) { observedRigidbody = candidate; break; }
+            if (observedRigidbody == null)
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_FORCE_STATE_UNPROVABLE", "Rigidbody could not be freshly resolved after applying force.", "Inspect the target Rigidbody and retry after the Editor is idle.");
+            var observedVelocity = observedRigidbody.velocity;
+            var observedPosition = observedRigidbody.position;
+            if (observedRigidbody.IsSleeping())
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_FORCE_STATE_UNPROVABLE", "The non-zero force request did not wake the freshly resolved Rigidbody.", "Inspect the target Rigidbody before submitting a new force request.");
+            target = observedTarget;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Force = new Vector3Data(force), Velocity = new Vector3Data(observedVelocity), Position = new Vector3Data(observedPosition),
+                PlannedEffects = new List<PhysicsPlannedEffect> { new PhysicsPlannedEffect { Type = "physics.force", Target = GameObjectToolSupport.HierarchyPath(target) } }
+            });
+        }
+
+        private static void ValidateFinite(Vector3 value, string name)
+        {
+            ValidateFinite(value.x, name + ".x"); ValidateFinite(value.y, name + ".y"); ValidateFinite(value.z, name + ".z");
+        }
+
+        private static void ValidateFinite(float value, string name)
+        {
+            if (float.IsNaN(value) || float.IsInfinity(value))
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_FORCE_VALUE_INVALID", name + " must be finite.", "Pass a finite float value.");
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/physics/joint/add.cs

@@ -0,0 +1,99 @@
+#if UNITY_EDITOR
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public class PhysicsJointAddTool : IUnityCliTool<PhysicsJointAddTool.Request, PhysicsJointResult>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            public string Type { get; set; }
+            public string ConnectedBody { get; set; }
+        }
+
+        // 返回单一动作的公开 descriptor。
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.joint.add",
+            Summary = "Add or configure a Joint component on a scene GameObject.",
+            Description = "Adds the requested Joint type to target, or configures its existing first component with connectedBody. This changes scene memory only, supports dryRun=true, and is available in Edit and Play mode.",
+            Group = "physics",
+            SupportsDryRun = true,
+            SideEffects = new[] { "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Add fixed joint", Input = new Request { Target = "Player", Type = "FixedJoint" } },
+                new ToolExample { Description = "Connect fixed joint", Input = new Request { Target = "Player", Type = "FixedJoint", ConnectedBody = "Enemy" } }
+            }
+        };
+
+        /// <summary>添加或配置 Joint；添加后重新解析组件，避免 Undo 返回的临时引用失效。</summary>
+        public ValueTask<PhysicsJointResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default)
+        {
+            var resolved = PhysicsJointToolSupport.Resolve(request.Target, request.Type, "physics.joint.add");
+            var target = resolved.Item1;
+            var targetId = target.GetInstanceID();
+            var type = resolved.Item2;
+            var existing = target.GetComponent(type) as Joint;
+            Rigidbody connectedBody = null;
+            var connectedBodyId = 0;
+            if (!string.IsNullOrEmpty(request.ConnectedBody))
+            {
+                var connectedTarget = GameObjectToolSupport.ResolveUniqueTarget(request.ConnectedBody, "Connected body target not found.");
+                connectedBody = connectedTarget.GetComponent<Rigidbody>();
+                if (connectedBody == null)
+                    throw new UnityCliBridge.BridgeCommandException("E_RIGIDBODY_NOT_FOUND", "Connected body target has no Rigidbody: " + connectedTarget.name, "Add a Rigidbody to the connected body before adding this joint.");
+                connectedBodyId = connectedBody.GetInstanceID();
+            }
+            if (ctx.DryRun)
+            {
+                return new ValueTask<PhysicsJointResult>(new PhysicsJointResult
+                {
+                    DryRun = true,
+                    Exists = existing != null,
+                    PlannedEffects = PhysicsJointToolSupport.Effects("physics.joint.add", existing == null ? "add" : "configure", type.Name)
+                });
+            }
+
+            ct.ThrowIfCancellationRequested();
+            ctx.CommitEffect();
+            if (existing == null) UnityCliSceneMutation.AddComponent(target, type);
+            var joint = target.GetComponent(type) as Joint;
+            if (joint == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_PHYSICS_JOINT_ADD_FAILED",
+                    "Unity did not attach the requested Joint component: " + type.Name,
+                    "Confirm the requested joint type is compatible with the target GameObject and retry.");
+            }
+
+            if (connectedBody != null)
+            {
+                joint.connectedBody = connectedBody;
+                if (joint.connectedBody != connectedBody)
+                    throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_JOINT_ADD_STATE_MISMATCH", "Joint connectedBody did not match the requested Rigidbody.", "Inspect the Joint component and retry after the Editor is idle.");
+            }
+            UnityCliSceneMutation.MarkSceneDirty(target.scene);
+            // proof 必须从 instance ID 重解析目标、Joint 及 connectedBody，不能复用写前引用。
+            var observedTarget = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+            var observedJoint = observedTarget == null ? null : observedTarget.GetComponent(type) as Joint;
+            var observedConnectedBody = connectedBodyId == 0 ? null : EditorUtility.InstanceIDToObject(connectedBodyId) as Rigidbody;
+            if (observedJoint == null || (connectedBodyId != 0 && (observedConnectedBody == null || observedJoint.connectedBody != observedConnectedBody)))
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_JOINT_ADD_STATE_MISMATCH", "Requested Joint component state was not present after mutation.", "Inspect the target GameObject and retry.");
+            return new ValueTask<PhysicsJointResult>(new PhysicsJointResult
+            {
+                Exists = true,
+                PlannedEffects = PhysicsJointToolSupport.Effects("physics.joint.add", existing == null ? "add" : "configure", type.Name)
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/physics/joint/remove.cs

@@ -0,0 +1,4 @@
+#if UNITY_EDITOR
+using System.Linq; using UnityEditor; using UnityEngine;
+namespace UnityCli { public class PhysicsJointRemoveTool : IUnityCliTool<PhysicsJointRemoveTool.Request, PhysicsJointResult> { public sealed class Request { [UnityCliRequired] public string Target { get; set; } public string Type { get; set; } public int? ComponentIndex { get; set; } } public ToolDescriptor Describe() => new() { Name = "physics.joint.remove", Summary = "Remove Joint components from a scene GameObject.", Description = "Removes all matching Joint components from target, or one selected by componentIndex. This changes scene memory only, supports dryRun=true, and is available in Edit and Play mode.", Group = "physics",SupportsDryRun = true, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Preview fixed joint removal", Input = new Request { Target = "Player", Type = "FixedJoint", ComponentIndex = 0 }, Execution = new ToolExampleExecution { DryRun = true } }, new ToolExample { Description = "Remove fixed joint", Input = new Request { Target = "Player", Type = "FixedJoint", ComponentIndex = 0 } } } }; public System.Threading.Tasks.ValueTask<PhysicsJointResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { var (target, type) = PhysicsJointToolSupport.Resolve(request.Target, request.Type, "physics.joint.remove"); var joints = target.GetComponents(type).Cast<Joint>().ToArray(); if (joints.Length == 0) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_JOINT_NOT_FOUND", "No matching Joint component found on target: " + type.Name, "Check target and type, or add one with physics.joint.add."); var index = request.ComponentIndex ?? -1; if (index < -1 || index >= joints.Length) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_JOINT_INDEX_INVALID", "componentIndex is outside the matching Joint component range.", "Pass a componentIndex from 0 to " + (joints.Length - 1) + "."); var targetId = target.GetInstanceID(); var requestedJointIds = (index >= 0 ? new[] { joints[index] } : joints).Select(joint => joint.GetInstanceID()).ToArray(); if (!ctx.DryRun) { ctx.CommitEffect(); foreach (var joint in index >= 0 ? new[] { joints[index] } : joints) UnityCliSceneMutation.DestroyObject(joint); UnityCliSceneMutation.MarkSceneDirty(target.scene); var observedTarget = EditorUtility.InstanceIDToObject(targetId) as GameObject; var remainingIds = observedTarget == null ? new int[0] : observedTarget.GetComponents(type).Cast<Joint>().Select(joint => joint.GetInstanceID()).ToArray(); if (observedTarget == null || requestedJointIds.Any(id => remainingIds.Contains(id))) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_JOINT_REMOVE_STATE_MISMATCH", "A requested Joint component still exists after removal.", "Inspect the target Joint components and retry after the Editor is idle."); target = observedTarget; } return new(new PhysicsJointResult { DryRun = ctx.DryRun, Removed = requestedJointIds.Length, PlannedEffects = PhysicsJointToolSupport.Effects("physics.joint.remove", "remove", type.Name) }); } } }
+#endif

package/unitypkg/Editor/Tools/physics/linecast.cs

@@ -0,0 +1,59 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.linecast — 检测两点间是否有碰撞。
+    /// </summary>
+    public class PhysicsLinecastTool : IUnityCliTool<PhysicsLinecastTool.Request, PhysicsLinecastTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Mode { get; set; }
+            public float StartX { get; set; }
+            public float StartY { get; set; }
+            public float StartZ { get; set; }
+            public float EndX { get; set; }
+            public float EndY { get; set; }
+            public float EndZ { get; set; }
+            public int? LayerMask { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool Hit { get; set; }
+            public RaycastHitInfo HitInfo { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.linecast",
+            Summary = "Check if a 3D or 2D line segment between two points is blocked by a collider.",
+            Description = "Cast a line from start to end and report whether any collider blocks the path. mode=3d (default) or 2d.",
+            Group = "physics",DestructiveHint = false,
+            Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Linecast between two points", Input = new Request { StartX = 0, EndX = 10 } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var mode = PhysicsToolSupport.NormalizeMode(request.Mode);
+            var layerMask = request.LayerMask ?? Physics.DefaultRaycastLayers;
+            var start = new Vector3(request.StartX, request.StartY, request.StartZ);
+            var end = new Vector3(request.EndX, request.EndY, request.EndZ);
+            if (mode == "2d")
+            {
+                var hit = Physics2D.Linecast(new Vector2(start.x, start.y), new Vector2(end.x, end.y), layerMask);
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { Hit = hit.collider != null });
+            }
+            RaycastHit hit3d;
+            var found = Physics.Linecast(start, end, out hit3d, layerMask);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Hit = found, HitInfo = found ? PhysicsToolSupport.BuildRaycast3DHit(hit3d) : null });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/physics/material.cs

@@ -0,0 +1,73 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.material — 创建/修改 PhysicMaterial 资产(.physicMaterial/.asset)。
+    /// </summary>
+    public class PhysicsMaterialTool : IUnityCliTool<PhysicsMaterialTool.Request, PhysicsMaterialTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public float? DynamicFriction { get; set; }
+            public float? StaticFriction { get; set; }
+            public float? Bounciness { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public PhysicMaterialInfo Material { get; set; }
+            public List<PhysicsPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.material",
+            Summary = "Create or update a PhysicMaterial asset at an Assets/*.physicMaterial path.",
+            Description = "Create a new PhysicMaterial asset or update an existing one. Path must be under Assets/ and end with .physicMaterial or .asset. Supports dynamicFriction, staticFriction, bounciness.",
+            Group = "physics",DestructiveHint = true, SideEffects = new[] { "asset-write" },
+            Target = "editor", PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Create bouncy material", Input = new Request { Path = "Assets/Physics/Bouncy.physicMaterial", Bounciness = 0.8f } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = SceneToolSupport.NormalizeAssetPath(request.Path);
+            if (string.IsNullOrEmpty(path) || !path.StartsWith("Assets/", System.StringComparison.OrdinalIgnoreCase) || (!path.EndsWith(".physicMaterial", System.StringComparison.OrdinalIgnoreCase) && !path.EndsWith(".asset", System.StringComparison.OrdinalIgnoreCase)))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_MATERIAL_PATH_INVALID", "Physics material path must be under Assets/ and end with .physicMaterial or .asset.", "Pass Assets/Physics/Bouncy.physicMaterial.");
+            }
+            var material = AssetDatabase.LoadAssetAtPath<PhysicMaterial>(path);
+            ctx.CommitEffect();
+            if (material == null)
+            {
+                SceneToolSupport.CreateAssetDirectory(path);
+                material = new PhysicMaterial(Path.GetFileNameWithoutExtension(path));
+                AssetDatabase.CreateAsset(material, path);
+            }
+            if (request.DynamicFriction.HasValue) material.dynamicFriction = request.DynamicFriction.Value;
+            if (request.StaticFriction.HasValue) material.staticFriction = request.StaticFriction.Value;
+            if (request.Bounciness.HasValue) material.bounciness = request.Bounciness.Value;
+            EditorUtility.SetDirty(material);
+            AssetDatabase.SaveAssets();
+            var observedMaterial = AssetDatabase.LoadAssetAtPath<PhysicMaterial>(path);
+            if (observedMaterial == null ||
+                (request.DynamicFriction.HasValue && !Mathf.Approximately(observedMaterial.dynamicFriction, request.DynamicFriction.Value)) ||
+                (request.StaticFriction.HasValue && !Mathf.Approximately(observedMaterial.staticFriction, request.StaticFriction.Value)) ||
+                (request.Bounciness.HasValue && !Mathf.Approximately(observedMaterial.bounciness, request.Bounciness.Value)))
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_MATERIAL_STATE_MISMATCH", "PhysicMaterial asset readback did not match the requested values.", "Inspect the asset and retry after Unity finishes importing.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Material = new PhysicMaterialInfo { Path = path, Name = observedMaterial.name, DynamicFriction = observedMaterial.dynamicFriction, StaticFriction = observedMaterial.staticFriction, Bounciness = observedMaterial.bounciness },
+                PlannedEffects = new List<PhysicsPlannedEffect> { new PhysicsPlannedEffect { Type = "physics.material", Property = "path", Value = path } }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/physics/overlap.cs

@@ -0,0 +1,84 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.overlap — 球体/盒子重叠查询(3D/2D)。
+    /// </summary>
+    public class PhysicsOverlapTool : IUnityCliTool<PhysicsOverlapTool.Request, PhysicsOverlapTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Mode { get; set; }
+            public string Shape { get; set; }
+            public float OriginX { get; set; }
+            public float OriginY { get; set; }
+            public float OriginZ { get; set; }
+            public float Radius { get; set; } = 1f;
+            public float SizeX { get; set; } = 1f;
+            public float SizeY { get; set; } = 1f;
+            public float SizeZ { get; set; } = 1f;
+            public float Angle { get; set; }
+            public int? LayerMask { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public Vector3Data Origin { get; set; }
+            public long HitCount { get; set; }
+            public List<ColliderRef> Hits { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.overlap",
+            Summary = "Find colliders overlapping a sphere or box volume in 3D or 2D.",
+            Description = "Overlap query: sphere (default) or box. mode=3d (default) or 2d. 2D supports circle (default) and box shapes.",
+            Group = "physics",DestructiveHint = false,
+            Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Overlap sphere at origin", Input = new Request { Radius = 5f } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var mode = PhysicsToolSupport.NormalizeMode(request.Mode);
+            var origin = new Vector3(request.OriginX, request.OriginY, request.OriginZ);
+            var layerMask = request.LayerMask ?? Physics.DefaultRaycastLayers;
+            if (mode == "2d")
+            {
+                var origin2d = new Vector2(origin.x, origin.y);
+                Collider2D[] colliders2d;
+                if (string.Equals(request.Shape, "box", StringComparison.OrdinalIgnoreCase))
+                {
+                    var size = new Vector2(request.SizeX, request.SizeY);
+                    colliders2d = Physics2D.OverlapBoxAll(origin2d, size, request.Angle, layerMask);
+                }
+                else
+                {
+                    colliders2d = Physics2D.OverlapCircleAll(origin2d, Math.Max(0.0001f, request.Radius), layerMask);
+                }
+                var hits = new List<ColliderRef>();
+                foreach (var c in colliders2d) hits.Add(PhysicsToolSupport.BuildColliderRef(c.gameObject, c.GetType().Name));
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { Origin = new Vector3Data(new Vector3(origin2d.x, origin2d.y, 0)), HitCount = colliders2d.Length, Hits = hits });
+            }
+            Collider[] colliders;
+            if (string.Equals(request.Shape, "box", StringComparison.OrdinalIgnoreCase))
+            {
+                var halfExtents = new Vector3(request.SizeX, request.SizeY, request.SizeZ) * 0.5f;
+                colliders = Physics.OverlapBox(origin, halfExtents, Quaternion.identity, layerMask);
+            }
+            else
+            {
+                colliders = Physics.OverlapSphere(origin, Math.Max(0.0001f, request.Radius), layerMask);
+            }
+            var hits3d = new List<ColliderRef>();
+            foreach (var c in colliders) hits3d.Add(PhysicsToolSupport.BuildColliderRef(c.gameObject, c.GetType().Name));
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Origin = new Vector3Data(origin), HitCount = colliders.Length, Hits = hits3d });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/physics/raycast-all.cs

@@ -0,0 +1,67 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.raycast-all — 3D/2D 射线查询,返回所有命中。
+    /// </summary>
+    public class PhysicsRaycastAllTool : IUnityCliTool<PhysicsRaycastAllTool.Request, PhysicsRaycastAllTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Mode { get; set; }
+            public float OriginX { get; set; }
+            public float OriginY { get; set; }
+            public float OriginZ { get; set; }
+            public float DirectionX { get; set; }
+            public float DirectionY { get; set; }
+            public float DirectionZ { get; set; } = 1f;
+            public float Distance { get; set; } = 100f;
+            public int? LayerMask { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long HitCount { get; set; }
+            public List<RaycastHitInfo> Hits { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.raycast-all",
+            Summary = "Cast a 3D or 2D ray and return all hits along the path.",
+            Description = "Cast a ray and return all collider hits, sorted by distance (3D). mode=3d (default) or 2d.",
+            Group = "physics",DestructiveHint = false,
+            Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "All hits forward", Input = new Request { OriginY = 1f, DirectionZ = 1f } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var mode = PhysicsToolSupport.NormalizeMode(request.Mode);
+            var distance = Math.Max(0f, request.Distance);
+            var layerMask = request.LayerMask ?? Physics.DefaultRaycastLayers;
+            if (mode == "2d")
+            {
+                var origin = new Vector2(request.OriginX, request.OriginY);
+                var direction = PhysicsToolSupport.NormalizeVector2(new Vector2(request.DirectionX, request.DirectionY));
+                var hits = Physics2D.RaycastAll(origin, direction, distance, layerMask);
+                var hitList = new List<RaycastHitInfo>();
+                foreach (var h in hits) hitList.Add(PhysicsToolSupport.BuildRaycast2DHit(h));
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { HitCount = hits.Length, Hits = hitList });
+            }
+            var origin3d = new Vector3(request.OriginX, request.OriginY, request.OriginZ);
+            var direction3d = PhysicsToolSupport.NormalizeVector3(new Vector3(request.DirectionX, request.DirectionY, request.DirectionZ));
+            var hits3d = Physics.RaycastAll(origin3d, direction3d, distance, layerMask);
+            Array.Sort(hits3d, (a, b) => a.distance.CompareTo(b.distance));
+            var list = new List<RaycastHitInfo>();
+            foreach (var h in hits3d) list.Add(PhysicsToolSupport.BuildRaycast3DHit(h));
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { HitCount = hits3d.Length, Hits = list });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/physics/raycast.cs

@@ -0,0 +1,96 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.raycast — 3D/2D 射线查询,返回首个命中或全部命中。
+    /// </summary>
+    public class PhysicsRaycastTool : IUnityCliTool<PhysicsRaycastTool.Request, PhysicsRaycastTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Mode { get; set; }
+            public float OriginX { get; set; }
+            public float OriginY { get; set; }
+            public float OriginZ { get; set; }
+            public float DirectionX { get; set; }
+            public float DirectionY { get; set; }
+            public float DirectionZ { get; set; } = 1f;
+            public float Distance { get; set; } = 100f;
+            public int? LayerMask { get; set; }
+            public bool All { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public RaycastQuery Query { get; set; }
+            public bool Hit { get; set; }
+            public long HitCount { get; set; }
+            public List<RaycastHitInfo> Hits { get; set; }
+            public List<string> NextActions { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.raycast",
+            Summary = "Cast a 3D or 2D ray and return the first hit, or all hits with all=true.",
+            Description = "Cast a ray from origin along direction up to distance. mode=3d (default) or 2d. all=true returns all hits sorted by distance. layerMask defaults to DefaultRaycastLayers.",
+            Group = "physics",DestructiveHint = false,
+            Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "3D raycast forward", Input = new Request { OriginY = 1f, DirectionZ = 1f } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var mode = PhysicsToolSupport.NormalizeMode(request.Mode);
+            var distance = Math.Max(0f, request.Distance);
+            var layerMask = request.LayerMask ?? Physics.DefaultRaycastLayers;
+            if (mode == "2d")
+            {
+                var origin = new Vector2(request.OriginX, request.OriginY);
+                var direction = PhysicsToolSupport.NormalizeVector2(new Vector2(request.DirectionX, request.DirectionY));
+                if (request.All)
+                {
+                    var hits = Physics2D.RaycastAll(origin, direction, distance, layerMask);
+                    var hitList = new List<RaycastHitInfo>();
+                    foreach (var h in hits) hitList.Add(PhysicsToolSupport.BuildRaycast2DHit(h));
+                    return new System.Threading.Tasks.ValueTask<Result>(new Result { Query = PhysicsToolSupport.BuildRaycast2DQuery(origin, direction, distance, layerMask), HitCount = hits.Length, Hits = hitList });
+                }
+                var hit = Physics2D.Raycast(origin, direction, distance, layerMask);
+                var list = new List<RaycastHitInfo>();
+                if (hit.collider != null) list.Add(PhysicsToolSupport.BuildRaycast2DHit(hit));
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    Query = PhysicsToolSupport.BuildRaycast2DQuery(origin, direction, distance, layerMask),
+                    Hit = hit.collider != null, HitCount = hit.collider != null ? 1 : 0, Hits = list,
+                    NextActions = hit.collider != null ? new List<string>() : new List<string> { "No Physics collider matched the ray); adjust origin, direction, distance or layer mask." }
+                });
+            }
+            var origin3d = new Vector3(request.OriginX, request.OriginY, request.OriginZ);
+            var direction3d = PhysicsToolSupport.NormalizeVector3(new Vector3(request.DirectionX, request.DirectionY, request.DirectionZ));
+            if (request.All)
+            {
+                var hits = Physics.RaycastAll(origin3d, direction3d, distance, layerMask);
+                Array.Sort(hits, (a, b) => a.distance.CompareTo(b.distance));
+                var hitList = new List<RaycastHitInfo>();
+                foreach (var h in hits) hitList.Add(PhysicsToolSupport.BuildRaycast3DHit(h));
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { Query = PhysicsToolSupport.BuildRaycast3DQuery(origin3d, direction3d, distance, layerMask), HitCount = hits.Length, Hits = hitList });
+            }
+            RaycastHit hit3d;
+            var didHit = Physics.Raycast(origin3d, direction3d, out hit3d, distance, layerMask);
+            var list3d = new List<RaycastHitInfo>();
+            if (didHit) list3d.Add(PhysicsToolSupport.BuildRaycast3DHit(hit3d));
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Query = PhysicsToolSupport.BuildRaycast3DQuery(origin3d, direction3d, distance, layerMask),
+                Hit = didHit, HitCount = didHit ? 1 : 0, Hits = list3d,
+                NextActions = didHit ? new List<string>() : new List<string> { "No Physics collider matched the ray); adjust origin, direction, distance or layer mask." }
+            });
+        }
+    }
+}
+#endif