@alpsckr/unitycli 0.4.0

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

@@ -0,0 +1,116 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.rigidbody — 添加/配置/校验目标 GameObject 的 Rigidbody。
+    /// </summary>
+    public class PhysicsRigidbodyTool : IUnityCliTool<PhysicsRigidbodyTool.Request, PhysicsRigidbodyTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public float? Mass { get; set; }
+            public float? Drag { get; set; }
+            public float? AngularDrag { get; set; }
+            public bool? UseGravity { get; set; }
+            public bool? IsKinematic { get; set; }
+            public bool Validate { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool HasRigidbody { get; set; }
+            public RigidbodyInfo Rigidbody { get; set; }
+            public Rigidbody2DInfo Rigidbody2D { get; set; }
+            public List<string> NextActions { get; set; }
+            public List<PhysicsPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.rigidbody",
+            Summary = "Add, configure, or validate a Rigidbody on a target GameObject.",
+            Description = "Add a Rigidbody (if missing) and configure mass/drag/angularDrag/useGravity/isKinematic. validate=true reads existing Rigidbody/Rigidbody2D without mutating.",
+            Group = "physics",DestructiveHint = false, SideEffects = new[] { "scene-modify" },
+            Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Validate rigidbody", Input = new Request { Target = "Player", Validate = true } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ValidateRequest(request);
+            var target = GameObjectToolSupport.ResolveUniqueTarget(request.Target, "physics.rigidbody requires --target.");
+            var targetId = target.GetInstanceID();
+            var rigidbody = target.GetComponent<Rigidbody>();
+            if (request.Validate)
+            {
+                var rigidbody2D = target.GetComponent<Rigidbody2D>();
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    HasRigidbody = rigidbody != null,
+                    Rigidbody = rigidbody == null ? null : PhysicsToolSupport.BuildRigidbodyInfo(rigidbody),
+                    Rigidbody2D = rigidbody2D == null ? null : PhysicsToolSupport.BuildRigidbody2DInfo(rigidbody2D),
+                    NextActions = rigidbody != null ? new List<string>() : new List<string> { "No Rigidbody is attached; run physics.rigidbody without validate=true to add and configure one." }
+                });
+            }
+            var hasSetter = request.Mass.HasValue || request.Drag.HasValue || request.AngularDrag.HasValue || request.UseGravity.HasValue || request.IsKinematic.HasValue;
+            if (rigidbody != null && !hasSetter)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    HasRigidbody = true,
+                    Rigidbody = PhysicsToolSupport.BuildRigidbodyInfo(rigidbody),
+                    PlannedEffects = new List<PhysicsPlannedEffect>()
+                });
+            }
+            ctx.CommitEffect();
+            if (rigidbody == null) rigidbody = UnityCliSceneMutation.AddComponent<Rigidbody>(target);
+            if (request.Mass.HasValue) rigidbody.mass = request.Mass.Value;
+            if (request.Drag.HasValue) rigidbody.drag = request.Drag.Value;
+            if (request.AngularDrag.HasValue) rigidbody.angularDrag = request.AngularDrag.Value;
+            if (request.UseGravity.HasValue) rigidbody.useGravity = request.UseGravity.Value;
+            if (request.IsKinematic.HasValue) rigidbody.isKinematic = request.IsKinematic.Value;
+            UnityCliSceneMutation.MarkSceneDirty(target.scene);
+            var observedTarget = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+            var observedRigidbody = observedTarget == null ? null : observedTarget.GetComponent<Rigidbody>();
+            if (observedRigidbody == null ||
+                (request.Mass.HasValue && !Mathf.Approximately(observedRigidbody.mass, request.Mass.Value)) ||
+                (request.Drag.HasValue && !Mathf.Approximately(observedRigidbody.drag, request.Drag.Value)) ||
+                (request.AngularDrag.HasValue && !Mathf.Approximately(observedRigidbody.angularDrag, request.AngularDrag.Value)) ||
+                (request.UseGravity.HasValue && observedRigidbody.useGravity != request.UseGravity.Value) ||
+                (request.IsKinematic.HasValue && observedRigidbody.isKinematic != request.IsKinematic.Value))
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_RIGIDBODY_STATE_MISMATCH", "Rigidbody state did not match the requested values.", "Inspect the Rigidbody component and retry after the Editor is idle.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                HasRigidbody = observedRigidbody != null,
+                Rigidbody = PhysicsToolSupport.BuildRigidbodyInfo(observedRigidbody),
+                PlannedEffects = new List<PhysicsPlannedEffect> { new PhysicsPlannedEffect { Type = "physics.rigidbody", Target = GameObjectToolSupport.HierarchyPath(observedTarget) } }
+            });
+        }
+
+        /// <summary>在 effect barrier 前校验全部数值，避免 Unity setter 截断或拒绝请求。</summary>
+        private static void ValidateRequest(Request request)
+        {
+            RequireFinite(request.Mass, "mass");
+            RequireFinite(request.Drag, "drag");
+            RequireFinite(request.AngularDrag, "angularDrag");
+            if (request.Mass.HasValue && request.Mass.Value <= 0f)
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_RIGIDBODY_INPUT_INVALID", "mass must be greater than zero.", "Pass a finite positive mass.");
+            if ((request.Drag.HasValue && request.Drag.Value < 0f) || (request.AngularDrag.HasValue && request.AngularDrag.Value < 0f))
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_RIGIDBODY_INPUT_INVALID", "drag and angularDrag must be non-negative.", "Pass finite non-negative drag values.");
+        }
+
+        // 可选 float 必须能作为有限 Unity 数值使用。
+        private static void RequireFinite(float? value, string field)
+        {
+            if (value.HasValue && (float.IsNaN(value.Value) || float.IsInfinity(value.Value)))
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_RIGIDBODY_INPUT_INVALID", field + " must be finite.", "Pass a finite numeric value for " + field + ".");
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,116 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public class PhysicsSettingsTool : IUnityCliTool<PhysicsSettingsTool.Request, PhysicsSettingsTool.Result>
+    {
+        public sealed class Request
+        {
+            public Vector3? Gravity { get; set; }
+            public Vector2? Gravity2d { get; set; }
+            public float? DefaultContactOffset { get; set; }
+            public float? BounceThreshold { get; set; }
+            public int? DefaultSolverIterations { get; set; }
+            public int? DefaultSolverVelocityIterations { get; set; }
+            public bool? QueriesHitTriggers { get; set; }
+            public bool? QueriesHitBackfaces { get; set; }
+            public bool? QueriesStartInColliders { get; set; }
+            public bool? AutoSimulation { get; set; }
+            public string SimulationMode2D { get; set; }
+            public string Property { get; set; }
+            public string Value { get; set; }
+        }
+
+        public sealed class Result { public PhysicsSettingsInfo Physics { get; set; } public List<PhysicsPlannedEffect> PlannedEffects { get; set; } }
+        private sealed class SettingPlan
+        {
+            public readonly string Property; public readonly string Value; public readonly Action Apply; public readonly Func<bool> ReadbackMatches;
+            public SettingPlan(string property, string value, Action apply, Func<bool> readbackMatches) { Property = property; Value = value; Apply = apply; ReadbackMatches = readbackMatches; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.settings", Summary = "Read and update Physics and Physics2D global settings, including manual simulation mode.",
+            Description = "Read and update Physics and Physics2D global settings. Pass individual fields to update; omit all to read current values. simulationMode2D accepts FixedUpdate, Update, or Script so physics.simulation prerequisites can be configured through the public Tool. Supports a generic property/value pair for gravityY, defaultContactOffset, queriesHitTriggers.",
+            Group = "physics",DestructiveHint = true, SideEffects = new[] { "settings-write" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Read physics settings", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var plans = new List<SettingPlan>();
+            AddTypedPlans(request, plans);
+            AddGenericPlan(request, plans);
+            var immutablePlans = plans.AsReadOnly();
+            if (immutablePlans.Count > 0)
+            {
+                ctx.CommitEffect();
+                foreach (var plan in immutablePlans) plan.Apply();
+                foreach (var plan in immutablePlans)
+                    if (!plan.ReadbackMatches())
+                        throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTINGS_STATE_MISMATCH", "Physics setting did not match after readback: " + plan.Property, "Inspect Project Settings > Physics and retry after the Editor is idle.");
+            }
+            var effects = new List<PhysicsPlannedEffect>();
+            foreach (var plan in immutablePlans) effects.Add(new PhysicsPlannedEffect { Type = "physics.settings", Property = plan.Property, Value = plan.Value });
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Physics = PhysicsToolSupport.BuildPhysicsSettings(), PlannedEffects = effects });
+        }
+
+        // 先将所有 typed 输入校验为不可变计划，确保任何写入前已完成完整校验。
+        private static void AddTypedPlans(Request request, List<SettingPlan> plans)
+        {
+            if (request.Gravity.HasValue) { var value = request.Gravity.Value; ValidateFinite(value, "gravity"); plans.Add(new SettingPlan("gravity", JsonVec(value), () => Physics.gravity = value, () => Physics.gravity == value)); }
+            if (request.Gravity2d.HasValue) { var value = request.Gravity2d.Value; ValidateFinite(value, "gravity2d"); plans.Add(new SettingPlan("gravity2d", JsonVec(value), () => Physics2D.gravity = value, () => Physics2D.gravity == value)); }
+            if (request.DefaultContactOffset.HasValue) { var value = request.DefaultContactOffset.Value; ValidateFinite(value, "defaultContactOffset"); ValidatePositive(value, "defaultContactOffset"); plans.Add(new SettingPlan("defaultContactOffset", Number(value), () => Physics.defaultContactOffset = value, () => Mathf.Approximately(Physics.defaultContactOffset, value))); }
+            if (request.BounceThreshold.HasValue) { var value = request.BounceThreshold.Value; ValidateFinite(value, "bounceThreshold"); ValidateNonNegative(value, "bounceThreshold"); plans.Add(new SettingPlan("bounceThreshold", Number(value), () => Physics.bounceThreshold = value, () => Mathf.Approximately(Physics.bounceThreshold, value))); }
+            if (request.DefaultSolverIterations.HasValue) { var value = request.DefaultSolverIterations.Value; ValidatePositive(value, "defaultSolverIterations"); plans.Add(new SettingPlan("defaultSolverIterations", Number(value), () => Physics.defaultSolverIterations = value, () => Physics.defaultSolverIterations == value)); }
+            if (request.DefaultSolverVelocityIterations.HasValue) { var value = request.DefaultSolverVelocityIterations.Value; ValidatePositive(value, "defaultSolverVelocityIterations"); plans.Add(new SettingPlan("defaultSolverVelocityIterations", Number(value), () => Physics.defaultSolverVelocityIterations = value, () => Physics.defaultSolverVelocityIterations == value)); }
+            if (request.QueriesHitTriggers.HasValue) { var value = request.QueriesHitTriggers.Value; plans.Add(new SettingPlan("queriesHitTriggers", value.ToString().ToLowerInvariant(), () => Physics.queriesHitTriggers = value, () => Physics.queriesHitTriggers == value)); }
+            if (request.QueriesHitBackfaces.HasValue) { var value = request.QueriesHitBackfaces.Value; plans.Add(new SettingPlan("queriesHitBackfaces", value.ToString().ToLowerInvariant(), () => Physics.queriesHitBackfaces = value, () => Physics.queriesHitBackfaces == value)); }
+            if (request.QueriesStartInColliders.HasValue) { var value = request.QueriesStartInColliders.Value; plans.Add(new SettingPlan("queriesStartInColliders", value.ToString().ToLowerInvariant(), () => Physics2D.queriesStartInColliders = value, () => Physics2D.queriesStartInColliders == value)); }
+            if (request.AutoSimulation.HasValue) { var value = request.AutoSimulation.Value; plans.Add(new SettingPlan("autoSimulation", value.ToString().ToLowerInvariant(), () => PhysicsToolSupport.SetAutoSimulation3D(value), () => PhysicsToolSupport.IsAutoSimulation3D() == value)); }
+            if (!string.IsNullOrEmpty(request.SimulationMode2D))
+            {
+                var value = ParseSimulationMode2D(request.SimulationMode2D);
+                plans.Add(new SettingPlan("simulationMode2D", value.ToString(), () => Physics2D.simulationMode = value, () => Physics2D.simulationMode == value));
+            }
+        }
+
+        // property/value 只接受当前公开的设置，并在写入前转换为对应的强类型值。
+        private static void AddGenericPlan(Request request, List<SettingPlan> plans)
+        {
+            if (string.IsNullOrEmpty(request.Property) && string.IsNullOrEmpty(request.Value)) return;
+            if (string.IsNullOrEmpty(request.Property) || string.IsNullOrEmpty(request.Value)) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTING_VALUE_INVALID", "property and value must be supplied together.", "Pass both property and value, or use a typed setting field.");
+            if (request.Property == "gravityY") { var value = ParseFiniteFloat(request.Value, request.Property); plans.Add(new SettingPlan(request.Property, Number(value), () => Physics.gravity = new Vector3(Physics.gravity.x, value, Physics.gravity.z), () => Mathf.Approximately(Physics.gravity.y, value))); return; }
+            if (request.Property == "defaultContactOffset") { var value = ParseFiniteFloat(request.Value, request.Property); ValidatePositive(value, request.Property); plans.Add(new SettingPlan(request.Property, Number(value), () => Physics.defaultContactOffset = value, () => Mathf.Approximately(Physics.defaultContactOffset, value))); return; }
+            if (request.Property == "queriesHitTriggers") { bool value; if (!bool.TryParse(request.Value, out value)) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTING_VALUE_INVALID", "queriesHitTriggers value must be true or false.", "Pass true or false."); plans.Add(new SettingPlan(request.Property, value.ToString().ToLowerInvariant(), () => Physics.queriesHitTriggers = value, () => Physics.queriesHitTriggers == value)); return; }
+            throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTING_UNSUPPORTED", "Unsupported physics setting: " + request.Property, "Use gravityY, defaultContactOffset, queriesHitTriggers, or a typed setting field.");
+        }
+
+        private static float ParseFiniteFloat(string text, string name) { float value; if (!float.TryParse(text, NumberStyles.Float, CultureInfo.InvariantCulture, out value)) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTING_VALUE_INVALID", name + " must be a float.", "Pass a finite numeric value."); ValidateFinite(value, name); return value; }
+
+        // 只接受 Unity 2022.3 公开的 SimulationMode2D 成员，避免未定义数值进入全局设置。
+        private static SimulationMode2D ParseSimulationMode2D(string text)
+        {
+            SimulationMode2D value;
+            if (!Enum.TryParse(text, true, out value) || !Enum.IsDefined(typeof(SimulationMode2D), value))
+                throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTING_VALUE_INVALID", "simulationMode2D must be FixedUpdate, Update, or Script.", "Pass one named SimulationMode2D value.");
+            return value;
+        }
+
+        private static void ValidateFinite(float value, string name) { if (float.IsNaN(value) || float.IsInfinity(value)) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTING_VALUE_INVALID", name + " must be finite.", "Pass a finite numeric value."); }
+        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(Vector2 value, string name) { ValidateFinite(value.x, name + ".x"); ValidateFinite(value.y, name + ".y"); }
+        private static void ValidatePositive(int value, string name) { if (value <= 0) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTING_VALUE_INVALID", name + " must be greater than zero.", "Pass a value greater than zero."); }
+        private static void ValidatePositive(float value, string name) { if (value <= 0f) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTING_VALUE_INVALID", name + " must be greater than zero.", "Pass a value greater than zero."); }
+        private static void ValidateNonNegative(float value, string name) { if (value < 0f) throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_SETTING_VALUE_INVALID", name + " must be non-negative.", "Pass zero or a positive value."); }
+        private static string Number(float value) => value.ToString(CultureInfo.InvariantCulture);
+        private static string Number(int value) => value.ToString(CultureInfo.InvariantCulture);
+        private static string JsonVec(Vector3 value) => value.x + "," + value.y + "," + value.z;
+        private static string JsonVec(Vector2 value) => value.x + "," + value.y;
+    }
+}
+#endif

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

@@ -0,0 +1,127 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.shapecast — 球体/盒子/胶囊体投射查询(3D/2D)。
+    /// </summary>
+    public class PhysicsShapecastTool : IUnityCliTool<PhysicsShapecastTool.Request, PhysicsShapecastTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Shape { get; set; } = "sphere";
+            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 float Radius { get; set; } = 0.5f;
+            public float HalfExtentX { get; set; } = 0.5f;
+            public float HalfExtentY { get; set; } = 0.5f;
+            public float HalfExtentZ { get; set; } = 0.5f;
+            public float Height { get; set; } = 1f;
+            public int CapsuleDirection { get; set; } = 1;
+            public float Angle { get; set; }
+            public float SizeX { get; set; }
+            public float SizeY { get; set; }
+            public float? Point1X { get; set; }
+            public float Point1Y { get; set; }
+            public float Point1Z { get; set; }
+            public float Point2X { get; set; }
+            public float Point2Y { get; set; }
+            public float Point2Z { get; set; }
+            public int? LayerMask { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public RaycastQuery Query { get; set; }
+            public long HitCount { get; set; }
+            public List<RaycastHitInfo> Hits { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.shapecast",
+            Summary = "Cast a sphere, box, or capsule shape and return all hits in 3D or 2D.",
+            Description = "Shape cast: sphere (default), box, or capsule. mode=3d (default) or 2d. 2D supports circle (default), box, and capsule.",
+            Group = "physics",DestructiveHint = false,
+            Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Sphere cast forward", Input = new Request { Shape = "sphere", DirectionZ = 1f } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var shape = request.Shape ?? "sphere";
+            var mode = PhysicsToolSupport.NormalizeMode(request.Mode);
+            var distance = Math.Max(0f, request.Distance);
+            var layerMask = request.LayerMask ?? Physics.DefaultRaycastLayers;
+            var origin = new Vector3(request.OriginX, request.OriginY, request.OriginZ);
+            var direction = PhysicsToolSupport.NormalizeVector3(new Vector3(request.DirectionX, request.DirectionY, request.DirectionZ));
+            var radius = request.Radius;
+            var halfExtents = new Vector3(request.HalfExtentX, request.HalfExtentY, request.HalfExtentZ);
+
+            if (mode == "2d")
+            {
+                var origin2d = new Vector2(origin.x, origin.y);
+                var direction2d = PhysicsToolSupport.NormalizeVector2(new Vector2(direction.x, direction.y));
+                RaycastHit2D[] hits2d;
+                if (shape == "box")
+                {
+                    var size = new Vector2(request.SizeX > 0 ? request.SizeX : halfExtents.x * 2f, request.SizeY > 0 ? request.SizeY : halfExtents.y * 2f);
+                    hits2d = Physics2D.BoxCastAll(origin2d, size, request.Angle, direction2d, distance, layerMask);
+                }
+                else if (shape == "capsule")
+                {
+                    var size = new Vector2(request.SizeX > 0 ? request.SizeX : radius * 2f, request.SizeY > 0 ? request.SizeY : request.Height);
+                    hits2d = Physics2D.CapsuleCastAll(origin2d, size, PhysicsToolSupport.ParseCapsuleDirection2D(null, request.CapsuleDirection), request.Angle, direction2d, distance, layerMask);
+                }
+                else
+                {
+                    hits2d = Physics2D.CircleCastAll(origin2d, radius, direction2d, distance, layerMask);
+                }
+                var hitList = new List<RaycastHitInfo>();
+                foreach (var h in hits2d) hitList.Add(PhysicsToolSupport.BuildRaycast2DHit(h));
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { Query = PhysicsToolSupport.BuildRaycast2DQuery(origin2d, direction2d, distance, layerMask), HitCount = hits2d.Length, Hits = hitList });
+            }
+            RaycastHit[] hits;
+            if (shape == "box")
+            {
+                hits = Physics.BoxCastAll(origin, halfExtents, direction, Quaternion.identity, distance, layerMask);
+            }
+            else if (shape == "capsule")
+            {
+                var capDir = request.CapsuleDirection;
+                Vector3 point1, point2;
+                if (request.Point1X.HasValue)
+                {
+                    point1 = new Vector3(request.Point1X.Value, request.Point1Y, request.Point1Z);
+                    point2 = new Vector3(request.Point2X, request.Point2Y, request.Point2Z);
+                }
+                else
+                {
+                    var halfH = Math.Max(0, request.Height / 2f - radius);
+                    var offset = capDir == 0 ? new Vector3(halfH, 0, 0) : capDir == 2 ? new Vector3(0, 0, halfH) : new Vector3(0, halfH, 0);
+                    point1 = origin + offset;
+                    point2 = origin - offset;
+                }
+                hits = Physics.CapsuleCastAll(point1, point2, radius, direction, distance, layerMask);
+            }
+            else
+            {
+                hits = Physics.SphereCastAll(origin, radius, direction, distance, layerMask);
+            }
+            var list = new List<RaycastHitInfo>();
+            foreach (var h in hits) list.Add(PhysicsToolSupport.BuildRaycast3DHit(h));
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Query = PhysicsToolSupport.BuildRaycast3DQuery(origin, direction, distance, layerMask), HitCount = hits.Length, Hits = list });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,89 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.simulation — 步进 Physics/Physics2D 模拟。
+    /// </summary>
+    public class PhysicsSimulationTool : IUnityCliTool<PhysicsSimulationTool.Request, PhysicsSimulationTool.Result>
+    {
+        public sealed class Request
+        {
+            public int Steps { get; set; } = 1;
+            public float DeltaTime { get; set; }
+            public bool Simulate { get; set; }
+            [UnityCliRequired] public UnityCliCompletionProbe CompletionProbe { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public SimulationInfo Simulation { get; set; }
+            public PhysicsSettingsInfo Physics { get; set; }
+            public UnityCliCompletionProbeReadback Completion { get; set; }
+            public List<PhysicsPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.simulation",
+            Summary = "Step manual Physics and Physics2D simulation and prove one declared body state.",
+            Description = "simulate=true advances manual 3D and 2D physics synchronously. completionProbe is mandatory and must prove a target resource before/after state through an eligible read Tool; API return values are not completion proof. deltaTime defaults to Time.fixedDeltaTime.",
+            Group = "physics",DestructiveHint = false, SideEffects = new[] { "scene-modify" },
+            Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample
+                {
+                    Description = "Simulate one manual step for PhysicsProbe starting at y=1.",
+                    Input = new Request
+                    {
+                        Steps = 1, Simulate = true, DeltaTime = 0.02f,
+                        CompletionProbe = new UnityCliCompletionProbe
+                        {
+                            ReadTool = "scene.gameobject", Input = new Dictionary<string, object> { { "target", "PhysicsProbe" } },
+                            Assertions = new List<UnityCliCompletionAssertion>
+                            {
+                                new UnityCliCompletionAssertion { Path = "/gameObject/transform/position/y", Operator = "approx", Before = 1.0, After = 0.996076, Tolerance = 0.001 }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (request == null) request = new Request();
+            if (request.Steps < 1) throw new UnityCliBridge.BridgeCommandException("E_SCHEMA_INVALID", "physics.simulation steps must be at least 1.", "Pass steps >= 1.");
+            var deltaTime = request.DeltaTime == 0 ? Time.fixedDeltaTime : request.DeltaTime;
+            if (float.IsNaN(deltaTime) || float.IsInfinity(deltaTime) || deltaTime <= 0)
+                throw new UnityCliBridge.BridgeCommandException("E_SCHEMA_INVALID", "physics.simulation deltaTime must be finite and positive.", "Pass a positive finite deltaTime or omit it.");
+            var effects = new List<PhysicsPlannedEffect>();
+            UnityCliCompletionProbeReadback completion = null;
+            if (request.Simulate)
+            {
+                if (PhysicsToolSupport.IsAutoSimulation3D() || Physics2D.simulationMode != SimulationMode2D.Script)
+                    throw new UnityCliBridge.BridgeCommandException("E_PHYSICS_MANUAL_SIMULATION_REQUIRED", "Manual simulation requires Physics.autoSimulation=false and Physics2D.simulationMode=Script.", "Configure manual simulation before invoking physics.simulation.");
+                completion = ctx.RunCompletionProbe(request.CompletionProbe, () =>
+                {
+                    for (var i = 0; i < request.Steps; i++)
+                    {
+                        Physics.Simulate(deltaTime);
+                        Physics2D.Simulate(deltaTime);
+                    }
+                });
+                effects.Add(new PhysicsPlannedEffect { Type = "physics.simulation", Property = "steps", Value = request.Steps.ToString() });
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Simulation = new SimulationInfo { Simulate = request.Simulate, Steps = request.Steps, DeltaTime = deltaTime, FixedDeltaTime = Time.fixedDeltaTime, AutoSimulation = PhysicsToolSupport.IsAutoSimulation3D() },
+                Physics = PhysicsToolSupport.BuildPhysicsSettings(), Completion = completion,
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,67 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// physics.validate — 校验目标 GameObject 的 Rigidbody/Collider 配置合理性。
+    /// </summary>
+    public class PhysicsValidateTool : IUnityCliTool<PhysicsValidateTool.Request, PhysicsValidateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Path { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool Valid { get; set; }
+            public List<string> Issues { get; set; }
+            public bool HasRigidbody { get; set; }
+            public bool HasRigidbody2D { get; set; }
+            public long ColliderCount { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "physics.validate",
+            Summary = "Validate Rigidbody and Collider configuration on a target GameObject.",
+            Description = "Check a GameObject's physics setup for common issues: Rigidbody without Collider, mixed 2D/3D bodies, kinematic body with only trigger colliders.",
+            Group = "physics",DestructiveHint = false,
+            Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Validate Player", Input = new Request { Target = "Player" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var target = request.Target ?? request.Path;
+            var go = string.IsNullOrEmpty(target) ? null : UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(target);
+            if (go == null)
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "physics.validate requires a target GameObject.", "Pass --target <path>.");
+            var rb = go.GetComponent<Rigidbody>();
+            var rb2d = go.GetComponent<Rigidbody2D>();
+            var colliders = go.GetComponents<Collider>();
+            var colliders2d = go.GetComponents<Collider2D>();
+            var issues = new List<string>();
+            if (rb != null && colliders.Length == 0 && colliders2d.Length == 0)
+                issues.Add("Rigidbody without any Collider: physics body will not collide.");
+            if (rb != null && rb2d != null)
+                issues.Add("Both Rigidbody and Rigidbody2D present: ambiguous physics domain.");
+            if (rb != null && rb.isKinematic && colliders.Length > 0)
+            {
+                var anyNonTrigger = false;
+                foreach (var c in colliders) if (!c.isTrigger) { anyNonTrigger = true; break; }
+                if (!anyNonTrigger) issues.Add("Kinematic Rigidbody with only trigger colliders: no solid collision.");
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Valid = issues.Count == 0, Issues = issues,
+                HasRigidbody = rb != null, HasRigidbody2D = rb2d != null, ColliderCount = colliders.Length + colliders2d.Length
+            });
+        }
+    }
+}
+#endif