Godot AI

Overview Schema Source Related Servers Discussions Admin

Particle Manage

particle_manage

Create and manage particle systems in Godot, supporting 2D/3D GPU and CPU emitters. Apply curated presets, configure emission, draw passes, and restart effects.

Instructions

Particle systems (GPUParticles2D/3D, CPUParticles2D/3D). All write ops create the node + sub-resources (ProcessMaterial, default QuadMesh draw pass) in a single undo action.

Ops: • create(parent_path, name="Particles", type="gpu_3d") Create an emitter. type: "gpu_3d" | "gpu_2d" | "cpu_3d" | "cpu_2d". For GPU emitters, auto-creates ProcessMaterial; for gpu_3d, also a default QuadMesh draw pass. • set_main(node_path, properties) Node-level props: amount, lifetime, one_shot, explosiveness, preprocess, speed_scale, randomness, fixed_fps, emitting, local_coords, interp_to_end. • set_process(node_path, properties) Behavior props (auto-creates ProcessMaterial for GPU). Emission shape, velocity, gravity, color_ramp, scale_curve, turbulence. See full property list in the Godot reference. GPU gravity is a Vector3 — pass {x, y, z} or [x, y, z], including for gpu_2d (the shared ProcessMaterial is 3D; z is ignored in 2D). • set_draw_pass(node_path, pass_=1, mesh="", texture="", material="") What gets drawn per particle. GPU 3D: mesh in draw_pass_N + optional material override. GPU 2D / CPU 2D: texture. CPU 3D: mesh. • restart(node_path) Restart emission. Runtime-only, not undoable. • get(node_path) Inspect main props, process material, draw passes. • apply_preset(parent_path, name, preset, type="gpu_3d", overrides=None) Curated effects: fire, smoke, spark_burst, magic_swirl, rain, explosion, lightning. One-shot presets re-trigger via restart. overrides = {"main": {...}, "process": {...}, "draw": {...}}; bare keys are auto-routed to main (amount, lifetime, one_shot, ...) or process — draw keys must be nested under "draw". draw configures the gpu_3d draw-pass StandardMaterial3D (blend_mode, albedo_color, emission, ...); on gpu_2d only draw.texture (res:// path) applies; cpu_* types reject draw overrides. Unknown or malformed override keys return INVALID_PARAMS (never silently dropped); response reports applied_main / applied_process / applied_draw. GPU gravity requires {x, y, z} (or [x, y, z]) even for gpu_2d.

Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`op`	Yes
`params`	No
`session_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv3.1.4Aug 10, 2026
Removedv3.0.7Jul 26, 2026
First observedv2.9.1Jul 11, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses side effects (single undo action, auto-created ProcessMaterial and QuadMesh), runtime-only behavior, invalid-override handling returning INVALID_PARAMS, and type-specific vector requirements. This is strong behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with a front-loaded scope and a clear operation-by-operation breakdown. There is some redundancy, notably GPU gravity formatting stated twice, and the length is high, but each section contributes necessary detail for a seven-operation tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with a sparse schema and no annotations, the description is remarkably complete: it covers operation signatures, property groupings, preset names, override routing, error behavior, and call shape. The output schema exists, so return-value details are already handled, and the pointer to the Godot reference for the full property list is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description compensates fully. It documents every op's parameters, type enum values, property groups, preset names, override structure, and per-type constraints like GPU gravity requiring {x, y, z} or [x, y, z]. This goes well beyond the minimal input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description immediately scopes to 'Particle systems (GPUParticles2D/3D, CPUParticles2D/3D)' and enumerates precise operations (create, set_main, set_process, set_draw_pass, restart, get, apply_preset). This clearly distinguishes it from sibling tools like node_create or material_manage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear operational context: all write ops create nodes plus sub-resources in one undo action, restart is runtime-only and not undoable, and the canonical call shape is specified. It does not explicitly state when not to use this tool versus alternatives, but it provides enough context for tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.