Tools

30 tools, named domain_verb. A tool that does several related things takes an op. An unknown op or argument is refused with the valid set listed. Generated from the server.

A call and its answer

project_settings {
  "projectPath": "/home/you/game",
  "op": "set",
  "setting": "display/window/size/viewport_width",
  "value": 1280
}

{
  "setting_path": "display/window/size/viewport_width",
  "old_value": 1152,
  "new_value": 1280,
  "was_new": false,
  "saved": true
}

new_value is read from the engine after the write. Engine stderr comes back under engine_messages. Every call takes projectPath, except the runtime_* and debug_* tools, where it picks between running games.

project

`project_info`

What a project is: its name and main scene from project.godot, the Godot that answers, and how many scenes, scripts and assets it holds, with optional sections on top.

Needs projectPath.

Arguments

include array: Extra sections: registered autoloads, addons and whether each is enabled, export presets, the audio bus layout, a health report, or export validation.
preset string: For validation: the export preset to validate against.
detail string: full adds what to do about it to every validation finding. Default summary.

`project_settings`

Reads or writes project.godot: settings, autoloads, the main scene, input actions, plugins and audio buses.

op	what it does	needs
`get`	read one setting	`projectPath` `setting`
`set`	write one setting	`projectPath` `setting` `value`
`add_autoload`	register an autoload singleton	`projectPath` `name` `path`
`remove_autoload`	unregister an autoload	`projectPath` `name`
`set_main_scene`	choose the scene the game starts in	`projectPath` `scenePath`
`add_input_action`	register an input action and its events	`projectPath` `actionName` `events`
`enable_plugin`	enable an addon	`projectPath` `pluginName`
`disable_plugin`	disable an addon	`projectPath` `pluginName`
`add_audio_bus`	add an audio bus	`projectPath` `busName`
`set_audio_bus_effect`	add or configure an effect on a bus	`projectPath` `busIndex` `effectIndex` `effectType`
`set_audio_bus_volume`	set a bus volume	`projectPath` `busIndex` `volumeDb`

Arguments

setting string: Setting path, such as "display/window/size/viewport_width".
value any: The value to write. Engine types may be tagged, {"_type": "Vector2", "x": 1, "y": 2}.
name string: Autoload name.
path string: Autoload script or scene inside the project.
enabled boolean: Autoloads: register enabled. Default true.
scenePath string: Scene file inside the project, such as "scenes/main.tscn" or "res://scenes/main.tscn".
actionName string: Input action name, such as "jump".
events array: The events that trigger the action.
deadzone number: Input actions: analogue deadzone, 0 to 1. Default 0.5.
pluginName string: Folder name under addons/.
busName string: Audio bus name.
parentBusIndex number: Audio buses: the bus to send to. Default 0, Master.
busIndex number: Audio bus index.
effectIndex number: Slot on the bus for the effect.
effectType string: Effect class, such as "AudioEffectReverb".
volumeDb number: Bus volume in decibels.

`project_search`

Searches text or a regular expression across project files and returns file paths with line numbers.

Needs projectPath, query.

Arguments

query string: The text or pattern to find.
fileTypes array: Extensions to search, such as ["gd", "tscn"]. Default: every text file.
regex boolean: Read the query as a regular expression. Default false.
caseSensitive boolean: Default false.
maxResults number: Default 100.

`project_dependencies`

What a resource depends on, or what depends on it.

Needs projectPath, resourcePath.

Arguments

resourcePath string: File inside the project, such as "sprites/hero.png" or "materials/steel.tres".
direction string: forward: what this resource loads, with cycles reported. reverse: every file that refers to it and how, a scene instancing it, a script extending, preloading or loading it, and for a script with a class_name every use of that name. Default forward.
depth number: forward: how many levels to follow. Default unlimited.
includeBuiltin boolean: forward: include the engine's own res://. resources. Default false.
fileTypes array: reverse: extensions to look in.

`project_import`

The import pipeline: what needs importing, how a resource is imported, reimports, UIDs, and the global class list the editor and the engine read.

