godot_add_primitive_mesh
Add primitive 3D mesh shapes like boxes, spheres, and cylinders to Godot scenes using MeshInstance3D nodes with customizable parameters and transforms.
Instructions
Add a MeshInstance3D with a built-in PrimitiveMesh resource such as BoxMesh, CylinderMesh, SphereMesh, CapsuleMesh, PlaneMesh, PrismMesh, QuadMesh, or TorusMesh.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes | Path to the Godot project directory or its project.godot file. | |
| scene_path | Yes | Path to the target .tscn file. Absolute, relative, and res:// paths are supported. | |
| mesh_type | Yes | Primitive mesh class to instantiate, such as BoxMesh, CylinderMesh, SphereMesh, CapsuleMesh, PlaneMesh, PrismMesh, QuadMesh, or TorusMesh. | |
| parent_path | No | Scene-relative node path where the new mesh node should be attached. Use '.' for the root. | . |
| node_name | No | Optional explicit MeshInstance3D node name. Defaults to a PascalCase form of the mesh type without a trailing Mesh suffix. | |
| mesh_parameters | No | Optional primitive mesh property overrides such as size, radius, height, or segment counts. | |
| transform | No | Optional Node3D transform fields to apply to the new MeshInstance3D. Vector values can be passed as objects like {x, y, z}. | |
| godot_executable | No | Optional explicit path to the Godot executable or .app bundle. |
Implementation Reference
- src/godot_mcp/godot.py:1291-1385 (handler)The handler method `add_primitive_mesh` in `GodotController` which executes the logic for adding a primitive mesh.
def add_primitive_mesh( self, project_path: str, scene_path: str, mesh_type: str, parent_path: str = ".", node_name: str | None = None, mesh_parameters: dict[str, Any] | None = None, transform: dict[str, Any] | None = None, godot_executable: str | None = None, ) -> dict[str, Any]: project_dir = ensure_project_path(project_path) executable, version = resolve_godot_executable(godot_executable) absolute_scene_path, resource_scene_path = resolve_scene_path(project_dir, scene_path) if not absolute_scene_path.exists(): raise GodotError(f"Scene not found: {absolute_scene_path}") final_mesh_type = mesh_type.strip() if not final_mesh_type: raise GodotError("`mesh_type` is required.") normalized_parent_path = normalize_scene_node_path(parent_path) final_node_name = (node_name or "").strip() if not final_node_name: base_name = final_mesh_type[:-4] if final_mesh_type.lower().endswith("mesh") else final_mesh_type final_node_name = pascal_case_name(base_name, default="Mesh") final_mesh_parameters = mesh_parameters or {} if not isinstance(final_mesh_parameters, dict): raise GodotError("`mesh_parameters` must be an object when provided.") final_transform = transform or {} if not isinstance(final_transform, dict): raise GodotError("`transform` must be an object when provided.") payload = { "mesh_parameters": final_mesh_parameters, "transform": final_transform, } try: with tempfile.NamedTemporaryFile( mode="w", encoding="utf-8", suffix="-godot-primitive-mesh.json", delete=False, ) as handle: json.dump(payload, handle, ensure_ascii=False) config_path = handle.name except TypeError as exc: raise GodotError( "`mesh_parameters` or `transform` contains a value that could not be serialized to JSON." ) from exc try: output = _run_godot_script( executable=executable, project_dir=project_dir, script_name="add_primitive_mesh.gd", user_args=[ "--scene-path", resource_scene_path, "--parent-path", normalized_parent_path, "--node-name", final_node_name, "--mesh-type", final_mesh_type, "--config-path", config_path, ], ) finally: Path(config_path).unlink(missing_ok=True) parsed = _parse_script_json_output(output, "add_primitive_mesh.gd") supported_mesh_parameters = parsed.get("supported_mesh_parameters", []) if not isinstance(supported_mesh_parameters, list): raise GodotError("Primitive mesh creation did not return a supported parameter list.") return { "project_path": str(project_dir), "scene_path": str(absolute_scene_path), "scene_resource_path": resource_scene_path, "parent_path": parsed.get("parent_path", normalized_parent_path), "node_path": parsed.get("node_path"), "node_name": parsed.get("node_name", final_node_name), "node_type": parsed.get("node_type", "MeshInstance3D"), "mesh_type": parsed.get("mesh_type", final_mesh_type), "mesh_parameters": parsed.get("mesh_parameters", {}), "supported_mesh_parameters": supported_mesh_parameters, "updated_mesh_parameters": parsed.get("updated_mesh_parameters", []), "transform": parsed.get("transform", {}), "godot_executable": str(executable), "godot_version": version, } - src/godot_mcp/server.py:547-599 (registration)Tool registration for `godot_add_primitive_mesh` in `server.py`.
name="godot_add_primitive_mesh", description="Add a MeshInstance3D with a built-in PrimitiveMesh resource such as BoxMesh, CylinderMesh, SphereMesh, CapsuleMesh, PlaneMesh, PrismMesh, QuadMesh, or TorusMesh.", input_schema={ "type": "object", "properties": { "project_path": { "type": "string", "description": "Path to the Godot project directory or its project.godot file.", }, "scene_path": { "type": "string", "description": "Path to the target .tscn file. Absolute, relative, and res:// paths are supported.", }, "mesh_type": { "type": "string", "description": "Primitive mesh class to instantiate, such as BoxMesh, CylinderMesh, SphereMesh, CapsuleMesh, PlaneMesh, PrismMesh, QuadMesh, or TorusMesh.", }, "parent_path": { "type": "string", "description": "Scene-relative node path where the new mesh node should be attached. Use '.' for the root.", "default": ".", }, "node_name": { "type": "string", "description": "Optional explicit MeshInstance3D node name. Defaults to a PascalCase form of the mesh type without a trailing Mesh suffix.", }, "mesh_parameters": { "type": "object", "description": "Optional primitive mesh property overrides such as size, radius, height, or segment counts.", }, "transform": { "type": "object", "description": "Optional Node3D transform fields to apply to the new MeshInstance3D. Vector values can be passed as objects like {x, y, z}.", }, "godot_executable": { "type": "string", "description": "Optional explicit path to the Godot executable or .app bundle.", }, }, "required": ["project_path", "scene_path", "mesh_type"], "additionalProperties": False, }, handler=lambda args: self.controller.add_primitive_mesh( project_path=args["project_path"], scene_path=args["scene_path"], mesh_type=args["mesh_type"], parent_path=args.get("parent_path", "."), node_name=args.get("node_name"), mesh_parameters=args.get("mesh_parameters"), transform=args.get("transform"), godot_executable=args.get("godot_executable"), ), ),