gdharness 0.4.1

package/build/godot/addons/gdharness_runtime/runtime_queries.gd

@@ -0,0 +1,283 @@
+extends RefCounted
+
+## What the server asks about the running tree: its shape, one node, the nodes matching a
+## question, where one is on screen, a property set, a method called, the metrics.
+
+const Values = preload("runtime_values.gd")
+
+## The most nodes one find answers with, unless asked for fewer: enough for any real query and
+## far short of the tree dump a query exists to avoid.
+const FIND_LIMIT: int = 100
+const FIND_LIMIT_CEILING: int = 1000
+
+var _host: Node
+var _values: Values
+
+
+## The host is the autoload, which is how the tree is reached: it is not in one when the
+## modules are built, and a fixture may put it in one later.
+func _init(host: Node, values: Values) -> void:
+	_host = host
+	_values = values
+
+
+func get_tree(params: Dictionary) -> Dictionary:
+	var root_path: String = str(params.get("root", "/root"))
+	var max_depth: int = int(params.get("depth", 3))
+	var include_properties: bool = bool(params.get("include_properties", false))
+
+	var root: Node = _host.get_tree().root.get_node_or_null(root_path)
+	if root == null:
+		return {"type": "error", "message": "Node not found: " + root_path}
+
+	return {"type": "tree", "root": _serialize_node_tree(root, 0, max_depth, include_properties)}
+
+
+## Nodes matching every filter given, as paths, so a caller can name what it wants without
+## reading the whole tree to find it. `class` matches native classes and their subclasses, and
+## the global name of a script class; `name` is a case-insensitive glob; `script` is a path.
+func find_nodes(params: Dictionary) -> Dictionary:
+	var root_path: String = str(params.get("root", "/root"))
+	var wanted_class: String = str(params.get("class", ""))
+	var wanted_script: String = str(params.get("script", ""))
+	var wanted_name: String = str(params.get("name", ""))
+	var wanted_group: String = str(params.get("group", ""))
+	var limit: int = clampi(int(params.get("limit", FIND_LIMIT)), 1, FIND_LIMIT_CEILING)
+
+	if (
+		wanted_class.is_empty()
+		and wanted_script.is_empty()
+		and wanted_name.is_empty()
+		and wanted_group.is_empty()
+	):
+		return {"type": "error", "message": "find_nodes needs at least one of class, script, name, group"}
+	if not wanted_script.is_empty() and not wanted_script.begins_with("res://"):
+		wanted_script = "res://" + wanted_script
+
+	var root: Node = _host.get_tree().root.get_node_or_null(root_path)
+	if root == null:
+		return {"type": "error", "message": "Node not found: " + root_path}
+
+	var found: Array[Dictionary] = []
+	var pending: Array[Node] = [root]
+	var truncated: bool = false
+	while not pending.is_empty():
+		var node: Node = pending.pop_front()
+		if _matches(node, wanted_class, wanted_script, wanted_name, wanted_group):
+			if found.size() >= limit:
+				truncated = true
+				break
+			found.append(_serialize_node(node, false))
+		var children: Array[Node] = node.get_children()
+		for index: int in range(children.size() - 1, -1, -1):
+			pending.push_front(children[index])
+
+	return {"type": "nodes", "count": found.size(), "truncated": truncated, "nodes": found}
+
+
+func _matches(
+	node: Node, wanted_class: String, wanted_script: String, wanted_name: String, wanted_group: String
+) -> bool:
+	if not wanted_group.is_empty() and not node.is_in_group(wanted_group):
+		return false
+	if not wanted_name.is_empty() and not str(node.name).matchn(wanted_name):
+		return false
+	var script: Variant = node.get_script()
+	if not wanted_script.is_empty():
+		if not script is Script:
+			return false
+		var attached: Script = script
+		if attached.resource_path != wanted_script:
+			return false
+	if not wanted_class.is_empty() and not node.is_class(wanted_class):
+		if not script is Script:
+			return false
+		var attached: Script = script
+		if attached.get_global_name() != wanted_class:
+			return false
+	return true
+
+
+## Where a node is on screen: a Control's rectangle, or a Node2D's position, in both the
+## canvas coordinates the node reports and the window pixels input arrives in. The two differ
+## whenever the project stretches its viewport, which is what made a rect unusable for a click.
+func get_rect(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	if node_path.is_empty():
+		return {"type": "error", "message": "Node path required"}
+
+	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
+	if node == null:
+		return {"type": "error", "message": "Node not found: " + node_path}
+
+	if node is Control:
+		var control: Control = node
+		var to_window: Transform2D = control.get_viewport().get_final_transform()
+		var canvas_rect: Rect2 = control.get_global_rect()
+		return {
+			"type": "rect",
+			"path": node_path,
+			"visible": control.is_visible_in_tree(),
+			"canvas": _values.serialize(canvas_rect),
+			"window": _values.serialize(to_window * canvas_rect),
+		}
+	if node is Node2D:
+		var item: Node2D = node
+		var canvas_position: Vector2 = item.get_global_transform_with_canvas().origin
+		var window_position: Vector2 = item.get_viewport().get_final_transform() * canvas_position
+		return {
+			"type": "point",
+			"path": node_path,
+			"visible": item.is_visible_in_tree(),
+			"canvas": _values.serialize(canvas_position),
+			"window": _values.serialize(window_position),
+		}
+	return {
+		"type": "error", "message": "%s is a %s, which has no place on screen" % [node_path, node.get_class()]
+	}
+
+
+func get_property(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	var property: String = str(params.get("property", ""))
+
+	if node_path.is_empty() or property.is_empty():
+		return {"type": "error", "message": "Node path and property required"}
+
+	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
+	if node == null:
+		return {"type": "error", "message": "Node not found: " + node_path}
+
+	# Asked of the property list rather than read and compared to null, because a property the
+	# node does not have and a property that is null both read as null.
+	var known: bool = false
+	for entry: Dictionary in node.get_property_list():
+		if str(entry["name"]) == property:
+			known = true
+			break
+	if not known:
+		return {"type": "error", "message": "%s has no property %s" % [node_path, property]}
+
+	return {
+		"type": "property",
+		"path": node_path,
+		"property": property,
+		"value": _values.serialize(node.get(property)),
+	}
+
+
+func set_property(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	var property: String = str(params.get("property", ""))
+	var value: Variant = params.get("value")
+
+	if node_path.is_empty() or property.is_empty():
+		return {"type": "error", "message": "Node path and property required"}
+
+	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
+	if node == null:
+		return {"type": "error", "message": "Node not found: " + node_path}
+
+	var old_value: Variant = node.get(property)
+	node.set(property, _values.fitted(value, typeof(old_value)))
+
+	return {
+		"type": "property_set",
+		"path": node_path,
+		"property": property,
+		"old_value": _values.serialize(old_value),
+		"new_value": _values.serialize(node.get(property))
+	}
+
+
+func call_method(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	var method: String = str(params.get("method", ""))
+	var args: Array = params.get("args", [])
+
+	if node_path.is_empty() or method.is_empty():
+		return {"type": "error", "message": "Node path and method required"}
+
+	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
+	if node == null:
+		return {"type": "error", "message": "Node not found: " + node_path}
+
+	if not node.has_method(method):
+		return {"type": "error", "message": "Method not found: " + method}
+
+	var deserialized_args: Array = []
+	for index: int in args.size():
+		deserialized_args.append(_values.fitted(args[index], _values.parameter_type(node, method, index)))
+
+	var result: Variant = node.callv(method, deserialized_args)
+
+	return {"type": "method_result", "path": node_path, "method": method, "result": _values.serialize(result)}
+
+
+func get_metrics(params: Dictionary) -> Dictionary:
+	var metrics: Array = params.get("metrics", [])
+	var all: Dictionary = {
+		"fps": Engine.get_frames_per_second(),
+		"frame_time": Performance.get_monitor(Performance.TIME_PROCESS),
+		"physics_time": Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS),
+		"memory_static": Performance.get_monitor(Performance.MEMORY_STATIC),
+		"memory_static_max": Performance.get_monitor(Performance.MEMORY_STATIC_MAX),
+		"object_count": Performance.get_monitor(Performance.OBJECT_COUNT),
+		"object_resource_count": Performance.get_monitor(Performance.OBJECT_RESOURCE_COUNT),
+		"object_node_count": Performance.get_monitor(Performance.OBJECT_NODE_COUNT),
+		"object_orphan_node_count": Performance.get_monitor(Performance.OBJECT_ORPHAN_NODE_COUNT),
+		"render_total_objects": Performance.get_monitor(Performance.RENDER_TOTAL_OBJECTS_IN_FRAME),
+		"render_total_primitives": Performance.get_monitor(Performance.RENDER_TOTAL_PRIMITIVES_IN_FRAME),
+		"render_total_draw_calls": Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME),
+	}
+
+	if metrics.is_empty():
+		return {"type": "metrics", "data": all}
+
+	# A caller that names metrics gets those and no others, and hears about a name that is
+	# not one rather than getting everything back as if the list had not been sent.
+	var unknown: Array[String] = []
+	var selected: Dictionary = {}
+	for metric: Variant in metrics:
+		if all.has(metric):
+			selected[metric] = all[metric]
+		else:
+			unknown.append(str(metric))
+	if not unknown.is_empty():
+		return {
+			"type": "error",
+			"message": "Unknown metrics: %s. Available: %s" % [", ".join(unknown), ", ".join(all.keys())]
+		}
+	return {"type": "metrics", "data": selected}
+
+
+func _serialize_node_tree(node: Node, depth: int, max_depth: int, include_properties: bool) -> Dictionary:
+	var result: Dictionary = _serialize_node(node, include_properties)
+
+	if depth < max_depth:
+		var children: Array = []
+		for child: Node in node.get_children():
+			children.append(_serialize_node_tree(child, depth + 1, max_depth, include_properties))
+		result["children"] = children
+
+	return result
+
+
+func _serialize_node(node: Node, include_properties: bool) -> Dictionary:
+	var result: Dictionary = {"name": node.name, "type": node.get_class(), "path": str(node.get_path())}
+
+	var script: Variant = node.get_script()
+	if script is Script:
+		var attached: Script = script
+		result["script"] = attached.resource_path
+
+	if include_properties:
+		var properties: Dictionary = {}
+		for prop: Dictionary in node.get_property_list():
+			if prop["usage"] & PROPERTY_USAGE_STORAGE:
+				var property_name: String = prop["name"]
+				if not property_name.begins_with("_"):
+					properties[property_name] = _values.serialize(node.get(property_name))
+		result["properties"] = properties
+
+	return result

package/build/godot/addons/gdharness_runtime/runtime_values.gd

@@ -0,0 +1,169 @@
+extends RefCounted
+
+## What crosses the wire between the game and the server, in both directions: Godot values
+## as JSON-safe dictionaries, and JSON back into the values a property or parameter wants.
+
+# What each Godot type becomes on the wire, keyed on typeof() rather than written as a chain of
+# `is` tests whose order has to be trusted: Resource had to be tested before Object, or every
+# resource came back as a bare class name with its path dropped.
+#
+# Method names rather than Callables or lambdas: a lambda spanning more than one line inside a
+# dictionary literal is where gdformat loses track of every comment in the file and writes them
+# all again into the lambda body, on every run.
+const SERIALISERS: Dictionary = {
+	TYPE_NIL: "_serialize_nil",
+	TYPE_VECTOR2: "_serialize_vector2",
+	TYPE_VECTOR3: "_serialize_vector3",
+	TYPE_VECTOR2I: "_serialize_vector2i",
+	TYPE_VECTOR3I: "_serialize_vector3i",
+	TYPE_COLOR: "_serialize_color",
+	TYPE_NODE_PATH: "_serialize_node_path",
+	TYPE_ARRAY: "_serialize_array",
+	TYPE_RECT2: "_serialize_rect2",
+	TYPE_TRANSFORM2D: "_serialize_transform2d",
+	TYPE_DICTIONARY: "_serialize_dictionary",
+	TYPE_OBJECT: "_serialize_object",
+}
+
+
+## Converts a Godot value into something JSON can carry. A type with no entry in the table
+## passes through as itself, which is what the JSON-native ones want.
+func serialize(value: Variant) -> Variant:
+	var serialiser: String = SERIALISERS.get(typeof(value), "")
+	return call(serialiser, value) if not serialiser.is_empty() else value
+
+
+func _serialize_nil(_value: Variant) -> Variant:
+	return null
+
+
+func _serialize_vector2(value: Vector2) -> Dictionary:
+	return {"_type": "Vector2", "x": value.x, "y": value.y}
+
+
+func _serialize_vector3(value: Vector3) -> Dictionary:
+	return {"_type": "Vector3", "x": value.x, "y": value.y, "z": value.z}
+
+
+func _serialize_vector2i(value: Vector2i) -> Dictionary:
+	return {"_type": "Vector2i", "x": value.x, "y": value.y}
+
+
+func _serialize_vector3i(value: Vector3i) -> Dictionary:
+	return {"_type": "Vector3i", "x": value.x, "y": value.y, "z": value.z}
+
+
+func _serialize_color(value: Color) -> Dictionary:
+	return {"_type": "Color", "r": value.r, "g": value.g, "b": value.b, "a": value.a}
+
+
+func _serialize_node_path(value: NodePath) -> Dictionary:
+	return {"_type": "NodePath", "path": str(value)}
+
+
+func _serialize_array(value: Array) -> Array:
+	return value.map(serialize)
+
+
+func _serialize_rect2(value: Rect2) -> Dictionary:
+	return {"_type": "Rect2", "position": serialize(value.position), "size": serialize(value.size)}
+
+
+func _serialize_transform2d(value: Transform2D) -> Dictionary:
+	return {
+		"_type": "Transform2D",
+		"origin": serialize(value.origin),
+		"x": serialize(value.x),
+		"y": serialize(value.y)
+	}
+
+
+func _serialize_dictionary(value: Dictionary) -> Dictionary:
+	var serialised: Dictionary = {}
+	for key: Variant in value:
+		serialised[str(key)] = serialize(value[key])
+	return serialised
+
+
+## The one case that genuinely needs the class hierarchy, since a Resource is also an Object and
+## its path is the half worth having. A node in the tree is answered with its path, so a
+## property that points at one can be fed straight back to any tool that takes a node.
+func _serialize_object(value: Object) -> Dictionary:
+	if value is Resource:
+		var resource: Resource = value
+		return {"_type": "Resource", "path": resource.resource_path, "class": resource.get_class()}
+	if value is Node:
+		var node: Node = value
+		if node.is_inside_tree():
+			return {"_type": "Node", "class": node.get_class(), "path": str(node.get_path())}
+	return {"_type": "Object", "class": value.get_class()}
+
+
+## Rebuilds a Godot value from the shape serialize gave it.
+func deserialize(value: Variant) -> Variant:
+	if value == null:
+		return null
+	if value is Array:
+		var items: Array = value
+		var rebuilt: Array = []
+		for item: Variant in items:
+			rebuilt.append(deserialize(item))
+		return rebuilt
+	if not value is Dictionary:
+		return value
+
+	var fields: Dictionary = value
+	if not fields.has("_type"):
+		var rebuilt: Dictionary = {}
+		for key: Variant in fields:
+			rebuilt[key] = deserialize(fields[key])
+		return rebuilt
+
+	match fields["_type"]:
+		"Vector2":
+			return Vector2(fields.get("x", 0), fields.get("y", 0))
+		"Vector3":
+			return Vector3(fields.get("x", 0), fields.get("y", 0), fields.get("z", 0))
+		"Vector2i":
+			return Vector2i(fields.get("x", 0), fields.get("y", 0))
+		"Vector3i":
+			return Vector3i(fields.get("x", 0), fields.get("y", 0), fields.get("z", 0))
+		"Color":
+			return Color(fields.get("r", 0), fields.get("g", 0), fields.get("b", 0), fields.get("a", 1))
+		"NodePath":
+			return NodePath(fields.get("path", ""))
+	return value
+
+
+## The declared type of one parameter of a method, or TYPE_NIL when the method or the parameter
+## is not there, which reads as "no opinion".
+func parameter_type(object: Object, method: String, index: int) -> int:
+	for entry: Dictionary in object.get_method_list():
+		if entry.get("name", "") != method:
+			continue
+		var params: Array = entry.get("args", [])
+		if index < 0 or index >= params.size():
+			return TYPE_NIL
+		var parameter: Dictionary = params[index]
+		return int(parameter.get("type", TYPE_NIL))
+	return TYPE_NIL
+
+
+## A value from the wire fitted to the type a property or parameter declares. Arguments arrive
+## as strings often enough, and callv refuses a "2.0" where a float is wanted, so a string that
+## reads as the wanted scalar is read as one.
+func fitted(value: Variant, type: int) -> Variant:
+	var rebuilt: Variant = deserialize(value)
+	if type == TYPE_NIL or typeof(rebuilt) == type:
+		return rebuilt
+
+	var simple: Array[int] = [TYPE_BOOL, TYPE_INT, TYPE_FLOAT, TYPE_STRING]
+	if not simple.has(type) or not simple.has(typeof(rebuilt)):
+		return rebuilt
+
+	if rebuilt is String and type != TYPE_STRING:
+		var parsed: Variant = JSON.parse_string(rebuilt)
+		if typeof(parsed) != TYPE_NIL and typeof(parsed) != TYPE_STRING:
+			rebuilt = parsed
+
+	return type_convert(rebuilt, type)

package/build/godot/addons/gdharness_runtime/runtime_waits.gd

@@ -0,0 +1,119 @@
+extends RefCounted
+
+## The commands that take time: they let the game run and answer when what was waited for has
+## happened, or when the time ran out, so the caller never sleeps for a guessed length.
+
+const Values = preload("runtime_values.gd")
+
+## The longest one wait may last, whatever the request says: past this the server has long
+## since given up on the reply.
+const CEILING_MSEC: int = 120000
+
+var _host: Node
+var _values: Values
+
+
+func _init(host: Node, values: Values) -> void:
+	_host = host
+	_values = values
+
+
+func wait_frames(params: Dictionary) -> Dictionary:
+	var frames: int = clampi(int(params.get("frames", 1)), 1, 600)
+	var started: int = Time.get_ticks_msec()
+	for _frame: int in frames:
+		await _host.get_tree().process_frame
+	return {"type": "waited", "frames": frames, "elapsed_ms": Time.get_ticks_msec() - started}
+
+
+## Waits for a signal to fire, and answers with what it carried, or that the time ran out.
+func wait_signal(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	var signal_name: String = str(params.get("signal", ""))
+	var timeout_ms: int = clampi(int(params.get("timeout_ms", 5000)), 1, CEILING_MSEC)
+	if node_path.is_empty() or signal_name.is_empty():
+		return {"type": "error", "message": "Node path and signal name required"}
+
+	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
+	if node == null:
+		return {"type": "error", "message": "Node not found: " + node_path}
+	if not node.has_signal(signal_name):
+		return {"type": "error", "message": "%s has no signal %s" % [node_path, signal_name]}
+
+	var catcher: SignalCatcher = SignalCatcher.new()
+	catcher.arity = _signal_arity(node, signal_name)
+	var callable: Callable = catcher._on_fired
+	node.connect(signal_name, callable, CONNECT_ONE_SHOT)
+	var started: int = Time.get_ticks_msec()
+	while not catcher.fired and Time.get_ticks_msec() - started < timeout_ms:
+		await _host.get_tree().process_frame
+	if not catcher.fired and is_instance_valid(node) and node.is_connected(signal_name, callable):
+		node.disconnect(signal_name, callable)
+
+	return {
+		"type": "signal",
+		"path": node_path,
+		"signal": signal_name,
+		"fired": catcher.fired,
+		"args": _values.serialize(catcher.args),
+		"elapsed_ms": Time.get_ticks_msec() - started,
+	}
+
+
+## Waits until a property reads as the value given, or the time runs out, and answers with
+## what it read last either way.
+func wait_until(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	var property: String = str(params.get("property", ""))
+	var timeout_ms: int = clampi(int(params.get("timeout_ms", 5000)), 1, CEILING_MSEC)
+	if node_path.is_empty() or property.is_empty():
+		return {"type": "error", "message": "Node path and property required"}
+	if not params.has("value"):
+		return {"type": "error", "message": "A value to wait for is required"}
+
+	var node: Node = _host.get_tree().root.get_node_or_null(node_path)
+	if node == null:
+		return {"type": "error", "message": "Node not found: " + node_path}
+
+	var current: Variant = node.get(property)
+	var wanted: Variant = _values.fitted(params["value"], typeof(current))
+	var started: int = Time.get_ticks_msec()
+	while current != wanted and Time.get_ticks_msec() - started < timeout_ms:
+		await _host.get_tree().process_frame
+		if not is_instance_valid(node):
+			return {"type": "error", "message": "%s was freed while waiting" % node_path}
+		current = node.get(property)
+
+	return {
+		"type": "condition",
+		"path": node_path,
+		"property": property,
+		"met": current == wanted,
+		"value": _values.serialize(current),
+		"elapsed_ms": Time.get_ticks_msec() - started,
+	}
+
+
+func _signal_arity(node: Node, signal_name: String) -> int:
+	for entry: Dictionary in node.get_signal_list():
+		if entry.get("name", "") == signal_name:
+			var declared: Array = entry.get("args", [])
+			return declared.size()
+	return 0
+
+
+## Remembers that a signal fired and what it carried, for a wait that polls rather than
+## awaits the signal directly, so the wait can also give up. The handler accepts up to five
+## arguments, which covers every signal the engine declares, and records as many as the signal
+## has.
+class SignalCatcher:
+	extends RefCounted
+	var fired: bool = false
+	var arity: int = 0
+	var args: Array = []
+
+	func _on_fired(
+		a: Variant = null, b: Variant = null, c: Variant = null, d: Variant = null, e: Variant = null
+	) -> void:
+		fired = true
+		args = [a, b, c, d, e].slice(0, mini(arity, 5))

package/build/godot/operations/audio_buses.gd

@@ -0,0 +1,125 @@
+extends RefCounted
+
+# The bus layout is a project resource the engine loads at startup and this process holds in
+# memory, so every change is written back to that file or it is gone with the process.
+
+const Log = preload("logger.gd")
+
+var _log: Log
+
+
+func _init(p_log: Log) -> void:
+	_log = p_log
+
+
+func create_audio_bus(params: Dictionary) -> Dictionary:
+	var bus_name: String = str(params.get("bus_name", ""))
+	if bus_name.is_empty():
+		return _log.failure("bus_name is required")
+	var parent_idx: int = int(params.get("parent_bus_index", 0))
+	if parent_idx < 0 or parent_idx >= AudioServer.bus_count:
+		return _log.failure("No bus at index " + str(parent_idx))
+
+	AudioServer.add_bus(parent_idx + 1)
+	var new_idx: int = AudioServer.bus_count - 1
+	AudioServer.set_bus_name(new_idx, bus_name)
+	if parent_idx > 0:
+		AudioServer.set_bus_send(new_idx, AudioServer.get_bus_name(parent_idx))
+
+	var layout: String = _save_layout()
+	if layout.is_empty():
+		return {}
+	return {"bus": _bus(new_idx), "layout": layout}
+
+
+func get_audio_buses(_params: Dictionary) -> Dictionary:
+	var buses: Array[Dictionary] = []
+	for i: int in range(AudioServer.bus_count):
+		buses.append(_bus(i))
+	return {"bus_count": AudioServer.bus_count, "buses": buses, "layout": _layout_path()}
+
+
+func set_audio_bus_effect(params: Dictionary) -> Dictionary:
+	var bus_idx: int = int(params.get("bus_index", 0))
+	var effect_idx: int = int(params.get("effect_index", 0))
+	var effect_type: String = str(params.get("effect_type", ""))
+	var enabled: bool = bool(params.get("enabled", true))
+	if bus_idx < 0 or bus_idx >= AudioServer.bus_count:
+		return _log.failure("No bus at index " + str(bus_idx))
+
+	var effect: AudioEffect = _effect_named(effect_type)
+	if effect == null:
+		return _log.failure("Unknown effect type: " + effect_type)
+
+	# The slot has to exist before an effect can be placed at that index.
+	while AudioServer.get_bus_effect_count(bus_idx) <= effect_idx:
+		AudioServer.add_bus_effect(bus_idx, AudioEffectAmplify.new())
+
+	AudioServer.add_bus_effect(bus_idx, effect, effect_idx)
+	AudioServer.set_bus_effect_enabled(bus_idx, effect_idx, enabled)
+
+	var layout: String = _save_layout()
+	if layout.is_empty():
+		return {}
+	return {"bus": _bus(bus_idx), "effect_index": effect_idx, "effect_type": effect_type, "layout": layout}
+
+
+func set_audio_bus_volume(params: Dictionary) -> Dictionary:
+	var bus_idx: int = int(params.get("bus_index", 0))
+	var volume_db: float = float(params.get("volume_db", 0.0))
+	if bus_idx < 0 or bus_idx >= AudioServer.bus_count:
+		return _log.failure("No bus at index " + str(bus_idx))
+
+	AudioServer.set_bus_volume_db(bus_idx, volume_db)
+
+	var layout: String = _save_layout()
+	if layout.is_empty():
+		return {}
+	return {"bus": _bus(bus_idx), "layout": layout}
+
+
+func _bus(index: int) -> Dictionary:
+	var effects: Array[Dictionary] = []
+	for e: int in range(AudioServer.get_bus_effect_count(index)):
+		var effect: Dictionary = {
+			"index": e,
+			"type": AudioServer.get_bus_effect(index, e).get_class(),
+			"enabled": AudioServer.is_bus_effect_enabled(index, e),
+		}
+		effects.append(effect)
+	return {
+		"index": index,
+		"name": AudioServer.get_bus_name(index),
+		"volume_db": AudioServer.get_bus_volume_db(index),
+		"mute": AudioServer.is_bus_mute(index),
+		"solo": AudioServer.is_bus_solo(index),
+		"send": AudioServer.get_bus_send(index),
+		"effects": effects,
+	}
+
+
+func _layout_path() -> String:
+	return str(ProjectSettings.get_setting("audio/buses/default_bus_layout", "res://default_bus_layout.tres"))
+
+
+# The path the layout was written to, or empty with the reason on stderr.
+func _save_layout() -> String:
+	var path: String = _layout_path()
+	var err: Error = ResourceSaver.save(AudioServer.generate_bus_layout(), path)
+	if err != OK:
+		_log.error("Failed to save the bus layout to " + path + ": " + error_string(err))
+		return ""
+	return path
+
+
+# Any effect class the engine has, by its class name or the part after "AudioEffect".
+func _effect_named(effect_type: String) -> AudioEffect:
+	var cls: String = effect_type if effect_type.begins_with("AudioEffect") else "AudioEffect" + effect_type
+	if not ClassDB.class_exists(cls) or not ClassDB.is_parent_class(cls, "AudioEffect"):
+		return null
+	if not ClassDB.can_instantiate(cls):
+		return null
+	var instance: Variant = ClassDB.instantiate(cls)
+	if instance is AudioEffect:
+		return instance
+	return null