op	what it does	needs
`status`	which resources are outdated or failed, or one resource with resourcePath	`projectPath`
`options`	the import options of one resource	`projectPath` `resourcePath`
`set_options`	change import options	`projectPath` `resourcePath` `options`
`reimport`	reimport one resource, or everything modified without resourcePath	`projectPath`
`uid`	the UID of one file	`projectPath` `resourcePath`
`refresh_uids`	resave every resource so UID references are current	`projectPath`
`refresh_classes`	rewrite .godot/global_script_class_cache.cfg from the class_name declarations on disk, for an editor whose list has gone stale	`projectPath`

Arguments

resourcePath string: File inside the project, such as "sprites/hero.png" or "materials/steel.tres".
includeUpToDate boolean: status: list resources that are current as well. Default false.
options object: set_options: import options keyed as the .import file spells them, {"compress/mode": 1}.
reimport boolean: set_options: reimport afterwards. Default true.
force boolean: reimport: reimport even what is current. Default false.

`project_export`

Export presets and exports.

op	what it does	needs
`list`	the presets in export_presets.cfg	`projectPath`
`run`	export with a preset	`projectPath` `preset` `outputPath`

Arguments

preset string: Preset name from export_presets.cfg.
outputPath string: Where the export is written, inside the project.
debug boolean: run: a debug export. Default false.

`project_test`

Runs the project's gdUnit4 tests headless and answers with every case: which failed, where, and what the assertion said. The class list is rebuilt first, so a suite written a moment ago is found. On Windows and Linux the run gets a user:// of its own, so a suite that saves a game writes nowhere near the saves of the copy somebody plays. Needs gdUnit4 under addons/gdUnit4.

Needs projectPath.

Arguments

path string: A test directory or one suite file inside the project. Default test.
ignore array: Suites or cases to leave out, as "suite_name" or "suite_name:test_name".
failFast boolean: Stop at the first failure. Default false: the whole set runs.
timeoutMs number: How long the run may take before it is killed. Default 600000.

scene

`scene_create`

Creates a scene file, saves one, or saves a copy under a new path. Needs the editor connected.

op	what it does	needs
`create` default	a new scene with one root node	`projectPath` `scenePath`
`save`	save the scene as it is in the editor	`projectPath` `scenePath`
`save_as`	save a copy under newPath	`projectPath` `scenePath` `newPath`

Arguments

scenePath string: Scene file inside the project, such as "scenes/main.tscn" or "res://scenes/main.tscn".
rootNodeType string: create: the root node class. Default Node2D.
newPath string: save_as: where the copy goes.

`scene_tree`

The nodes of a scene file: names, classes and hierarchy, with properties when asked. Needs the editor connected.

Needs projectPath, scenePath.

Arguments

scenePath string: Scene file inside the project, such as "scenes/main.tscn" or "res://scenes/main.tscn".
depth number: How many levels to descend. Default: all.
includeProperties boolean: Include each node's properties. Default false.

`scene_node`

One node in a scene file: add, read, set, duplicate, reparent or delete it, or paint TileMap cells. Any ClassDB node type can be added, so a NavigationRegion2D, an AnimationTree or a Camera3D is an add with that nodeType and its properties. A property holding a Resource takes the res:// path of one, so a texture, a material or a theme is a set like any other. Needs the editor connected.

op	what it does	needs
`add`	add a node of any class	`projectPath` `scenePath` `nodeType` `nodeName`
`get`	read a node's properties	`projectPath` `scenePath` `nodePath`
`set`	set properties on a node	`projectPath` `scenePath` `nodePath` `properties`
`duplicate`	copy a node and its children	`projectPath` `scenePath` `nodePath` `newName`
`reparent`	move a node under another parent	`projectPath` `scenePath` `nodePath` `newParentPath`
`delete`	remove a node and its children	`projectPath` `scenePath` `nodePath`
`set_tilemap_cells`	place tiles in a TileMap	`projectPath` `scenePath` `nodePath` `cells`

Arguments

scenePath string: Scene file inside the project, such as "scenes/main.tscn" or "res://scenes/main.tscn".
nodePath string: Node path from the scene root, such as "Player/Sprite2D". "." is the root.
parentNodePath string: add: where the node goes. Default the root. duplicate: where the copy goes.
nodeType string: add: the node class, such as "CharacterBody2D".
nodeName string: add: the new node's name.
properties object: Properties to set, keyed by Godot property name. Vectors, colours and the like may be written as {"x": 1, "y": 2} or tagged {"_type": "Vector2", "x": 1, "y": 2}.
newName string: duplicate: the copy's name.
newParentPath string: reparent: the new parent.
includeDefaults boolean: get: include properties still at their default. Default false.
layer number: set_tilemap_cells: the TileMap layer. Default 0.
cells array: Cells to place.

