godot-omni

Overview Schema Source Related Servers Discussions Admin

particle_manage

Create and configure Godot particle systems (2D/3D, GPU/CPU) with presets, emission properties, and draw passes for visual 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.

Changed1 schema field changedv5.0.14Sep 20, 2026

changedInput schema / properties / op / enum

Previous value: -[
-  "apply_preset",
-  "create",
-  "get",
-  "restart",
-  "set_draw_pass",
-  "set_main",
-  "set_process"
-]New value: +[
+  "apply_preset",
+  "create",
+  "get",
+  "restart",
+  "set_draw_pass",
+  "set_main",
+  "set_process",
+  "spawn_preset_2d"
+]

First observedv4.1.0Sep 17, 2026

TDQS

A4.1/5.0

Behavior5/5

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

With no annotations, the description carries full responsibility for behavioral disclosure, and it does so thoroughly: it documents undo grouping, runtime-only restart, auto-created sub-resources, INVALID_PARAMS for bad overrides, applied_* response reporting, and the GPU gravity vector format. This is exceptional transparency for an unannotated tool.

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: a shared behavior note is front-loaded, followed by a scannable bullet list of operations. The only notable redundancy is repeating the GPU gravity vector requirement in both set_process and apply_preset, but overall every section earns its place.

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

Completeness3/5

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

The description is rich in operation-level detail, error behavior, and call shape, and the presence of an output schema means return values need not be re-explained. However, the input schema exposes spawn_preset_2d as a valid op, and the description never documents it, which is a significant completeness gap for an agent choosing operations.

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

Parameters4/5

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

The schema provides almost no parameter detail (0% coverage), and the description compensates with full op signatures, type enums, property lists, and override structures. However, it omits the spawn_preset_2d enum value and defers the full set_process property list to the Godot reference, leaving some parameter semantics incomplete.

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

Purpose4/5

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

The description clearly targets particle systems (GPUParticles2D/3D, CPUParticles2D/3D) and enumerates specific verbs for each operation, so an agent knows what resource this tool manages. It does not explicitly differentiate from sibling tools such as node_create or material_manage, instead relying on the particle-specific scope.

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 op-by-op breakdown gives concrete guidance on when to use create, set_main, set_process, set_draw_pass, restart, get, and apply_preset, including type-specific behavior and override routing. It does not explicitly state when to prefer this tool over sibling node/material tools, so exclusion guidance is missing.

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

Deploy Server