Improve drag and drop in Tree

[vaner-org]

Closes #54400, closes #3201.

This PR improves intuitiveness and usability for moving nodes via drag and drop in Tree, by:

1. Adding an always-present vertical component to the drop indicator, that points up to a to-be parent in the future place of their relationship line, as well as a phantom dropdown arrow when about to be the first ever child of a node.

2. Considering the x position of the cursor in determining to-be parent when in indent space (negative space to the left), akin to functionality seen in vector design software. When in item space, the current behaviour that users expect is largely maintained.

tree-improvement.mp4

3. Moving the drop indicator drawing outside of draw_item, and placing it on its own CanvasItem, that StyleBoxes that could previously occlude it no longer do.

Before	After

4. Preventing invalid drop targets, so unhandled cases of dropping as a descendant of self are no longer possible.

These changes allow for much more fluid interactions with the tree, where any kind of rearrangement the user might want to do is possible within a single mouse click, while also more clearly telegraphing relationships post-release.

cc @kleonc

[AdriaandeJongh]

this looks like an incredible improvement! looking at the video, i do have one question though: why do some items in the tree become blue temporarily? is that a remnant of the old method that didn’t take x pos into account? if so, it should probably go, as the hierarchy like this pr consistently adds is a much clearer indication of the result of the drag and drop.

[vaner-org]

Blue means pushed to inspector! I realised while working on this, and it's an indicator that's unrelated to this PR. Hovering on something for a bit turns it blue and shows it in the inspector, so that you can then drag the node into the blue node's export slots, if any.

[kleonc]

Looks very promising!
(I haven't checked the code)

But note that drag dropping is not for nodes only (or rather just for the tree items, which in case of the scene tree represent nodes). E.g. you can drag resources onto the nodes, in such case the new indicators are wrong:

v4.5.1.stable.official [f62fdbd]	v4.6.dev.gh-112993 [c599891c2]

Also be sure to take in mind potential user-usages of the Tree node.
Currently (without this PR) visual drop indicators are hard coded to be shown when Tree.drop_mode_flags != DROP_MODE_DISABLED, I think we could potentially change this to be somehow configurable (with default config preserving the previous behavior?). Given how the new indicators are much more complex visually it makes sense to have some control over them. However the indicators will be fixed for dropping resources onto nodes etc., probably the same level of customization should be available for the users.

[vaner-org]

@kleonc Makes sense, I'll start moving in that direction. Thank you for having a look.

[vaner-org]

With the addition of a pair of if statements, in the specific case that DROP_MODE_ON_ITEM is the only enabled flag for a drag:

• The dropdown arrow and stub are replaced with the prior rectangular selection, but now styled with the editor's accent color, much like the border that appears on a compatible inspector property slot, or as noted above, the "blue" that the text of the target node adopts when pushed to the inspector. This is registered in the theme as Tree > drop_on_item_color.
• Indent space is no longer considered for choosing this drop target.

Through this, the visualization of a "child" in this specific case is no more, replaced with something more analogous to the resulting action - an image replacing the Texture slot of a Sprite2D, a script replacing the Script slot of any node.

[AdriaandeJongh]

Tested this PR and generally think it's an improvement, or at least heading in the right direction.

Before:

Screen.Recording.2026-02-20.at.16.04.49.mp4

After:

Screen.Recording.2026-02-20.at.16.05.55.mp4

The one thing that bugs me is that dragging a node onto its already current position also shows the "you'll be parented to this node as the child" visuals even though you can obviously not parent a node onto itself. I'd probably address that before merging.

[vaner-org]

Thank you for the feedback. Not only should what you mentioned be addressed, but it also looks like the drop line is too thin compared to the relationship line in hiDPI.

I turned this into a draft once I was made aware how much of the engine interface relied on Tree, for very different purposes. I've been meaning to do a proper survey to ensure I don't mess with any of the visual metaphors for the many ways it's used. Additionally, I've identified an improvement to be made in the input editor tree that I'd like to PR first, before this one.

Will resume work on this soon.

[vaner-org]

Thank you for the approvals.

I was aware of the problem with multiple nodes, but due to the present solution's reliance on selected_item, it's best saved for a follow up or would add a lot more complexity, especially for an edge case.

[Calinou]

Tested locally, it works as expected. Code looks good to me.

Note that you can't drag-and-drop the last item of a tree outside its parent by moving it at the bottom (after the end of the tree). You have to make it a child of the root node all the way to the top instead:

drag-and-drop-tree.mp4

It's not a big issue, but I thought I'd mention it nonetheless.

[vaner-org]

Note that you can't drag-and-drop the last item of a tree outside its parent by moving it at the bottom (after the end of the tree). You have to make it a child of the root node all the way to the top instead.

Try dragging to the left. 😊
Or do you mean you would prefer everything past the end of the tree to be treated as free space for the root node? Looking into this.

[vaner-org]

Summarising my thoughts from earlier.

The addition of a new accepts_children flag for TreeItems allows us to exclude them from an adoptive hover. So the reparent indicator no longer appears over files in FileSystemDock, and its null root is now completely inaccessible.

Impossible child	Untouchable root

This also lays the groundwork for...

1. @Calinou's recommendation, which entails that whenever a Tree is updated, the eldest and lowermost node with accepts_children is nominated as the "fallback root," and accepts anything dropped in the free space below as last child. A draft for this is ready, but will take time. This would also be a good place to refactor parts of the editor's individual Tree instances, as they will get pulled in regardless.

2. Implementing #14338 as a drop_lock_depth flag for Input Map Editor, so that drags are able to maintain their hierarchy: actions only rearrange among actions, mappings only ever attempt to switch parents, and nothing invalid is attempted. This needs the prior feature to be rock solid first, so that this case isn't prematurely excluded from testing.

3. @KoBeWi's recommendation of better handling multi-select drags, which should then adhere to all the new rules.

These are best saved for successive PR's.

[AdriaandeJongh]

Sounds good to me!

[akien-mga]

Thanks!

[Decapitated]

Loving this enhancement. But one thing we seemed to have lost in the process is the parent highlight.

Not sure what everyone else thinks, but I think we should bring it back.

[vaner-org]

For the case of the FileSystem tree drag & drops, a theme change that totally hides inactionable sibling relationships and just indicates parents is in the works. It would look exactly like how dragging a node from the SceneTree into the FileSystem already looks.

filesystem-drop.mp4

This is also addresses @kleonc's concern above.

Given how the new indicators are much more complex visually it makes sense to have some control over them. However the indicators will be fixed for dropping resources onto nodes etc., probably the same level of customization should be available for the users.

[ChildLearningClub]

@vaner-org Thank you for working on this. I'm just now playing with 4.7 and noticed when dragging and dropping an object or another scene into the viewport there is no visual representation of where it will be placed within the scene tree when dropped like there is when dropping it into the scene tree itself. Would this be hard to maybe update sometime in the future?

[vaner-org]

@ChildLearningClub That would be a great addition, I would also find it useful. I will add it to my personal todo list but please consider writing a proposal for it as well, so that you may track its progress.