`scene_signal`

Signal connections in a scene file. Needs the editor connected.

op	what it does	needs
`connect`	connect a signal to a method	`projectPath` `scenePath` `sourceNodePath` `signalName` `targetNodePath` `methodName`
`disconnect`	remove a connection	`projectPath` `scenePath` `sourceNodePath` `signalName` `targetNodePath` `methodName`
`list`	every connection in the scene	`projectPath` `scenePath`

Arguments

scenePath string: Scene file inside the project, such as "scenes/main.tscn" or "res://scenes/main.tscn".
sourceNodePath string: The node that emits.
signalName string
targetNodePath string: The node whose method is called.
methodName string
flags number: connect: Object.ConnectFlags, such as 1 for deferred.
nodePath string: list: only connections involving this node.

`scene_animation`

Animations in an AnimationPlayer and states in an AnimationTree state machine. Needs the editor connected.

op	what it does	needs
`create`	a new animation in an AnimationPlayer	`projectPath` `scenePath` `playerNodePath` `animationName`
`add_track`	a property or method track with keyframes	`projectPath` `scenePath` `playerNodePath` `animationName` `track`
`add_state`	a state playing an animation, in an AnimationTree	`projectPath` `scenePath` `animTreePath` `stateName` `animationName`
`connect_states`	a transition between two states	`projectPath` `scenePath` `animTreePath` `fromState` `toState`

Arguments

scenePath string: Scene file inside the project, such as "scenes/main.tscn" or "res://scenes/main.tscn".
playerNodePath string: The AnimationPlayer node.
animationName string
length number: create: seconds. Default 1.
loopMode string: create: default none.
step number: create: keyframe snap in seconds. Default 0.1.
track object: The track to add.
animTreePath string: The AnimationTree node.
stateName string
stateMachinePath string: add_state: a nested state machine. Default the root.
fromState string
toState string
transitionType string: connect_states: default immediate.
advanceCondition string: connect_states: the condition parameter that advances.

script

`script_edit`

Creates a GDScript file, or adds functions, variables and signals to one. Every declaration written carries a type. create loads what it wrote under the project's own warning settings and answers with parses; the engine's reasons for a refusal come back under engine_messages.

op	what it does	needs
`create`	a new script file	`projectPath` `scriptPath`
`modify`	add to an existing script	`projectPath` `scriptPath` `modifications`

Arguments

scriptPath string: Script file inside the project, such as "scripts/player.gd".
className string: create: a class_name for the script.
extends string: create: the base class. Default Node.
content string: create: the whole file, instead of a template.
template string: create: a starting shape.
modifications array: Additions to make, in order.

`script_info`

What a script contains: its structure from the file, or symbols, completions and hover text from the editor's language server.

op	what it does	needs
`structure` default	functions, variables, signals, class_name and extends, read from the file	`projectPath` `scriptPath`
`symbols`	document symbols from the language server	`projectPath` `scriptPath`
`completion`	completions at a position	`projectPath` `scriptPath` `line` `character`
`hover`	hover text at a position	`projectPath` `scriptPath` `line` `character`

Arguments

scriptPath string: Script file inside the project, such as "scripts/player.gd".
includeInherited boolean: structure: include inherited members. Default false.
line number: completion, hover: zero-based line.
character number: completion, hover: zero-based column.

`script_diagnostics`

Errors and warnings for a script from the editor's language server, and whether the script is clean. Needs the editor running.

Needs projectPath, scriptPath.

Arguments

scriptPath string: Script file inside the project, such as "scripts/player.gd".

resource

`resource_edit`

Resource files: create any ClassDB resource as .tres, change one, write a shader, build a TileSet, or set a Theme colour or font size. A material is a create with resourceType StandardMaterial3D, ShaderMaterial or CanvasItemMaterial. Needs the editor connected.

op	what it does	needs
`create`	a new resource of any class	`projectPath` `resourcePath` `resourceType`
`modify`	set properties on an existing resource	`projectPath` `resourcePath` `properties`
`create_shader`	a .gdshader file	`projectPath` `resourcePath` `shaderType`
`create_tileset`	a TileSet from texture atlases	`projectPath` `resourcePath` `sources`
`set_theme_color`	a colour in a Theme	`projectPath` `resourcePath` `controlType` `colorName` `color`
`set_theme_font_size`	a font size in a Theme	`projectPath` `resourcePath` `controlType` `fontSizeName` `size`

