godot_run_scene
Execute a specific scene from a Godot project to test gameplay, debug functionality, or verify scene behavior during development.
Instructions
Run a specific Godot scene from an existing project.
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. | |
| headless | No | Whether to run the scene in headless mode. | |
| godot_executable | No | Optional explicit path to the Godot executable or .app bundle. |
Implementation Reference
- src/godot_mcp/server.py:857-889 (handler)Registration of the `godot_run_scene` tool, which delegates to `GodotController.run_scene`.
name="godot_run_scene", description="Run a specific Godot scene from an existing project.", 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.", }, "headless": { "type": "boolean", "description": "Whether to run the scene in headless mode.", "default": False, }, "godot_executable": { "type": "string", "description": "Optional explicit path to the Godot executable or .app bundle.", }, }, "required": ["project_path", "scene_path"], "additionalProperties": False, }, handler=lambda args: self.controller.run_scene( project_path=args["project_path"], scene_path=args["scene_path"], headless=bool(args.get("headless", False)), godot_executable=args.get("godot_executable"), ), ), - src/godot_mcp/godot.py:2058-2087 (handler)The `GodotController.run_scene` method that implements the tool's execution logic by launching a Godot subprocess.
def run_scene( self, project_path: str, scene_path: str, godot_executable: str | None = None, headless: bool = False, ) -> 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}") command = [str(executable), "--path", str(project_dir)] if headless: command.append("--headless") command.append(str(absolute_scene_path)) launched = _launch_process(command, cwd=project_dir, log_name="run-scene") return { "project_path": str(project_dir), "scene_path": str(absolute_scene_path), "scene_resource_path": resource_scene_path, "pid": launched.pid, "command": launched.command, "log_path": launched.log_path, "headless": headless, "godot_version": version, }