@alpsckr/unitycli 0.4.0

package/extensions/vfx-graph/unitypkg/Editor/Vfx/line-positions.cs

@@ -0,0 +1,100 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// vfx.line-positions - 更新 LineRenderer 顶点集合或单个顶点。
+    /// </summary>
+    public class VfxLinePositionsTool : IUnityCliTool<VfxLinePositionsTool.Request, VfxLinePositionsTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Target { get; set; }
+            public List<Vector3Input> Positions { get; set; }
+            public int? Index { get; set; }
+            public Vector3Input Position { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public VfxLineRendererInfo Line { get; set; }
+            public List<VfxPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.line-positions",
+            Summary = "Replace all LineRenderer positions or patch a single indexed point.",
+            Description = "Update a LineRenderer's position set. Provide positions to replace the full array, or provide index plus position to patch one point in place.",
+            Group = "vfx",
+            DestructiveHint = false,
+            SideEffects = new[] { "line-renderer-edit" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Replace all positions", Input = new Request { Target = "AimLine", Positions = new List<Vector3Input> { new Vector3Input { X = 0, Y = 0, Z = 0 }, new Vector3Input { X = 4, Y = 0, Z = 0 } } } },
+                new ToolExample { Description = "Patch one point", Input = new Request { Target = "AimLine", Index = 1, Position = new Vector3Input { X = 2, Y = 1, Z = 0 } } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.line-positions");
+            var line = VfxToolSupport.ResolveLineRenderer(request.Target);
+            if (line == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_LINE_RENDERER_NOT_FOUND",
+                    "LineRenderer not found: " + request.Target,
+                    "Pass a GameObject name / hierarchy path with a LineRenderer component.");
+            }
+
+            var effects = new List<VfxPlannedEffect>();
+            VfxToolSupport.RequireMutation((request.Positions != null && request.Positions.Count > 0) || (request.Index.HasValue && request.Position != null), "vfx.line-positions");
+            if (request.Positions != null) foreach (var item in request.Positions) { VfxToolSupport.RequireFinite(item.X, "positions.x"); VfxToolSupport.RequireFinite(item.Y, "positions.y"); VfxToolSupport.RequireFinite(item.Z, "positions.z"); }
+            if (request.Position != null) { VfxToolSupport.RequireFinite(request.Position.X, "position.x"); VfxToolSupport.RequireFinite(request.Position.Y, "position.y"); VfxToolSupport.RequireFinite(request.Position.Z, "position.z"); }
+            var positions = request.Positions != null && request.Positions.Count > 0 ? VfxToolSupport.ToUnityVector3Array(request.Positions) : null;
+            var patchPosition = request.Position == null ? Vector3.zero : VfxToolSupport.ToUnityVector3(request.Position);
+            if (request.Index.HasValue && request.Position != null && (request.Index.Value < 0 || request.Index.Value >= (positions == null ? line.positionCount : positions.Length)))
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_INDEX_OUT_OF_RANGE",
+                    "Line position index out of range: " + request.Index.Value.ToString(System.Globalization.CultureInfo.InvariantCulture),
+                    "Use an index between 0 and " + ((positions == null ? line.positionCount : positions.Length) - 1).ToString(System.Globalization.CultureInfo.InvariantCulture) + ".");
+            }
+            var gameObjectId = line.gameObject.GetInstanceID();
+            if (positions != null || (request.Index.HasValue && request.Position != null)) ctx.CommitEffect();
+            line = VfxToolSupport.ResolveObservedComponent<LineRenderer>(gameObjectId, "vfx.line-positions");
+            if (positions != null)
+            {
+                line.positionCount = positions.Length;
+                line.SetPositions(positions);
+                effects.Add(new VfxPlannedEffect { Type = "vfx.line-positions", Target = GameObjectToolSupport.HierarchyPath(line.gameObject), Property = "positions", Value = positions.Length.ToString(System.Globalization.CultureInfo.InvariantCulture) });
+            }
+            if (request.Index.HasValue && request.Position != null)
+            {
+                line.SetPosition(request.Index.Value, patchPosition);
+                effects.Add(new VfxPlannedEffect { Type = "vfx.line-positions", Target = GameObjectToolSupport.HierarchyPath(line.gameObject), Property = "index", Value = request.Index.Value.ToString(System.Globalization.CultureInfo.InvariantCulture) });
+            }
+
+            var observed = VfxToolSupport.ResolveObservedComponent<LineRenderer>(gameObjectId, "vfx.line-positions");
+            if (positions != null) VfxToolSupport.VerifyLineRendererFields(observed, new LineRendererFields { Positions = request.Positions });
+            if (request.Index.HasValue && request.Position != null && observed.GetPosition(request.Index.Value) != patchPosition) throw new UnityCliBridge.BridgeCommandException("E_LINE_VERIFY_FAILED", "LineRenderer indexed position did not retain the requested value.", "Retry after checking the LineRenderer.");
+            UnityCliSceneMutation.MarkSceneObjectDirty(observed);
+            VfxToolSupport.MarkSceneDirty(observed.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Line = VfxToolSupport.BuildLineRendererInfo(observed),
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/parameter.cs

@@ -0,0 +1,216 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// vfx.parameter - 设置 VisualEffect 暴露参数。
+    /// </summary>
+    public class VfxParameterTool : IUnityCliTool<VfxParameterTool.Request, VfxParameterTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Target { get; set; }
+            [UnityCliRequired]
+            public string Name { get; set; }
+            public string Type { get; set; }
+            public double? NumberValue { get; set; }
+            public int? IntValue { get; set; }
+            public bool? BoolValue { get; set; }
+            public string AssetPath { get; set; }
+            public double? X { get; set; }
+            public double? Y { get; set; }
+            public double? Z { get; set; }
+            public double? W { get; set; }
+            public double? R { get; set; }
+            public double? G { get; set; }
+            public double? B { get; set; }
+            public double? A { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string ParameterName { get; set; }
+            public string ParameterType { get; set; }
+            public List<VfxPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.parameter",
+            Summary = "Set an exposed VisualEffect parameter by explicit scalar, vector, color, texture, or mesh input.",
+            Description = "Set an exposed VisualEffect parameter on a target component using an explicit type, then require matching Has*/Get* APIs to verify its typed readback. Use numberValue, intValue, boolValue, assetPath, or the vector/color axis fields that match the requested type. This tool reflects the package API at runtime and does not require compile-time VFX references.",
+            Group = "vfx",
+            DestructiveHint = false,
+            RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new[] { "component-state-edit" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Set float parameter", Input = new Request { Target = "Effects/Emitter", Name = "SpawnRate", Type = "float", NumberValue = 12.5 } },
+                new ToolExample { Description = "Set color parameter", Input = new Request { Target = "Effects/Emitter", Name = "Tint", Type = "color", R = 1, G = 0.5, B = 0.2, A = 1 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.parameter");
+            var visualEffectType = VfxToolSupport.RequireVisualEffectType();
+            var gameObject = GameObjectToolSupport.ResolveUniqueTarget(request.Target, "VFX parameter requires target.");
+            var component = gameObject.GetComponent(visualEffectType);
+            if (component == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_VFX_COMPONENT_NOT_FOUND",
+                    "VisualEffect component not found on target: " + GameObjectToolSupport.HierarchyPath(gameObject),
+                    "Use vfx.effect.add or choose a target with VisualEffect.");
+            }
+
+            if (string.IsNullOrWhiteSpace(request.Name)) throw new UnityCliBridge.BridgeCommandException("E_VFX_PARAMETER_NAME_REQUIRED", "VFX parameter name is required.", "Pass a non-empty exposed parameter name.");
+            var parameterType = (request.Type ?? "float").Trim().ToLowerInvariant();
+            if (parameterType != "float" && parameterType != "int" && parameterType != "bool" && parameterType != "vector2" && parameterType != "vector3" && parameterType != "vector4" && parameterType != "color" && parameterType != "texture" && parameterType != "mesh") throw new UnityCliBridge.BridgeCommandException("E_VFX_PARAMETER_TYPE_UNSUPPORTED", "Unsupported VFX parameter type: " + parameterType, "Use float, int, bool, vector2, vector3, vector4, color, texture, or mesh.");
+            VfxToolSupport.RequireFinite(request.NumberValue, "numberValue"); VfxToolSupport.RequireFinite(request.X, "x"); VfxToolSupport.RequireFinite(request.Y, "y"); VfxToolSupport.RequireFinite(request.Z, "z"); VfxToolSupport.RequireFinite(request.W, "w"); VfxToolSupport.RequireFinite(request.R, "r", 0, 1); VfxToolSupport.RequireFinite(request.G, "g", 0, 1); VfxToolSupport.RequireFinite(request.B, "b", 0, 1); VfxToolSupport.RequireFinite(request.A, "a", 0, 1);
+            PrepareParameterApi(visualEffectType, component, parameterType, request.Name);
+            if ((parameterType == "texture" || parameterType == "mesh") && !string.IsNullOrWhiteSpace(request.AssetPath) && AssetDatabase.LoadAssetAtPath(AssetToolSupport.NormalizeAssetPath(request.AssetPath), parameterType == "texture" ? typeof(Texture) : typeof(Mesh)) == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_PARAMETER_ASSET_NOT_FOUND", "Parameter asset not found: " + request.AssetPath, "Pass an existing compatible asset path.");
+            var gameObjectId = gameObject.GetInstanceID();
+            var effects = new List<VfxPlannedEffect>();
+            try
+            {
+                ctx.CommitEffect();
+                var observedObject = VfxToolSupport.FindGameObjectByTarget(gameObjectId.ToString(System.Globalization.CultureInfo.InvariantCulture));
+                component = observedObject == null ? null : observedObject.GetComponent(visualEffectType);
+                if (component == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_OBSERVED_TARGET_MISSING", "vfx.parameter target/component disappeared after commit.", "Retry after checking the target still exists.");
+                switch (parameterType)
+                {
+                    case "float":
+                        var floatValue = (float)(request.NumberValue ?? 0d);
+                        Invoke(visualEffectType, component, "SetFloat", new[] { typeof(string), typeof(float) }, request.Name, floatValue);
+                        Verify(visualEffectType, component, "Float", request.Name, floatValue);
+                        effects.Add(VfxToolSupport.Effect("vfx.parameter", request.Name, VfxToolSupport.Number(request.NumberValue ?? 0d)));
+                        break;
+                    case "int":
+                        var intValue = request.IntValue ?? 0;
+                        Invoke(visualEffectType, component, "SetInt", new[] { typeof(string), typeof(int) }, request.Name, intValue);
+                        Verify(visualEffectType, component, "Int", request.Name, intValue);
+                        effects.Add(VfxToolSupport.Effect("vfx.parameter", request.Name, (request.IntValue ?? 0).ToString(System.Globalization.CultureInfo.InvariantCulture)));
+                        break;
+                    case "bool":
+                        var boolValue = request.BoolValue ?? false;
+                        Invoke(visualEffectType, component, "SetBool", new[] { typeof(string), typeof(bool) }, request.Name, boolValue);
+                        Verify(visualEffectType, component, "Bool", request.Name, boolValue);
+                        effects.Add(VfxToolSupport.Effect("vfx.parameter", request.Name, VfxToolSupport.Bool(request.BoolValue ?? false)));
+                        break;
+                    case "vector2":
+                        var vector2Value = new Vector2((float)(request.X ?? 0d), (float)(request.Y ?? 0d));
+                        Invoke(visualEffectType, component, "SetVector2", new[] { typeof(string), typeof(Vector2) }, request.Name, vector2Value);
+                        Verify(visualEffectType, component, "Vector2", request.Name, vector2Value);
+                        effects.Add(VfxToolSupport.Effect("vfx.parameter", request.Name, "vector2"));
+                        break;
+                    case "vector3":
+                        var vector3Value = new Vector3((float)(request.X ?? 0d), (float)(request.Y ?? 0d), (float)(request.Z ?? 0d));
+                        Invoke(visualEffectType, component, "SetVector3", new[] { typeof(string), typeof(Vector3) }, request.Name, vector3Value);
+                        Verify(visualEffectType, component, "Vector3", request.Name, vector3Value);
+                        effects.Add(VfxToolSupport.Effect("vfx.parameter", request.Name, "vector3"));
+                        break;
+                    case "vector4":
+                        var vector4Value = new Vector4((float)(request.X ?? 0d), (float)(request.Y ?? 0d), (float)(request.Z ?? 0d), (float)(request.W ?? 0d));
+                        Invoke(visualEffectType, component, "SetVector4", new[] { typeof(string), typeof(Vector4) }, request.Name, vector4Value);
+                        Verify(visualEffectType, component, "Vector4", request.Name, vector4Value);
+                        effects.Add(VfxToolSupport.Effect("vfx.parameter", request.Name, "vector4"));
+                        break;
+                    case "color":
+                        var colorValue = (Vector4)new Color((float)(request.R ?? 0d), (float)(request.G ?? 0d), (float)(request.B ?? 0d), (float)(request.A ?? 1d));
+                        Invoke(visualEffectType, component, "SetVector4", new[] { typeof(string), typeof(Vector4) }, request.Name, colorValue);
+                        Verify(visualEffectType, component, "Vector4", request.Name, colorValue);
+                        effects.Add(VfxToolSupport.Effect("vfx.parameter", request.Name, "color"));
+                        break;
+                    case "texture":
+                        var texture = string.IsNullOrWhiteSpace(request.AssetPath) ? null : AssetDatabase.LoadAssetAtPath<Texture>(AssetToolSupport.NormalizeAssetPath(request.AssetPath));
+                        if (texture == null && !string.IsNullOrWhiteSpace(request.AssetPath))
+                        {
+                            throw new UnityCliBridge.BridgeCommandException("E_VFX_TEXTURE_NOT_FOUND", "Texture not found: " + request.AssetPath, "Pass a valid Assets/ texture path.");
+                        }
+                        Invoke(visualEffectType, component, "SetTexture", new[] { typeof(string), typeof(Texture) }, request.Name, texture);
+                        Verify(visualEffectType, component, "Texture", request.Name, texture);
+                        effects.Add(VfxToolSupport.Effect("vfx.parameter", request.Name, request.AssetPath ?? "null"));
+                        break;
+                    case "mesh":
+                        var mesh = string.IsNullOrWhiteSpace(request.AssetPath) ? null : AssetDatabase.LoadAssetAtPath<Mesh>(AssetToolSupport.NormalizeAssetPath(request.AssetPath));
+                        if (mesh == null && !string.IsNullOrWhiteSpace(request.AssetPath))
+                        {
+                            throw new UnityCliBridge.BridgeCommandException("E_VFX_MESH_NOT_FOUND", "Mesh not found: " + request.AssetPath, "Pass a valid Assets/ mesh path.");
+                        }
+                        Invoke(visualEffectType, component, "SetMesh", new[] { typeof(string), typeof(Mesh) }, request.Name, mesh);
+                        Verify(visualEffectType, component, "Mesh", request.Name, mesh);
+                        effects.Add(VfxToolSupport.Effect("vfx.parameter", request.Name, request.AssetPath ?? "null"));
+                        break;
+                    default:
+                        throw new UnityCliBridge.BridgeCommandException(
+                            "E_VFX_PARAMETER_TYPE_UNSUPPORTED",
+                            "Unsupported VFX parameter type: " + parameterType,
+                            "Use float, int, bool, vector2, vector3, vector4, color, texture, or mesh.");
+                }
+            }
+            catch (TargetInvocationException exception)
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_VFX_PARAMETER_SET_FAILED",
+                    "Failed to set VFX parameter: " + (exception.InnerException == null ? exception.Message : exception.InnerException.Message),
+                    "Check the parameter name and type match the VFX Graph exposed parameters.");
+            }
+
+            UnityCliSceneMutation.MarkSceneObjectDirty(component);
+            VfxToolSupport.MarkSceneDirty(component.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                ParameterName = request.Name,
+                ParameterType = parameterType,
+                PlannedEffects = effects
+            });
+        }
+
+        private static void PrepareParameterApi(Type owner, Component component, string parameterType, string name)
+        {
+            var suffix = parameterType == "color" ? "Vector4" : char.ToUpperInvariant(parameterType[0]) + parameterType.Substring(1);
+            var valueType = parameterType == "float" ? typeof(float) : parameterType == "int" ? typeof(int) : parameterType == "bool" ? typeof(bool) : parameterType == "vector2" ? typeof(Vector2) : parameterType == "vector3" ? typeof(Vector3) : typeof(Vector4);
+            if (parameterType == "texture") valueType = typeof(Texture);
+            if (parameterType == "mesh") valueType = typeof(Mesh);
+            var set = owner.GetMethod("Set" + suffix, new[] { typeof(string), valueType });
+            var has = owner.GetMethod("Has" + suffix, new[] { typeof(string) });
+            var get = owner.GetMethod("Get" + suffix, new[] { typeof(string) });
+            if (set == null || has == null || get == null || get.ReturnType != valueType || has.ReturnType != typeof(bool)) throw new UnityCliBridge.BridgeCommandException("E_VFX_PARAMETER_API_UNSUPPORTED", "VisualEffect typed parameter API is unavailable for " + parameterType + ".", "Check the installed Visual Effect Graph package version.");
+            if (!(bool)has.Invoke(component, new object[] { name })) throw new UnityCliBridge.BridgeCommandException("E_VFX_PARAMETER_NOT_EXPOSED", "VisualEffect parameter is not exposed: " + name, "Expose a parameter with the requested name and type in the VFX Graph.");
+        }
+
+        private static void Invoke(Type owner, Component component, string methodName, System.Type[] signature, params object[] args)
+        {
+            var method = owner.GetMethod(methodName, signature);
+            if (method == null)
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_PARAMETER_API_UNSUPPORTED", "VisualEffect method is unavailable: " + methodName, "Check the installed Visual Effect Graph package version.");
+            method.Invoke(component, args);
+        }
+
+        // 每种参数都必须存在对应 Has*/Get* API，并且读回值与写入的强类型值一致。
+        private static void Verify(Type owner, Component component, string typeName, string name, object expected)
+        {
+            var has = owner.GetMethod("Has" + typeName, new[] { typeof(string) });
+            var get = owner.GetMethod("Get" + typeName, new[] { typeof(string) });
+            if (has == null || get == null)
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_PARAMETER_API_UNSUPPORTED", "VisualEffect readback API is unavailable for " + typeName + ".", "Check the installed Visual Effect Graph package version.");
+            if (!(bool)has.Invoke(component, new object[] { name }))
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_PARAMETER_NOT_EXPOSED", "VisualEffect parameter is not exposed: " + name, "Expose a parameter with the requested name and type in the VFX Graph.");
+            var actual = get.Invoke(component, new object[] { name });
+            if (!Equals(actual, expected))
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_PARAMETER_VERIFY_FAILED", "VisualEffect parameter did not retain the requested value: " + name, "Check the parameter type and value in the VFX Graph.");
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/particle-clear.cs

@@ -0,0 +1,39 @@
+#if UNITY_EDITOR
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>清空目标 ParticleSystem 的活动粒子。</summary>
+    public sealed class VfxParticleClearTool : IUnityCliTool<VfxParticleClearTool.Request, VfxParticleActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } public bool? WithChildren { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.particle.clear", Summary = "Clear live ParticleSystem particles.",
+            Description = "Clear live particles from the existing ParticleSystem, optionally including child systems.",
+            Group = "vfx",SideEffects = new[] { "particle-playback-edit" },
+            Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Clear the dust system", Input = new Request { Target = "Effects/Dust" } },
+                new ToolExample { Description = "Clear child systems", Input = new Request { Target = "Effects/Dust", WithChildren = true } }
+            }
+        };
+
+        public async System.Threading.Tasks.ValueTask<VfxParticleActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var particleSystem = VfxActionToolSupport.RequireParticle(request.Target, "vfx.particle.clear");
+            var withChildren = request.WithChildren ?? true;
+            var gameObjectId = particleSystem.gameObject.GetInstanceID();
+            ctx.CommitEffect();
+
+            particleSystem = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle.clear");
+            particleSystem.Clear(withChildren);
+            await VfxActionToolSupport.RequireParticleState(particleSystem, withChildren, system => system.particleCount == 0, "vfx.particle.clear", ctx, ct);
+            var observed = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle.clear");
+            return VfxActionToolSupport.BuildParticleResult(observed, "vfx.particle.clear", ctx.LogPath);
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/particle-create.cs

@@ -0,0 +1,80 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// vfx.particle-create - 创建或初始化 ParticleSystem。
+    /// </summary>
+    public class VfxParticleCreateTool : IUnityCliTool<VfxParticleCreateTool.Request, VfxParticleCreateTool.Result>
+    {
+        public sealed class Request : ParticleMainFields
+        {
+            public string Target { get; set; }
+            public string Name { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public VfxParticleSystemInfo ParticleSystem { get; set; }
+            public List<VfxPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.particle-create",
+            Summary = "Create or initialize a ParticleSystem on a target GameObject and apply main module defaults.",
+            Description = "Create a new GameObject when target is omitted, ensure a ParticleSystem and ParticleSystemRenderer exist, and apply any provided main module fields such as duration, startLifetime, startSpeed, size, color, looping, and simulation space.",
+            Group = "vfx",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-object-create", "component-add", "particle-main-edit" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Create a new particle system", Input = new Request { Name = "Dust", Duration = 2, StartLifetime = 1, StartSpeed = 3 } },
+                new ToolExample { Description = "Ensure particle system on target", Input = new Request { Target = "Effects/Dust", Loop = true, MaxParticles = 512 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.particle-create");
+            VfxToolSupport.PrepareParticleMainFields(request);
+            var preparedTarget = string.IsNullOrWhiteSpace(request.Target) ? null : GameObjectToolSupport.ResolveUniqueTarget(request.Target, "vfx.particle-create requires target.");
+            ctx.CommitEffect();
+            var gameObject = preparedTarget == null
+                ? VfxToolSupport.CreateSceneObject(string.IsNullOrWhiteSpace(request.Name) ? "ParticleSystem" : request.Name)
+                : VfxToolSupport.FindGameObjectByTarget(preparedTarget.GetInstanceID().ToString(System.Globalization.CultureInfo.InvariantCulture));
+            if (gameObject == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_OBSERVED_TARGET_MISSING", "vfx.particle-create target disappeared after commit.", "Retry after checking the target still exists.");
+            var gameObjectId = gameObject.GetInstanceID();
+            var particleSystem = gameObject.GetComponent<ParticleSystem>();
+            var effects = new List<VfxPlannedEffect>();
+            if (particleSystem == null)
+            {
+                particleSystem = gameObject.AddComponent<ParticleSystem>();
+                if (gameObject.GetComponent<ParticleSystemRenderer>() == null)
+                {
+                    gameObject.AddComponent<ParticleSystemRenderer>();
+                }
+                effects.Add(new VfxPlannedEffect { Type = "vfx.particle-create", Target = GameObjectToolSupport.HierarchyPath(gameObject), Property = "component", Value = "added" });
+            }
+
+            VfxToolSupport.ApplyParticleMainFields(particleSystem, request, "vfx.particle-create", effects);
+            var observed = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle-create");
+            VfxToolSupport.VerifyParticleMainFields(observed, request);
+            UnityCliSceneMutation.MarkSceneObjectDirty(observed);
+            VfxToolSupport.MarkSceneDirty(observed.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                ParticleSystem = VfxToolSupport.BuildParticleSystemInfo(observed),
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/particle-emission.cs

@@ -0,0 +1,126 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// vfx.particle-emission - 修改 ParticleSystem 发射模块。
+    /// </summary>
+    public class VfxParticleEmissionTool : IUnityCliTool<VfxParticleEmissionTool.Request, VfxParticleEmissionTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Target { get; set; }
+            public bool? Enabled { get; set; }
+            public double? RateOverTime { get; set; }
+            public double? RateOverDistance { get; set; }
+            public int? BurstCount { get; set; }
+            public List<ParticleBurstInput> Bursts { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public VfxParticleEmissionInfo Emission { get; set; }
+            public List<VfxPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.particle-emission",
+            Summary = "Update ParticleSystem emission enablement, rates, and optional burst definitions.",
+            Description = "Update the emission module of an existing ParticleSystem. Supports enabled, rateOverTime, rateOverDistance, burstCount, and an optional bursts array with time/count/cycles/repeatInterval entries.",
+            Group = "vfx",
+            DestructiveHint = false,
+            SideEffects = new[] { "particle-emission-edit" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Enable constant emission", Input = new Request { Target = "Effects/Dust", Enabled = true, RateOverTime = 12 } },
+                new ToolExample { Description = "Configure one burst", Input = new Request { Target = "Effects/Dust", BurstCount = 1, Bursts = new List<ParticleBurstInput> { new ParticleBurstInput { Time = 0, Count = 24 } } } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.particle-emission");
+            var particleSystem = VfxToolSupport.ResolveParticleSystem(request.Target);
+            if (particleSystem == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_PARTICLE_SYSTEM_NOT_FOUND",
+                    "ParticleSystem not found: " + request.Target,
+                    "Pass a GameObject name / hierarchy path with a ParticleSystem component.");
+            }
+
+            VfxToolSupport.RequireFinite(request.RateOverTime, "rateOverTime", 0);
+            VfxToolSupport.RequireFinite(request.RateOverDistance, "rateOverDistance", 0);
+            if (request.BurstCount.HasValue && request.BurstCount.Value < 0) throw new UnityCliBridge.BridgeCommandException("E_VFX_INPUT_RANGE_INVALID", "burstCount must be non-negative.", "Pass burstCount greater than or equal to zero.");
+            if (request.Bursts != null && (!request.BurstCount.HasValue || request.Bursts.Count > request.BurstCount.Value)) throw new UnityCliBridge.BridgeCommandException("E_VFX_INPUT_RANGE_INVALID", "bursts requires burstCount large enough to contain every burst.", "Set burstCount to the number of supplied bursts.");
+            VfxToolSupport.PrepareParticleBursts(request.Bursts);
+            VfxToolSupport.RequireMutation(request.Enabled.HasValue || request.RateOverTime.HasValue || request.RateOverDistance.HasValue || request.BurstCount.HasValue, "vfx.particle-emission");
+            var gameObjectId = particleSystem.gameObject.GetInstanceID();
+            var effects = new List<VfxPlannedEffect>();
+            ctx.CommitEffect();
+            particleSystem = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle-emission");
+            var emission = particleSystem.emission;
+            if (request.Enabled.HasValue)
+            {
+                emission.enabled = request.Enabled.Value;
+                effects.Add(VfxToolSupport.Effect("vfx.particle-emission", "enabled", VfxToolSupport.Bool(emission.enabled)));
+            }
+            if (request.RateOverTime.HasValue)
+            {
+                emission.rateOverTime = (float)request.RateOverTime.Value;
+                effects.Add(VfxToolSupport.Effect("vfx.particle-emission", "rateOverTime", VfxToolSupport.Number(emission.rateOverTime.constant)));
+            }
+            if (request.RateOverDistance.HasValue)
+            {
+                emission.rateOverDistance = (float)request.RateOverDistance.Value;
+                effects.Add(VfxToolSupport.Effect("vfx.particle-emission", "rateOverDistance", VfxToolSupport.Number(emission.rateOverDistance.constant)));
+            }
+            if (request.BurstCount.HasValue)
+            {
+                var burstCount = request.BurstCount.Value;
+                var bursts = new ParticleSystem.Burst[burstCount];
+                for (var index = 0; index < burstCount; index++)
+                {
+                    var burst = request.Bursts != null && index < request.Bursts.Count ? request.Bursts[index] : null;
+                    bursts[index] = new ParticleSystem.Burst(
+                        (float)(burst?.Time ?? 0d),
+                        (short)(burst?.Count ?? 10),
+                        (short)(burst?.Cycles ?? 1),
+                        (float)(burst?.RepeatInterval ?? 0.01d));
+                }
+                emission.SetBursts(bursts);
+            }
+
+            var observed = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle-emission");
+            VfxToolSupport.VerifyParticleEmissionFields(observed, request.Enabled, request.RateOverTime, request.RateOverDistance, request.BurstCount, request.Bursts);
+            var observedEmission = observed.emission;
+            if (request.Enabled.HasValue) effects.Add(VfxToolSupport.Effect("vfx.particle-emission", "enabled", VfxToolSupport.Bool(observedEmission.enabled)));
+            if (request.RateOverTime.HasValue) effects.Add(VfxToolSupport.Effect("vfx.particle-emission", "rateOverTime", VfxToolSupport.Number(observedEmission.rateOverTime.constant)));
+            if (request.RateOverDistance.HasValue) effects.Add(VfxToolSupport.Effect("vfx.particle-emission", "rateOverDistance", VfxToolSupport.Number(observedEmission.rateOverDistance.constant)));
+            if (request.BurstCount.HasValue) effects.Add(VfxToolSupport.Effect("vfx.particle-emission", "burstCount", observedEmission.burstCount.ToString(System.Globalization.CultureInfo.InvariantCulture)));
+            UnityCliSceneMutation.MarkSceneObjectDirty(observed);
+            VfxToolSupport.MarkSceneDirty(observed.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Emission = new VfxParticleEmissionInfo
+                {
+                    Enabled = observed.emission.enabled,
+                    RateOverTime = observed.emission.rateOverTime.constant,
+                    RateOverDistance = observed.emission.rateOverDistance.constant,
+                    BurstCount = observed.emission.burstCount
+                },
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/particle-info.cs

@@ -0,0 +1,55 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>
+    /// vfx.particle-info - 读取 ParticleSystem 摘要。
+    /// </summary>
+    public class VfxParticleInfoTool : IUnityCliTool<VfxParticleInfoTool.Request, VfxParticleInfoTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public VfxParticleSystemInfo ParticleSystem { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.particle-info",
+            Summary = "Read ParticleSystem main, emission, shape, and module state for a target or the first scene particle system.",
+            Description = "Read a ParticleSystem summary without changing the scene. When target is omitted, the first ParticleSystem found in the loaded scenes is used.",
+            Group = "vfx",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Inspect the first particle system", Input = new Request() },
+                new ToolExample { Description = "Inspect a named target", Input = new Request { Target = "Effects/Dust" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var particleSystem = VfxToolSupport.ResolveParticleSystem(request.Target);
+            if (particleSystem == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_PARTICLE_SYSTEM_NOT_FOUND",
+                    "ParticleSystem not found: " + request.Target,
+                    "Pass a GameObject name / hierarchy path with a ParticleSystem component.");
+            }
+
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                ParticleSystem = VfxToolSupport.BuildParticleSystemInfo(particleSystem)
+            });
+        }
+    }
+}
+#endif