Arguments

resourcePath string: File inside the project, such as "sprites/hero.png" or "materials/steel.tres".
resourceType string: create: the resource class, such as "PhysicsMaterial" or "StandardMaterial3D".
properties object: Properties to set, keyed by Godot property name. Vectors, colours and the like may be written as {"x": 1, "y": 2} or tagged {"_type": "Vector2", "x": 1, "y": 2}.
script string: create: a script to attach, for custom resources.
shaderType string: create_shader.
code string: create_shader: the shader source. Default: a minimal shader of that type.
sources array: Atlas sources, one per texture.
controlType string: Theme ops: the Control class, such as "Button".
colorName string: set_theme_color: such as "font_color".
color object
fontSizeName string: set_theme_font_size: such as "font_size".
size number: set_theme_font_size: pixels.

editor

`editor_launch`

Opens the Godot editor on a project, in a window on this machine, or restarts the one already connected. An editor goes on serving the addon it read at startup, so restart is what puts a gdharness upgrade into effect; it saves open scenes on the way out and answers with the version that came back. Only an editor with a window can be restarted, because the engine hands back none of the arguments it was started with. editor_status says which editor is connected and whether it is holding an old addon.

op	what it does	needs
`open` default	open the editor on a project	`projectPath`
`restart`	restart the connected editor and wait for it	—

`editor_run`

The run: starting the project, stopping it, or booting it once to see whether it comes up clean. start keeps it running and collecting output until stop, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. check boots it headless for a few frames, waits for it to quit, and answers with the verdict: whether it came up, and every error and warning it printed on the way.

op	what it does	needs
`start` default	run the project until stop	`projectPath`
`stop`	end the run and answer with what it printed last	`projectPath`
`check`	boot headless, quit after a few frames, and report the verdict	`projectPath`

Arguments

scene string: A scene to run instead of the main scene.
headless boolean: start: force a window or no window.
frames number: check: frames to run before quitting. Default 3.
timeoutMs number: check: how long to give the boot before it is called hung. Default 60000.

`editor_output`

What the project started by editor_run has printed, as entries with a severity: the errors and warnings the engine reported, each with where it happened, and everything else as info. Answers with the counts and the verdict as well as the entries.

Arguments

severity string: The least severe entry to include. Default info, which is everything.
sinceLastCall boolean: Only entries printed since the previous editor_output. Default false.
contains string: Only entries mentioning this text.
limit number: The most entries to answer with, newest kept. Default 200.

`editor_status`

Whether the editor addon is connected, which Godot answers, whether the editor is playing something, and whether a game with the runtime addon is reachable.

`editor_rescan`

Makes the running editor scan the project filesystem, so files written outside it, and any class_name they declare, become visible. Needs the editor connected.

Needs projectPath.

Arguments

timeoutMs number: How long to wait for the scan. Default 30000.

`editor_classes`

The engine's ClassDB: find classes, read one in full, or walk an inheritance tree.

op	what it does	needs
`query` default	classes matching a filter or category	`projectPath`
`info`	methods, properties, signals and enums of one class	`projectPath` `className`
`inheritance`	ancestors and descendants of one class	`projectPath` `className`

Arguments

filter string: query: a substring of the class name.
category string: query: limit to one family.
instantiableOnly boolean: query: leave out abstract classes. Default false.
className string: info, inheritance: the class.
includeInherited boolean: info: include inherited members. Default false.

runtime

`runtime_inspect`

Questions about the running game: the scene tree, the nodes matching a query, where one node is on screen, what one property reads, or the performance metrics. Needs the game running with the runtime addon.

op	what it does	needs
`tree` default	the live scene tree	—
`find`	the paths of every node matching className, script, namePattern or group	—
`rect`	one node's rectangle or position, in canvas and in window pixels	`nodePath`
`property`	what one property reads on a node, refusing a property the node does not have	`nodePath` `property`
`metrics`	frame time, memory, draw calls and the rest	—

Arguments

