@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/animation/animator/set-parameter.cs

@@ -0,0 +1,71 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animator.set-parameter — 设置 Animator 参数默认值(编辑模式修改 Controller 资产)。</summary>
+    public class AnimatorSetParameterTool : IUnityCliTool<AnimatorSetParameterTool.Request, AnimatorSetParameterTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string ParameterName { get; set; } public string Value { get; set; } }
+        public sealed class Result { public AnimatorParameterRef Parameter { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animator.set-parameter", Summary = "Set an Animator parameter default value by editing the AnimatorController asset.", Description = "In edit mode, modifies the AnimatorController asset parameter defaults. Requires an AnimatorController assigned to the Animator.", Group = "animation",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Set Speed default", Input = new Request { Target = "Player", ParameterName = "Speed", Value = "0.5" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = GameObjectToolSupport.ResolveUniqueTarget(r.Target, "Animator set-parameter requires --target <go>.");
+            var animator = go.GetComponent<Animator>();
+            if (animator == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NOT_FOUND", "Animator component not found on target: " + GameObjectToolSupport.HierarchyPath(go), "Add an Animator component or choose another target.");
+            if (string.IsNullOrEmpty(r.ParameterName)) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_PARAMETER_NAME_REQUIRED", "Animator set-parameter requires --parameter-name <name>.", "Pass the name of an Animator parameter.");
+            var ac = animator.runtimeAnimatorController as AnimatorController;
+            if (ac == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NO_CONTROLLER", "Animator has no AnimatorController assigned: " + GameObjectToolSupport.HierarchyPath(go), "Assign an AnimatorController asset.");
+            var param = AnimationToolSupport.FindAnimatorParameter(animator, r.ParameterName);
+            if (param == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_PARAMETER_NOT_FOUND", "Parameter '" + r.ParameterName + "' not found: " + GameObjectToolSupport.HierarchyPath(go), "Run animator.get-info to list parameters.");
+            var expectedFloat = 0f;
+            var expectedInt = 0;
+            var expectedBool = false;
+            switch (param.type)
+            {
+                case AnimatorControllerParameterType.Float: expectedFloat = GameObjectToolSupport.ParseFloat(r.Value ?? "0", r.ParameterName); break;
+                case AnimatorControllerParameterType.Int: expectedInt = int.Parse(r.Value ?? "0", System.Globalization.CultureInfo.InvariantCulture); break;
+                case AnimatorControllerParameterType.Bool: expectedBool = bool.Parse(r.Value ?? "false"); break;
+            }
+            ctx.CommitEffect();
+            Undo.RecordObject(ac, "Set Animator Parameter Default");
+            var parameters = ac.parameters;
+            for (var i = 0; i < parameters.Length; i++)
+            {
+                if (parameters[i].name == r.ParameterName)
+                {
+                    switch (param.type)
+                    {
+                        case AnimatorControllerParameterType.Float: parameters[i].defaultFloat = expectedFloat; break;
+                        case AnimatorControllerParameterType.Int: parameters[i].defaultInt = expectedInt; break;
+                        case AnimatorControllerParameterType.Bool: parameters[i].defaultBool = expectedBool; break;
+                    }
+                    break;
+                }
+            }
+            ac.parameters = parameters;
+            EditorUtility.SetDirty(ac);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(AssetDatabase.GetAssetPath(ac));
+            AnimatorControllerParameter observedParameter = null;
+            if (observedController != null) foreach (var candidate in observedController.parameters) if (candidate.name == r.ParameterName) { observedParameter = candidate; break; }
+            if (observedParameter == null || !DefaultValueMatches(observedParameter, r.Value)) throw AnimationToolSupport.StateMismatch("E_ANIMATOR_PARAMETER_STATE_MISMATCH", "AnimatorController parameter default");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Parameter = new AnimatorParameterRef { Name = observedParameter.name, Type = observedParameter.type.ToString() }, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animator.set-parameter", Target = GameObjectToolSupport.HierarchyPath(go), Parameter = observedParameter.name } } });
+        }
+
+        private static bool DefaultValueMatches(AnimatorControllerParameter parameter, string value)
+        {
+            switch (parameter.type)
+            {
+                case AnimatorControllerParameterType.Float: return Mathf.Approximately(parameter.defaultFloat, GameObjectToolSupport.ParseFloat(value ?? "0", parameter.name));
+                case AnimatorControllerParameterType.Int: return parameter.defaultInt == int.Parse(value ?? "0", System.Globalization.CultureInfo.InvariantCulture);
+                case AnimatorControllerParameterType.Bool: return parameter.defaultBool == bool.Parse(value ?? "false");
+                default: return true;
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/animator/set-speed.cs

@@ -0,0 +1,33 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animator.set-speed — 设置 Animator.speed。</summary>
+    public class AnimatorSetSpeedTool : IUnityCliTool<AnimatorSetSpeedTool.Request, AnimatorSetSpeedTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public float? Speed { get; set; } }
+        public sealed class Result { public double Speed { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animator.set-speed", Summary = "Set the playback speed of an Animator component.", Description = "Resolve a target with an Animator and set animator.speed. Defaults to 1.0.", Group = "animation",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Set speed to 2x", Input = new Request { Target = "Player", Speed = 2f } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = GameObjectToolSupport.ResolveUniqueTarget(r.Target, "Animator set-speed requires --target <go>.");
+            var animator = go.GetComponent<Animator>();
+            if (animator == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NOT_FOUND", "Animator component not found on target: " + GameObjectToolSupport.HierarchyPath(go), "Add an Animator component or choose another target.");
+            var speed = r.Speed ?? 1f;
+            ctx.CommitEffect();
+            UnityCliSceneMutation.RecordObject(animator, "Set Animator Speed");
+            animator.speed = speed;
+            UnityCliSceneMutation.MarkSceneObjectDirty(animator);
+            var observedTarget = EditorUtility.InstanceIDToObject(go.GetInstanceID()) as GameObject;
+            var observedAnimator = observedTarget == null ? null : observedTarget.GetComponent<Animator>();
+            var observedSpeed = observedAnimator == null ? 0f : observedAnimator.speed;
+            if (observedAnimator == null || !Mathf.Approximately(observedSpeed, speed)) throw AnimationToolSupport.StateMismatch("E_ANIMATOR_SPEED_STATE_MISMATCH", "Animator speed");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Speed = observedSpeed, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animator.set-speed", Target = GameObjectToolSupport.HierarchyPath(go), Value = observedSpeed.ToString(System.Globalization.CultureInfo.InvariantCulture) } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/clip/create.cs

@@ -0,0 +1,48 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animation.clip.create — 创建持久化 AnimationClip 资产。</summary>
+    public class AnimationClipCreateTool : IUnityCliTool<AnimationClipCreateTool.Request, AnimationClipCreateTool.Result>
+    {
+        public sealed class Request { public string Path { get; set; } public bool? Overwrite { get; set; } public float? FrameRate { get; set; } public bool? Legacy { get; set; } public string WrapMode { get; set; } public bool? LoopTime { get; set; } public float? StartTime { get; set; } public float? StopTime { get; set; } public float? Length { get; set; } public int? MaxCurveKeys { get; set; } }
+        public sealed class Result { public bool DryRun { get; set; } public bool WouldOverwrite { get; set; } public AnimationClipInfo Clip { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animation.clip.create", Summary = "Create or overwrite a persistent AnimationClip asset at an Assets/*.anim path.", Description = "Create a new .anim asset with clip-level settings (frameRate, legacy, wrapMode, loopTime, startTime/stopTime/length). overwrite=true to replace existing.", Group = "animation",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create clip", Input = new Request { Path = "Assets/Animations/Created.anim", FrameRate = 30f, LoopTime = true } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireAnimationClipPath(r.Path);
+            var overwrite = r.Overwrite ?? false;
+            var existing = AssetDatabase.LoadAssetAtPath<AnimationClip>(path);
+            var wm = AnimationToolSupport.ValidateClipSettings(r.FrameRate, r.WrapMode, r.StartTime, r.StopTime, r.Length);
+            if (existing != null && !overwrite)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_CLIP_EXISTS", "AnimationClip already exists: " + path, "Pass overwrite:true after inspecting the existing clip, or choose another Assets/*.anim path.");
+            var dryRun = ctx.DryRun;
+            if (dryRun)
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = true, WouldOverwrite = existing != null, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animation.clip.create", Path = path } } });
+            ctx.CommitEffect();
+            SceneToolSupport.CreateAssetDirectory(path);
+            if (existing != null) AssetDatabase.DeleteAsset(path);
+            var clip = new AnimationClip { name = Path.GetFileNameWithoutExtension(path) };
+            if (r.FrameRate.HasValue) clip.frameRate = r.FrameRate.Value;
+            if (r.Legacy.HasValue) clip.legacy = r.Legacy.Value;
+            if (!string.IsNullOrEmpty(r.WrapMode)) clip.wrapMode = wm;
+            var settings = AnimationUtility.GetAnimationClipSettings(clip);
+            if (r.StartTime.HasValue) settings.startTime = r.StartTime.Value;
+            if (r.StopTime.HasValue) settings.stopTime = r.StopTime.Value;
+            else if (r.Length.HasValue) settings.stopTime = settings.startTime + r.Length.Value;
+            if (r.LoopTime.HasValue) settings.loopTime = r.LoopTime.Value;
+            AnimationUtility.SetAnimationClipSettings(clip, settings);
+            AssetDatabase.CreateAsset(clip, path);
+            var observedClip = AnimationToolSupport.ReloadAnimationClipAsset(path);
+            var observedSettings = observedClip == null ? default(AnimationClipSettings) : AnimationUtility.GetAnimationClipSettings(observedClip);
+            if (observedClip == null || observedClip.name != clip.name || (r.FrameRate.HasValue && !Mathf.Approximately(observedClip.frameRate, r.FrameRate.Value)) || (r.Legacy.HasValue && observedClip.legacy != r.Legacy.Value) || (!string.IsNullOrEmpty(r.WrapMode) && observedClip.wrapMode != wm) || (r.LoopTime.HasValue && observedSettings.loopTime != r.LoopTime.Value) || (r.StartTime.HasValue && !Mathf.Approximately(observedSettings.startTime, r.StartTime.Value)) || (r.StopTime.HasValue && !Mathf.Approximately(observedSettings.stopTime, r.StopTime.Value)) || (r.Length.HasValue && !r.StopTime.HasValue && !Mathf.Approximately(observedSettings.stopTime - observedSettings.startTime, r.Length.Value)))
+                throw AnimationToolSupport.StateMismatch("E_ANIMATION_CLIP_CREATE_STATE_MISMATCH", "AnimationClip creation");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = false, Clip = AnimationToolSupport.BuildAnimationClipInfo(path, observedClip, r.MaxCurveKeys ?? 5), PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animation.clip.create", Path = path } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/clip/modify.cs

@@ -0,0 +1,43 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animation.clip.modify — 修改已存在 AnimationClip 的 clip 级设置。</summary>
+    public class AnimationClipModifyTool : IUnityCliTool<AnimationClipModifyTool.Request, AnimationClipModifyTool.Result>
+    {
+        public sealed class Request { public string Path { get; set; } public float? FrameRate { get; set; } public bool? Legacy { get; set; } public string WrapMode { get; set; } public bool? LoopTime { get; set; } public float? StartTime { get; set; } public float? StopTime { get; set; } public float? Length { get; set; } public int? MaxCurveKeys { get; set; } }
+        public sealed class Result { public bool DryRun { get; set; } public AnimationClipInfo Clip { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animation.clip.modify", Summary = "Update clip-level settings on an existing AnimationClip asset.", Description = "Modify frameRate, legacy, wrapMode, loopTime, startTime/stopTime/length on an existing .anim asset. Does not touch curves or events.", Group = "animation",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Set loop time", Input = new Request { Path = "Assets/Animations/Walk.anim", LoopTime = true } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireAnimationClipPath(r.Path);
+            var clip = AnimationToolSupport.LoadAnimationClipAsset(path);
+            var wm = AnimationToolSupport.ValidateClipSettings(r.FrameRate, r.WrapMode, r.StartTime, r.StopTime, r.Length);
+            var dryRun = ctx.DryRun;
+            if (dryRun)
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = true, Clip = AnimationToolSupport.BuildAnimationClipInfo(path, clip, r.MaxCurveKeys ?? 5), PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animation.clip.modify", Path = path } } });
+            ctx.CommitEffect();
+            Undo.RecordObject(clip, "Modify AnimationClip Settings");
+            if (r.FrameRate.HasValue) clip.frameRate = r.FrameRate.Value;
+            if (r.Legacy.HasValue) clip.legacy = r.Legacy.Value;
+            if (!string.IsNullOrEmpty(r.WrapMode)) clip.wrapMode = wm;
+            var settings = AnimationUtility.GetAnimationClipSettings(clip);
+            if (r.StartTime.HasValue) settings.startTime = r.StartTime.Value;
+            if (r.StopTime.HasValue) settings.stopTime = r.StopTime.Value;
+            else if (r.Length.HasValue) settings.stopTime = settings.startTime + r.Length.Value;
+            if (r.LoopTime.HasValue) settings.loopTime = r.LoopTime.Value;
+            AnimationUtility.SetAnimationClipSettings(clip, settings);
+            EditorUtility.SetDirty(clip);
+            var observedClip = AnimationToolSupport.ReloadAnimationClipAsset(path);
+            var observedSettings = observedClip == null ? default(AnimationClipSettings) : AnimationUtility.GetAnimationClipSettings(observedClip);
+            if (observedClip == null || (r.FrameRate.HasValue && !Mathf.Approximately(observedClip.frameRate, r.FrameRate.Value)) || (r.Legacy.HasValue && observedClip.legacy != r.Legacy.Value) || (!string.IsNullOrEmpty(r.WrapMode) && observedClip.wrapMode != wm) || (r.LoopTime.HasValue && observedSettings.loopTime != r.LoopTime.Value) || (r.StartTime.HasValue && !Mathf.Approximately(observedSettings.startTime, r.StartTime.Value)) || (r.StopTime.HasValue && !Mathf.Approximately(observedSettings.stopTime, r.StopTime.Value)) || (r.Length.HasValue && !r.StopTime.HasValue && !Mathf.Approximately(observedSettings.stopTime - observedSettings.startTime, r.Length.Value)))
+                throw AnimationToolSupport.StateMismatch("E_ANIMATION_CLIP_MODIFY_STATE_MISMATCH", "AnimationClip settings");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = false, Clip = AnimationToolSupport.BuildAnimationClipInfo(path, observedClip, r.MaxCurveKeys ?? 5), PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animation.clip.modify", Path = path } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/clip.cs

@@ -0,0 +1,23 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animation.clip — 读取 AnimationClip 资产的设置、绑定曲线和事件。</summary>
+    public class AnimationClipTool : IUnityCliTool<AnimationClipTool.Request, AnimationClipTool.Result>
+    {
+        public sealed class Request { public string Path { get; set; } public int? MaxCurveKeys { get; set; } }
+        public sealed class Result { public AnimationClipInfo Clip { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animation.clip", Summary = "Read an AnimationClip asset's settings, curve bindings, and events.", Description = "Read Assets/*.anim AnimationClip settings, events, and bounded curve summaries. maxCurveKeys limits keys per binding (default 5).", Group = "animation",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read clip", Input = new Request { Path = "Assets/Animations/Idle.anim" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireAnimationClipPath(r.Path);
+            var clip = AnimationToolSupport.LoadAnimationClipAsset(path);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Clip = AnimationToolSupport.BuildAnimationClipInfo(path, clip, r.MaxCurveKeys ?? 5) });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/play.cs

@@ -0,0 +1,41 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animation.play — 播放指定 Animator 状态。</summary>
+    public class AnimationPlayTool : IUnityCliTool<AnimationPlayTool.Request, AnimationPlayTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string State { get; set; } public int? Layer { get; set; } public float? NormalizedTime { get; set; } }
+        public sealed class Result { public AnimatorInfo Animator { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animation.play", Summary = "Play a named Animator state on a target GameObject.", Description = "Resolve a target with an Animator and play the named state on the given layer.", Group = "animation",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Play Walk state", Input = new Request { Target = "Player", State = "Walk" } } } };
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = GameObjectToolSupport.ResolveUniqueTarget(r.Target, "Animation play requires --target <go>.");
+            var animator = go.GetComponent<Animator>();
+            if (animator == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NOT_FOUND", "Animator component not found on target: " + GameObjectToolSupport.HierarchyPath(go), "Add an Animator component or choose another target.");
+            var effectiveLayerCount = AnimationToolSupport.EffectiveAnimatorLayerCount(animator);
+            if (animator.runtimeAnimatorController == null || effectiveLayerCount <= 0)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_NO_CONTROLLER", "Animator has no RuntimeAnimatorController assigned or no effective layers: " + GameObjectToolSupport.HierarchyPath(go), "Assign a RuntimeAnimatorController with at least one layer.");
+            if (string.IsNullOrEmpty(r.State)) throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_STATE_REQUIRED", "Animation play requires --state <name>.", "Pass an Animator state name.");
+            var layer = r.Layer ?? 0;
+            if (layer < 0 || layer >= effectiveLayerCount) throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_LAYER_INVALID", "Animator layer is out of range: " + layer, "Run animation.state to inspect layer count.");
+            var controller = animator.runtimeAnimatorController as AnimatorController;
+            var state = controller == null || layer >= controller.layers.Length ? null : AnimationToolSupport.FindStateInLayer(controller.layers[layer].stateMachine, r.State);
+            if (state == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_STATE_UNOBSERVABLE", "Animation state cannot be resolved to a stable Animator readback: " + r.State, "Pass a root state name from the selected AnimatorController layer.");
+            var expectedHash = Animator.StringToHash(controller.layers[layer].name + "." + state.name);
+            ctx.CommitEffect();
+            animator.Play(r.State, animator.layerCount > 0 ? layer : 0, r.NormalizedTime ?? 0f);
+            animator.Update(0f);
+            var observed = await ctx.Wait.UntilStable(() => animator != null && animator.GetCurrentAnimatorStateInfo(layer).fullPathHash == expectedHash, System.TimeSpan.FromMilliseconds(ctx.TimeoutMs), ct: ct);
+            if (!observed) throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_STATE_TIMEOUT", "Animator did not reach the requested state before timeout: " + r.State, "Check Animator transitions and retry after the requested state is reachable.");
+            UnityCliSceneMutation.MarkSceneObjectDirty(animator);
+            var finalAnimator = AnimationToolSupport.BuildAnimatorInfo(animator, layer);
+            return new Result { Animator = finalAnimator, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animation.play", Target = GameObjectToolSupport.HierarchyPath(go), State = r.State } } };
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/state.cs

@@ -0,0 +1,25 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animation.state — 读取目标 Animator 的当前状态信息。</summary>
+    public class AnimationStateTool : IUnityCliTool<AnimationStateTool.Request, AnimationStateTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public int? Layer { get; set; } }
+        public sealed class Result { public AnimatorInfo Animator { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animation.state", Summary = "Read the current Animator state for a target GameObject.", Description = "Resolve a target with an Animator and return current state info (layer, state hash, normalized time).", Group = "animation",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read animation state", Input = new Request { Target = "Player" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = GameObjectToolSupport.ResolveUniqueTarget(r.Target, "Animation state requires --target <go>.");
+            var animator = go.GetComponent<Animator>();
+            if (animator == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NOT_FOUND", "Animator component not found on target: " + GameObjectToolSupport.HierarchyPath(go), "Add an Animator component or choose another target.");
+            var layer = Mathf.Clamp(r.Layer ?? 0, 0, Mathf.Max(0, AnimationToolSupport.EffectiveAnimatorLayerCount(animator) - 1));
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Animator = AnimationToolSupport.BuildAnimatorInfo(animator, layer) });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/stop.cs

@@ -0,0 +1,45 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animation.stop — 停止/重置目标 Animator。</summary>
+    public class AnimationStopTool : IUnityCliTool<AnimationStopTool.Request, AnimationStopTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } }
+        public sealed class Result { public AnimatorInfo Animator { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animation.stop", Summary = "Stop and rebind an Animator on a target GameObject.", Description = "Call Animator.Rebind() and Update(0) to reset the Animator to its initial state.", Group = "animation",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Stop animation", Input = new Request { Target = "Player" } } } };
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = GameObjectToolSupport.ResolveUniqueTarget(r.Target, "Animation stop requires --target <go>.");
+            var animator = go.GetComponent<Animator>();
+            if (animator == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NOT_FOUND", "Animator component not found on target: " + GameObjectToolSupport.HierarchyPath(go), "Add an Animator component or choose another target.");
+            var controller = animator.runtimeAnimatorController as AnimatorController;
+            if (controller == null || controller.layers.Length == 0 || controller.layers[0].stateMachine.defaultState == null)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_STATE_UNOBSERVABLE", "Animator has no root-layer default state that can prove reset completion.", "Assign an AnimatorController with a root-layer default state.");
+            var defaultState = controller.layers[0].stateMachine.defaultState;
+            var expectedHash = Animator.StringToHash(controller.layers[0].name + "." + defaultState.name);
+            var targetId = go.GetInstanceID();
+            ctx.CommitEffect();
+            animator.Rebind();
+            animator.Update(0f);
+            var observed = await ctx.Wait.UntilStable(() =>
+            {
+                var target = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+                var freshAnimator = target == null ? null : target.GetComponent<Animator>();
+                return freshAnimator != null && freshAnimator.GetCurrentAnimatorStateInfo(0).fullPathHash == expectedHash;
+            }, System.TimeSpan.FromMilliseconds(ctx.TimeoutMs), ct: ct);
+            if (!observed) throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_RESET_TIMEOUT", "Animator did not return to its default state before timeout.", "Inspect the AnimatorController default state and transitions.");
+            var observedTarget = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+            var observedAnimator = observedTarget == null ? null : observedTarget.GetComponent<Animator>();
+            if (observedAnimator == null || observedAnimator.GetCurrentAnimatorStateInfo(0).fullPathHash != expectedHash) throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_RESET_TIMEOUT", "Animator reset proof was not available after completion.", "Inspect the AnimatorController default state and transitions.");
+            UnityCliSceneMutation.MarkSceneObjectDirty(observedAnimator);
+            var finalAnimator = AnimationToolSupport.BuildAnimatorInfo(observedAnimator, 0);
+            return new Result { Animator = finalAnimator, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animation.stop", Target = GameObjectToolSupport.HierarchyPath(observedTarget), State = defaultState.name } } };
+        }
+    }
+}
+#endif