io.github.Aureliolo/gdharness

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. Operations: set: set a breakpoint; remove: remove a breakpoint.

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. Operations: continue: resume after a breakpoint; step_over: run the current line; step_into: run the current line, stopping inside whatever it calls.

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. Operations: stack: the stack trace; variables: locals, members and globals at a frame, with their values; output: console output captured through the debug adapter. Default stack.

The engine's ClassDB: find classes, read one in full, or walk an inheritance tree. Operations: query: classes matching a filter or category; info (needs className): methods, properties, signals and enums of one class; inheritance (needs className): ancestors and descendants of one class. Default query.

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. Opening a project is a save and so is closing one, which is the part that is not obvious from outside: the editor imports the project on open and writes project.godot back, and Godot writes only what differs from its own defaults, so a key named deliberately at its default value is dropped either way. A restart says which under settingsDropped in its own answer because it waits for the editor to return. An open cannot, since it answers as soon as the process exists and the save happens during the import minutes later, so editor_status carries that reading once the editor has connected. Nothing else will say a key went until something depends on one. Operations: open (needs projectPath): open the editor on a project; restart: restart the connected editor and wait for it. Default open.

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. A run that has quit still answers here, with running false and its exit code, until the next one starts. A run this server started also answers with transcript, the file both its streams are written to: uncapped, written while the run is going, and the thing to read or tail for a long run rather than the engine's own log, which every engine start rotates away. Read the file for output and this answer for state: running is asked of the operating system, endedBy says whether gdharness ended the run, and a transcript that has stopped growing is a run between prints rather than a run that is over.

Makes the running editor scan the project filesystem, so files written outside it are picked up. The scan is a change-detecting walk rather than an unconditional reparse, so a file another engine has already imported reads as settled and the walk does not look inside it: its class_name then stays out of the list the editor resolves against, however many times you scan. Any class in that state is named under unseenByEditor, which is what no check on disk can see, since the declaration and the cache are both correct there and only the editor disagrees. The cure is this call on its own, with no change to the declaring script: measured against a real editor on three platforms, with idle waits of the same length ruled out so the scan is credited rather than the time it takes, and reproduced in a second project against its own reproduction in 203ms. editor_launch restart also does it and costs a window, and project_import refresh_classes does not: it rewrites the cache and does not touch what the editor is holding. A scan writes .godot/global_script_class_cache.cfg from the list the editor is holding, so a class the editor cannot resolve goes out of that file with it. That is not a reason to refuse the scan, because on a class the editor has merely not walked yet the scan is the cure; what the answer does instead is name the loss under cacheLost and rebuild the cache from the files, naming what came back under cacheRestored, so no fresh engine, CI run or clone inherits the short file. An editor that lost classes is still holding the short list, so the note says to restart it before scanning again. Needs the editor connected.

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 it quits or is stopped, windowed where there is a display and headless where there is not, unless headless says otherwise; only runtime_capture needs the window. A run that quits on its own is kept, so a scene that prints an answer and quits is start, then editor_output until running is false. What runs is a scene: a SceneTree script is not an entry point here, so put the script on the root of a scene of its own and name that in scene. args hands the game its own flags, the ones it reads with OS.get_cmdline_user_args(), and a run carrying any is started by this server rather than by the editor. 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. A start waits for the game to become something the runtime_* tools can talk to and says which it is under runtime: listening with the port it took, or why not, so the first call after a start does not have to be made twice. When it is not listening, mayYetAnnounce says whether that is final: false is a runtime that is not coming, true is a game still on its way up, which editor_status will see and runtimeWaitMs waits longer for. A start this server made also answers with transcript, the file both the run's streams are written to, so a watch on it can be armed off the start rather than off a second call. Operations: start (needs projectPath): run the project until it quits or is stopped; stop: end the run and answer with what it printed last, naming the process ended under endedPid: a game that started processes of its own keeps them; check (needs projectPath): boot headless, quit after a few frames, and report the verdict; wait: wait for the run to end, then answer as editor_output does. Default start.

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. When connected is false, mayYetConnect says whether that is final: the editor dials this server rather than the other way round and backs off between tries, so for the first half-minute after a server starts, false means "not reached yet" as often as it means "no editor". True is worth waiting out; false is an editor that is not there. listeningSince is when this server took the bridge port, which is what that window is measured from and what a caller wanting its own window should read. An editor this server opened counts for as long as its process lives, however far past that window the import runs, and awaitingLaunchedEditor names its pid so the two reasons for true are told apart. settingsDropped appears here once when the editor this server opened saved project.godot on its way in, which is the same reading editor_launch restart makes in its own answer.

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

