Unique name search finds node outside the subscene if not found in the subscene

[Klaim]

Tested versions

Tested with Godot 4.4.1-stable, on Windows only

System information

Godot v4.4.1.stable - Windows 11 (build 26100) - Multi-window, 2 monitors - Vulkan (Forward+) - dedicated NVIDIA GeForce RTX 3080 Ti (NVIDIA; 32.0.15.7270) - AMD Ryzen 9 5900X 12-Core Processor (24 threads)

Issue description

The following setup is basically what I have seen in my game project:

Note that some_object is not marked with a unique name. In the original project that was a mistake, but the bug made it very much harder to spot, because it finds a node from somewhere else and manipulates it, which lead to surprisingly obscure behaviors.

Here is a scene using that A scene as a subscene:

Note that some_object is marked with a unique name.

The script from A's node:

extends Node2D

@onready var some_object = %some_object

func _ready() -> void:
	print("some_object = ", some_object)
	if some_object:
		print("where: ", some_object.get_path())

results in:

some_object = some_object:<Node#29276243270>
where: /root/main/some_object

But we expect:

some_object = null

This behavior directly contradicts the documentation:
Both the tooltip and the documentation for unique scene names explicitly specifies that in this case the scene A being a subscene should not find a node which exists outside of it's children, same name or not.

Steps to reproduce

In a new project:

• create a main scene
• create another scene, say A.tscn
• in A scene, add a child node and name it some_object DO NOT MAKE IT UNIQUE
• add the script above to A's root node
• add A.tscn as child node of the main scene
• add a Node to the main scene with the name some_object and make it a unique scene name
• run the project

Minimal reproduction project (MRP)

test_repro_unique_name.zip

[Klaim]

I reproduced the problem the same repro project with Godot 4.5-beta1:

$ "E:\tools\godot\Godot_v4.5-beta1_win64.exe" ./
Godot Engine v4.5.beta1.official.46c495ca2 - https://godotengine.org
Vulkan 1.4.303 - Forward+ - Using Device #0: NVIDIA - NVIDIA GeForce RTX 3080 Ti

some_object = some_object:<Node#37715182959>
where: /root/main/some_object

(git-bash output, still on windows, same machine as in the first post)

[Fgico]

I was able to reproduce this behaviour on v4.5.beta.custom_build [30456ba] and the node homonymy isn't even necessary,
but I'm not sure it should be considered a bug,
however I think the documentation should be updated, the picture suggests the get_node call was actually ran inside the blade script since there is not a script attached to the sword node, and this seems to work as intended where the outer node isn't accessible, so we should fix the Text and maybe include this edge case?

[Klaim]

Note that while it could be considered an acceptable decision to keep this behavior, it is misleading for users (like me) and made me lost several hours of trying to understand what was happening with a "spooky action at a distance" kind of bug. The source of the bug was that I misnamed the node and if the behavior of the node name search was matching exactly the behavior described by the documentation, it would have been easy to find. Instead, I lost time because the node was "found" and manipulated with code that happened to call functions existing for that wrong node and made the whole thing behave weirdly.

The requirement that the search with unique name is confined withing the scene where the name is given is useful in the same way scopes are useful in programming, so I would highly prefer if this was not considered a documentation issue but a real bug, and that the issue be fixed to match the current documentation.

however I think the documentation should be updated, the picture suggests the get_node call was actually ran inside the blade script since there is not a script attached to the sword node, and this seems to work as intended where the outer node isn't accessible, so we should fix the Text and maybe include this edge case?

To me the picture is clear that the executed script is part of the Sword scene, wherever the script is, which happen have it's child nodes visible here but they are still part of that Sword scene, not the current one. So if the function is run in the script of any node in that scene it should fine unique name in that scene. To me the documentation and text are pretty clear as long as you understand that the picture shows the internals of the Sword scene (the yellow nodes) but doesnt mean it's children node are imported in the current one.

[Fgico]

The documentation looks wrong as from the engine screenshot there is no script attached to the sword node and I assume the get_node call was actually ran inside the blade script.
From my tests this was working correctly

From the script attached to the C node I wasn't able to get the B node,
the A node can reach the B node, since once instantiated the main node becomes it's "owner", thus sharing the unique name scope,

I agree that this is not the most desirable behaviour since it favours copuling between two different scenes, but it could have it's uses in some cases, like if the A node had no script attached in it's original scene and was added only in the outer scene, then it would be fine and expected to be able to reach "outer nodes".
In my opinion an update to the documentation would not break past projects and will help users find the cause of the same problem you had.
Maybe even adding a warning in the code editor which checks for the presence of a unique name in the scene where the script is defined?

[Klaim]

I understand better what you meant, thanks for the clarification.

To me it makes sense that a script on A would find B IFF that script was set from main scene. If that script is part of A's scene, I maintain that it doesn't make sense and is problematic for detecting errors in scripts in A.

When using for example node types CharacterBody3D or RigidBody3D it is highly recommended to keep them as the root node of a scene representing a physical game entity. That entity's ehavior code end up on these root nodes too, driving the child nodes. It's so common that this issue basically affects any usage of these nodes as there is often a script on the root node of physical objects.

Adding a warning would be a bit helpful but it would then pop in almost any situation such as usage of these physical nodes to represent a physical game entity. If the warning was constrained to only the case where there is actually a possibility of getting a node that is from another scene, then it means we could detect and reject that case instead, leading to a more helpful error.

I understand thar the case where A has a script set from the main scene is useful too, so I think it would be best if there was a clear distinction in search results when on unique names between the case where

• A having a script from it's own scene -> B is not found
• A script being set from the main scene -> B is found

Can this distinction be made?

[Rindbee]

godot/doc/classes/Node.xml

Lines 1086 to 1089 in e1b4101

	<member name="unique_name_in_owner" type="bool" setter="set_unique_name_in_owner" getter="is_unique_name_in_owner" default="false">
	If [code]true[/code], the node can be accessed from any node sharing the same [member owner] or from the [member owner] itself, with special [code]%Name[/code] syntax in [method get_node].
	[b]Note:[/b] If another node with the same [member owner] shares the same [member name] as this node, the other node will no longer be accessible as unique.
	</member>

the node can be accessed from

1. any node sharing the same [member owner]
2. or from the [member owner] itself

There is no error. It’s just that the sub-scene root node satisfies conditions 1 and 2 at the same time. In this case, the document does not explicitly state that condition 2 takes precedence.