Docs of `Node.duplicate` don't mention it duplicates whole Node subtree

[vinni-richburgh]

Tested versions

I am experiencing this behavior on Homebrew-Godot 4.2 and 4.3.

• I just built 4.0-stable and it too is affected.

System information

Godot v4.3.stable - macOS 14.6.1 - Vulkan (Forward+) - integrated Apple M1 - Apple M1 (8 Threads)

Issue description

In one of my projects I am using Polygon2Ds as terrain. To make them fit into the pixelart style of the game, I add a SubViewportContainer and a SubViewport (transparent_bg = true) as children to the Polygon2D via a script, make the Polygon2D duplicate itself and attach its copy to the SubViewport. (See polygon_cloner.gd!)

This messes up the view order in my scenes when I edit z_index and set show_behind_parent = true in a Polygon2D that is attached to another Polygon2D running the same script. As far as I can tell, this doesn't happen with Sprite2Ds.

Steps to reproduce

Open the MRP. Run the node_2d.tscn scene. Observe the red Polygon2D sticking through OccludingSprite2D when it shouldn't.

Minimal reproduction project (MRP)

subviewport.zip

[kleonc]

Here's the remote scene tree view when running the MRP: I suspect that's not what you wanted to generate? :upside_down_face:

---

So the obvious issue seems to be the documentation of Node.duplicate, as it doesn't mention at all that it duplicates the whole subtree. It needs to be documented in detail what/how it duplicates, when re-instantiates scenes, etc., all depending on the passed flags.

https://github.com/godotengine/godot/blob/5ca419e32c58e671284b3b7f91257179657d9114/doc/classes/Node.xml#L254-L260 Relevant source code: https://github.com/godotengine/godot/blob/5ca419e32c58e671284b3b7f91257179657d9114/scene/main/node.cpp#L2662-L2821

---

Regarding why Polygon2D shows on top but Sprite2D doesn't: seems like the resulting sprites are massively outside of the screen (and of course even more outside of the smaller viewports). But AFAICT that's according to the code in sprite_cloner.gd.

Here's some of their screen transforms (notice big origin positions (O:) and unrotated basis axes with positive scalings (X:/Y:)(thus sprites are further into the right/bottom from such origins)):

@SubViewportContainer@6:<SubViewportContainer#25853691178> screen_transform=[X: (328.9991, 0), Y: (0, 685.9996), O: (655.7994, 410.8773)]
  @SubViewport@7:<SubViewport#25887245612> screen_transform=
    Sprite2D:<Sprite2D#25937577263> screen_transform=[X: (475.782, 0), Y: (0, 1841.861), O: (886.0988, 490.7544)]

@SubViewportContainer@8:<SubViewportContainer#25987908914> screen_transform=[X: (227.5, 0), Y: (0, 255.5), O: (3849.375, 4836.375)]
  @SubViewport@9:<SubViewport#26021463348> screen_transform=
    Sprite2D:<Sprite2D#26071794999> screen_transform=[X: (7393.75, 0), Y: (0, 9325.75), O: (7432.5, 9371.5)]
      Sprite2D:<Sprite2D#26088572216> screen_transform=[X: (10692.47, 0), Y: (0, 25038.99), O: (12608.13, 10457.38)]
        _SubViewportContainer_6:<SubViewportContainer#26105349433> screen_transform=[X: (10692.47, 0), Y: (0, 25038.99), O: (20092.86, 13372.9)]
          _SubViewport_7:<SubViewport#26138903867> screen_transform=
            Sprite2D:<Sprite2D#26189235518> screen_transform=[X: (15462.92, 0), Y: (0, 67227.93), O: (27577.59, 16288.41)]

---

So I'm assuming there's no rendering issue in here, only some excessive/unexpected duplicated nodes.

@vinni-richburgh please update if there are any rendering issues after fixing the generation/duplication code.

For now I'll mark it as a documentation-only issue.

[vinni-richburgh]

Woah, thank very much you for clarifying this! Indeed, Node.duplicate works differently than I expected and I am embarrassed to admit that I never noticed the button for showing the remote scene tree popping up before🫠

After trying out a few possible Node.xml revisions, this is the one that felt the most straightforward: https://github.com/godotengine/godot/commit/9b0c83aa8f47bcc39c7c327fac0257ef6d18191f If there's anything else I can do, I am happy to help.

Best regards

Vinni

[kleonc]

I am embarrassed to admit that I never noticed the button for showing the remote scene tree popping up before🫠

Through the years I've seen many users not being aware of this, so it's very likely a discoverability issue. It is documented but maybe not in the best place? Also it kinda doesn't stand out visually too much. But it's definitely improved compared to 3.x:

v3.5.3.stable.official [6c814135b]	v4.3.stable.official [77dcf97d8]

After trying out a few possible Node.xml revisions, this is the one that felt the most straightforward: 9b0c83a If there's anything else I can do, I am happy to help.

Feel free to open a PR. :slightly_smiling_face:

[vinni-richburgh]

it's very likely a discoverability issue.

The fact, that clicking anything in the editor window makes the game window go out of focus, might have been discouraging me from stumbling over the remote tree just out of curiosity.

Over in Unreal you are shown the hierarchy of the running scene by default, which I used like. Maybe having an Advanced Setting bool for showing the remote scene tree by default would be nice. But that doesn't help people find out about the remote tree to begin with.

I think I would look for something like the remote scene tree documentation somewhere around here https://docs.godotengine.org/en/4.3/tutorials/editor/index.html.

[kleonc]

Maybe having an Advanced Setting bool for showing the remote scene tree by default would be nice.

There's already debugger/auto_switch_to_remote_scene_tree editor setting, false by default though:

https://github.com/godotengine/godot/blob/568589c9d8c763bfb3a4348174d53b42d7c59f21/editor/editor_settings.cpp#L862

I think I would look for something like the remote scene tree documentation somewhere around here https://docs.godotengine.org/en/4.3/tutorials/editor/index.html.

Anyway, this belongs to the https://github.com/godotengine/godot-docs repo, either issue/PR could be opened in there. I'm not sure if the suggested page is indeed a good place, whether maintainers of these docs will agree / like it, etc. :slightly_smiling_face:

In the main repo (here) there's only class reference docs (because they're built-in into the editor).