Export presets and exports. Operations: list: the presets in export_presets.cfg; run (needs preset, outputPath): export with a preset.

The import pipeline: what needs importing, how a resource is imported, reimports, UIDs, and the global class list the editor and the engine read. Operations: status: which resources are outdated or failed, or one resource with resourcePath; options (needs resourcePath): the import options of one resource; set_options (needs resourcePath, options): change import options; reimport: reimport one resource, or everything modified without resourcePath; uid (needs resourcePath): the UID of one file; refresh_uids: import the project so every script and shader has its .uid sidecar, and name under uidsCreated the ones this made and under stillWithoutUid the ones the engine would not import: it writes no scene and no script, so a project whose sidecars are all present is left untouched; refresh_classes: rewrite .godot/global_script_class_cache.cfg from the class_name declarations on disk, and name under unseenByEditor any class the editor open on this project still cannot resolve: rewriting the file does not reach the list a running editor loaded, so "added: []" means the file was already right rather than that nothing is wrong.

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.

Searches text or a regular expression across project files and returns file paths with line numbers. What the engine steps over is not searched: directories spelled with a dot, node_modules, and any directory holding a .gdignore. A vendored engine or an export directory is therefore absent from the results rather than matching the code you are looking for in a copy nobody runs.

Reads or writes project.godot: settings, autoloads, the main scene, input actions, plugins and audio buses. Operations: get: read one setting, or every setting under prefix; set (needs setting, value): write one setting; add_autoload (needs name, path): register an autoload singleton; remove_autoload (needs name): unregister an autoload; set_main_scene (needs scenePath): choose the scene the game starts in; add_input_action (needs actionName, events): register an input action and its events; enable_plugin (needs pluginName): enable an addon; disable_plugin (needs pluginName): disable an addon; add_audio_bus (needs busName): add an audio bus; set_audio_bus_effect (needs busIndex, effectIndex, effectType): add or configure an effect on a bus; set_audio_bus_volume (needs busIndex, volumeDb): set a bus volume.

Runs the project's gdUnit4 tests headless and answers with every case that did not pass: where it is, and what the assertion said. Suites where everything passed are counted rather than listed, and an engine message keeps the frames above gdUnit4 rather than the twenty inside it, so a clean tier answers in a few lines. 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. A run that found nothing to run is never called a pass: gdUnit4 exits cleanly for one, so the answer says so and names the path it looked in. A run where nothing failed but nodes were left in the tree comes back under warnings, with the count per suite: gdUnit4 decides its verdict on those and keeps them out of its report, so they are read off what it printed. Needs gdUnit4 under addons/gdUnit4.

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. Operations: create (needs resourceType): a new resource of any class; modify (needs properties): set properties on an existing resource; create_shader (needs shaderType): a .gdshader file; create_tileset (needs sources): a TileSet from texture atlases; set_theme_color (needs controlType, colorName, color): a colour in a Theme; set_theme_font_size (needs controlType, fontSizeName, size): a font size in a Theme.

A picture of the running game: the whole screen or one viewport, as an image. Needs the game running with a window. Operations: screenshot: the screen; viewport: one viewport's texture. Default screenshot.

