add_node
Add a node to a Godot scene or instance another scene as a child, with type-checked property values saved automatically. Invalid types, parents, or properties error without adding anything.
Instructions
Add a node to a scene, or instance another scene when nodeType is a scene path. Saves automatically. Values in properties are checked against each property's declared type; a mismatch errors (Property Values in docs/tools.md). Returns: nodeName, nodeType and nodePath, read back after the add; warnings leads when Godot renamed the node or a value will not be saved. Errors and adds nothing if the type, parent or a property is invalid. Errors while a runtime session is live on this project.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"projectPath": "<projectPath>",
"scenePath": "<scenePath>",
"nodeType": "<nodeType>",
"nodeName": "<nodeName>"
},
"name": "add_node"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scale | No | Scale: {"x": 2, "y": 2} on a 2D node, {"x": 2, "y": 2, "z": 2} on a 3D node. Shorthand for properties.scale; properties wins on a conflict. | |
| visible | No | Whether the node is visible. Shorthand for properties.visible; properties wins on a conflict. | |
| modulate | No | Color modulation (e.g. {"r": 1, "g": 0, "b": 0, "a": 1}). Shorthand for properties.modulate; properties wins on a conflict. | |
| nodeName | Yes | Name for the new node as it appears in the scene tree | |
| nodeType | Yes | Godot node class to instantiate (e.g. "Sprite2D", "CollisionShape2D", "Label"), or a project-relative scene path (.tscn or .scn, e.g. "scenes/enemy.tscn") to instance an existing scene as a child - instanced children serialize as `instance=ExtResource(...)` on save | |
| position | No | Position: {"x": 100, "y": 200} on a 2D node, {"x": 0, "y": 1, "z": 0} on a 3D node. Shorthand for properties.position; properties wins on a conflict. | |
| rotation | No | Rotation in radians, for a 2D node. On a 3D node rotation is a vector: pass it as properties.rotation, {"x", "y", "z"} in radians. Shorthand for properties.rotation; properties wins on a conflict. | |
| scenePath | Yes | Scene file path relative to the project | |
| properties | No | Additional property values as a JSON object. A key here wins over the same top-level shorthand (position, rotation, scale, visible, modulate). An Object-typed property takes a res:// path, a {type: ClassName, ...props} dict that builds a Resource inline, or null; slash-suffixed keys like shader_parameter/<uniform> go inside that dict, not on the node; metadata/<name> and slash keys the node declares go straight into properties. Coercion and Packed*Array / Array[T] / Dictionary[K, V] element rules: Property Values in docs/tools.md. | |
| projectPath | Yes | Path to the Godot project directory | |
| parentNodePath | No | Parent node path from scene root (e.g. "root/Player"). Defaults to the root node; an empty string also means the root. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nodeName | Yes | Name the node has after the add. Differs from the requested nodeName when Godot renamed it. | |
| nodePath | Yes | Path from the scene root in "root/..." form, usable as nodePath elsewhere. | |
| nodeType | Yes | Class of the added node, or of the root of an instanced scene. | |
| warnings | No |