EditorPlugin Scene Tree Edits Test

plugin.gd

tool
extends EditorPlugin

# All extraneous plugin functions stripped

func _tool_gen_subdata_in_scene(args) -> void:
# this function is registered as a "tool menu item" which calls this with args=null
	var scene := get_tree().edited_scene_root
	var audio_nodes := _recurse_get_audio_nodes(scene)

  for audio in audio_nodes:
		var add_data := true
		for c in audio.get_children():
			if c is SubtitleData:
				add_data = false
		if add_data:
			var sub_data := Node.new() # just testing with Node, will use custom type once this works
			audio.add_child(sub_data)
		else:
			print(">\tSubtitle data detected on scene node : %s" %  str(scene.get_path_to(audio)))

func _recurse_get_audio_nodes(root : Node, existing_array : Array = []) -> Array:
	for c in root.get_children():
		# technically this will skip the root node if it is an audio node, however, that is so incredibly unlikely for a scene.
		if _is_audio_node(c):
			existing_array.append(c)
		_recurse_get_audio_nodes(c, existing_array)
	return existing_array

func _is_audio_node(node : Node) -> bool:
	if node is AudioStreamPlayer:
		return true
	if node is AudioStreamPlayer2D:
		return true
	if node is AudioStreamPlayer3D:
		return true
	return false

Image of testing scene tree;

Text Version:
Spatial (root)
|-> AudioStreamPlayer

RESOLVED

leaving this gist here so the solution can be found by anyone else facing similar troubles

Solution

From the Godot documentation for "Node"

Note: If you want a child to be persisted to a PackedScene, you must set owner in addition to calling add_child(). This is typically relevant for tool scripts and editor plugins. If add_child() is called without setting owner, the newly added Node will not be visible in the scene tree, though it will be visible in the 2D/3D view.

this means that on line 18 of the above script, the node is technically being added as a child, but it actually isn't entering the scene because it's an editor state. So calling sub_data.set_owner(scene) has the node actually enter the scene tree. I called this after adding it as a child. So the entire sequence looks like:

var sub_data := Node.new() # make the node
audio.add_child(sub_data) # add as child
sub_data.set_owner(scene) # enter the tree

This works perfectly