Input to the running game: a whole click on a Control or a 3D node named by path, an item chosen out of a menu, typing into whatever has the focus, 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. Operations: click (needs nodePath): 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. A control out of sight inside a ScrollContainer is scrolled to first, and scrolled_into_view says whether the view moved. A 3D node is clicked where it is drawn, and landed then says the interface did not swallow the press; choose (needs nodePath): take an item out of a menu, by what it says or by where it is in the list. A menu's items are drawn rather than built, so there is nothing to click: the item takes the focus and Enter presses it, which is the engine's own path and needs no window. Answers with what was chosen and what the button in front of it shows now; action (needs action): press an action, or hold it; key (needs keycode): press a key, or hold it; text (needs text): type a string into the field being edited, a character at a time, and say what it landed in; mouse_click (needs x, y): one mouse button event at a position; mouse_motion (needs x, y): move the mouse to a position.

Questions about the running game: what is written on the screen, 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. Operations: tree: the live scene tree; text: every line of text under nodePath, the values in its fields included, in the order somebody reads the screen, leaving out what is hidden and everything under it; find: the paths of every node matching className, script, namePattern, group or says, with property read off each, hidden ones included unless includeHidden says otherwise; rect (needs nodePath): one node's rectangle or position, in canvas and in window pixels. A 3D node answers with the point to aim at, which is the middle of what it draws rather than the origin it stands on, the rectangle it covers under covers, the camera that drew it, and behind_camera when it is not in front of one; property (needs nodePath, property): what one property reads on a node, or through the objects it holds, refusing a name nothing along the way has; metrics: frame time, memory, draw calls and the rest. Default tree.

Sets a property or calls a method on a node in the running game. Needs the game running with the runtime addon. Operations: set (needs property, value): set a property, on a node or on an object it holds; call (needs method): call a method, on a node or on an object it holds, and return its result.

Lets the running game get on with it and answers when something has happened: a number of frames, a signal, a property reaching a value, or words appearing on a screen. Needs the game running with the runtime addon. Operations: frames (needs frames): let frames pass; signal (needs nodePath, signal): wait for a signal and answer with what it carried; until (needs nodePath): wait for a property to read as a value, or for words to appear under a node, and answer with what it found.

Animations in an AnimationPlayer and states in an AnimationTree state machine. Needs the editor connected. Operations: create (needs playerNodePath, animationName): a new animation in an AnimationPlayer; add_track (needs playerNodePath, animationName, track): a property or method track with keyframes; add_state (needs animTreePath, stateName, animationName): a state playing an animation, in an AnimationTree; connect_states (needs animTreePath, fromState, toState): a transition between two states.

Creates a scene file, saves one, or saves a copy under a new path. Needs the editor connected. Operations: create: a new scene with one root node; save: save the scene as it is in the editor; save_as (needs newPath): save a copy under newPath. Default create.

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. Operations: add (needs nodeType, nodeName): add a node of any class; get (needs nodePath): read a node's properties; set (needs nodePath, properties): set properties on a node; duplicate (needs nodePath, newName): copy a node and its children; reparent (needs nodePath, newParentPath): move a node under another parent; delete (needs nodePath): remove a node and its children; set_tilemap_cells (needs nodePath, cells): place tiles in a TileMap.

Signal connections in a scene file. Needs the editor connected. Operations: connect (needs sourceNodePath, signalName, targetNodePath, methodName): connect a signal to a method; disconnect (needs sourceNodePath, signalName, targetNodePath, methodName): remove a connection; list: every connection in the scene.

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

Errors and warnings for a script from the editor's language server, and whether the script is clean. Needs the editor running. Diagnostics are checked against the project's own files, and the two that the files disprove are named rather than passed on: a member the class cache's file declares comes back under contradictedByTheFile, and a class this project declares that the diagnostic could not resolve comes back under typesTheEditorHasNotLoaded, with inTheClassCache saying whether a launched game would resolve it. staleAnalysis then says which remedy applies, because they differ: a stale analysed type needs editor_launch restart, while a class missing from the cache needs project_import refresh_classes.

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. Operations: create: a new script file; modify (needs modifications): add to an existing script.

What a script contains: its structure from the file, or symbols, completions and hover text from the editor's language server. Operations: structure: functions, variables, signals, class_name and extends, read from the file; symbols: document symbols from the language server; completion (needs line, character): completions at a position; hover (needs line, character): hover text at a position. Default structure.