godot_create_scene

Create and save new Godot scenes with normalized filenames, specifying root node types and project paths for organized game development.

Instructions

Create and save a new scene with a normalized Godot-style filename and root node name.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`project_path`	Yes	Path to the Godot project directory or its project.godot file.
`scene_name`	Yes	Human-friendly scene name, for example 'Main Menu'.
`root_type`	No	Godot node type for the scene root, such as Node2D, Control, or Node3D.	Node2D
`folder`	No	Project-relative folder where the scene should be saved.	scenes
`set_as_main_scene`	No	Whether to update the project so this scene becomes the main scene.
`overwrite`	No	Whether to replace an existing scene file with the same normalized name.
`godot_executable`	No	Optional explicit path to the Godot executable or .app bundle.

Implementation Reference

src/godot_mcp/godot.py:1008-1063 (handler)

The `create_scene` method in `GodotController` executes the logic to create and save a new scene in a Godot project by calling a helper script `create_scene.gd`.

def create_scene(
    self,
    project_path: str,
    scene_name: str,
    root_type: str = "Node2D",
    folder: str = "scenes",
    set_as_main_scene: bool = False,
    overwrite: bool = False,
    godot_executable: str | None = None,
) -> dict[str, Any]:
    project_dir = ensure_project_path(project_path)
    executable, version = resolve_godot_executable(godot_executable)

    if not scene_name.strip():
        raise GodotError("`scene_name` is required.")

    normalized_folder = normalize_project_subdir(folder)
    scene_dir = project_dir / normalized_folder if normalized_folder else project_dir
    scene_dir.mkdir(parents=True, exist_ok=True)

    filename = f"{snake_case_name(scene_name)}.tscn"
    absolute_scene_path = (scene_dir / filename).resolve()
    if absolute_scene_path.exists() and not overwrite:
        raise GodotError(f"Scene already exists at {absolute_scene_path}. Pass `overwrite=true` to replace it.")

    relative_scene_path = absolute_scene_path.relative_to(project_dir)
    resource_scene_path = f"res://{relative_scene_path.as_posix()}"
    root_name = pascal_case_name(scene_name)

    _run_godot_script(
        executable=executable,
        project_dir=project_dir,
        script_name="create_scene.gd",
        user_args=[
            "--scene-path",
            resource_scene_path,
            "--root-type",
            root_type,
            "--root-name",
            root_name,
            "--set-main-scene",
            "true" if set_as_main_scene else "false",
        ],
    )

    return {
        "project_path": str(project_dir),
        "scene_name": scene_name,
        "scene_path": str(absolute_scene_path),
        "scene_resource_path": resource_scene_path,
        "scene_root_name": root_name,
        "root_type": root_type,
        "set_as_main_scene": set_as_main_scene,
        "godot_executable": str(executable),
        "godot_version": version,
    }

src/godot_mcp/server.py:241-291 (registration)

The `godot_create_scene` tool is registered in `GodotMcpServer` with its description, input schema, and handler.

    name="godot_create_scene",
    description="Create and save a new scene with a normalized Godot-style filename and root node name.",
    input_schema={
        "type": "object",
        "properties": {
            "project_path": {
                "type": "string",
                "description": "Path to the Godot project directory or its project.godot file.",
            },
            "scene_name": {
                "type": "string",
                "description": "Human-friendly scene name, for example 'Main Menu'.",
            },
            "root_type": {
                "type": "string",
                "description": "Godot node type for the scene root, such as Node2D, Control, or Node3D.",
                "default": "Node2D",
            },
            "folder": {
                "type": "string",
                "description": "Project-relative folder where the scene should be saved.",
                "default": "scenes",
            },
            "set_as_main_scene": {
                "type": "boolean",
                "description": "Whether to update the project so this scene becomes the main scene.",
                "default": False,
            },
            "overwrite": {
                "type": "boolean",
                "description": "Whether to replace an existing scene file with the same normalized name.",
                "default": False,
            },
            "godot_executable": {
                "type": "string",
                "description": "Optional explicit path to the Godot executable or .app bundle.",
            },
        },
        "required": ["project_path", "scene_name"],
        "additionalProperties": False,
    },
    handler=lambda args: self.controller.create_scene(
        project_path=args["project_path"],
        scene_name=args["scene_name"],
        root_type=args.get("root_type", "Node2D"),
        folder=args.get("folder", "scenes"),
        set_as_main_scene=bool(args.get("set_as_main_scene", False)),
        overwrite=bool(args.get("overwrite", False)),
        godot_executable=args.get("godot_executable"),
    ),
),

Godot MCP