nodePath string: tree, find: where to start, default /root. rect: the node to place. property: the node to read.
property string: property: which one to read.
depth number: tree: levels to descend. Default 3.
includeProperties boolean: tree: include each node's properties. Default false.
className string: find: a native class, matching its subclasses too, or a class_name.
script string: find: the script file the node carries.
namePattern string: find: a case-insensitive glob on the node name, such as "Enemy*".
group string: find: a group the node is in.
limit number: find: the most nodes to answer with. Default 100.
metrics array: metrics: which to read. Default all.

`runtime_invoke`

Sets a property or calls a method on a node in the running game. Needs the game running with the runtime addon.

op	what it does	needs
`set`	set a property	`nodePath` `property` `value`
`call`	call a method and return its result	`nodePath` `method`

Arguments

nodePath string: Absolute node path, such as "/root/Main/Player".
property string
value any: set: the value, fitted to the property's type.
method string
args array: call: the arguments, fitted to the method's parameter types.

`runtime_capture`

A picture of the running game: the whole screen or one viewport, as an image. Needs the game running with a window.

op	what it does	needs
`screenshot` default	the screen	—
`viewport`	one viewport's texture	—

Arguments

viewportPath string: viewport: the Viewport node. Default the root viewport.
width number: Scale the image to this width.
height number: Scale the image to this height.

`runtime_input`

Input to the running game: a whole click on a Control named by path, or a raw action, key, mouse button or mouse motion. All of it works headless, where the window is 64 by 64 and the GUI only takes what is inside it.

op	what it does	needs
`click`	press and release on a Control, a frame apart, and answer with what was under the pointer and what became of the control: in_tree, removed or freed	`nodePath`
`action`	press or release an action	`action`
`key`	press or release a key	`keycode`
`mouse_click`	one mouse button event at a position	`x` `y`
`mouse_motion`	move the mouse to a position	`x` `y`

Arguments

nodePath string: click: the Control to click, at its centre.
action string: action: the InputMap action name.
pressed boolean: Press or release. Default true.
strength number: action: 0 to 1. Default 1.
keycode string: key: the key name, such as "Space" or "A".
shift boolean
ctrl boolean
alt boolean
x number: mouse_click, mouse_motion: window pixels.
y number: mouse_click, mouse_motion: window pixels.
button string: click, mouse_click: default left.
doubleClick boolean: click, mouse_click: default false.
relativeX number: mouse_motion: movement since the last event.
relativeY number: mouse_motion: movement since the last event.

`runtime_wait`

Lets the running game get on with it and answers when something has happened: a number of frames, a signal, or a property reaching a value. Needs the game running with the runtime addon.

op	what it does	needs
`frames`	let frames pass	`frames`
`signal`	wait for a signal and answer with what it carried	`nodePath` `signal`
`until`	wait for a property to read as a value and answer with what it read	`nodePath` `property` `value`

Arguments

frames number: frames: how many to let pass, 1 to 600.
nodePath string: signal, until: the node.
signal string: signal: the signal name.
property string: until: the property name.
value any: until: the value to wait for, fitted to the property's type.
timeoutMs number: signal, until: how long to wait before answering anyway. Default 5000.

debug

`debug_breakpoint`

Sets or removes a breakpoint through the editor's debug adapter. Needs the editor, not a running game: set them first, then editor_run, and the game stops where you asked.

op	what it does	needs
`set`	set a breakpoint	`projectPath` `scriptPath` `line`
`remove`	remove a breakpoint	`projectPath` `scriptPath` `line`

Arguments

scriptPath string: Script file inside the project, such as "scripts/player.gd".
line number: One-based line.

`debug_control`

Continues or steps the debugged game through the editor's debug adapter, answering with the stack where it ended up. There is no pause and no step_out: Godot's adapter answers a pause by reporting the game stopped and leaving it running, and implements no stepOut at all, so hold the game where you want it with a breakpoint and step over or into from there.

op	what it does	needs
`continue`	resume after a breakpoint	—
`step_over`	run the current line	—
`step_into`	run the current line, stopping inside whatever it calls	—

`debug_state`

Where the debugged game is stopped: the stack trace, what is in scope at a frame with the values, or the debug adapter's console output so far.

op	what it does	needs
`stack` default	the stack trace	—
`variables`	locals, members and globals at a frame, with their values	—
`output`	console output captured through the debug adapter	—

Arguments

frameId number: variables: which frame, from a stack answer. Default the innermost.