Node Path Refactor

Rename a node. This fixes everything you just broke.

Godot's editor rewrites the .tscn when you rename a node. It does not touch your scripts. So the moment you rename Player to Hero, all of this silently becomes a runtime crash:

@onready var sprite = $Player/Sprite

@onready var bar = get_node("Player/HealthBar")

@export var target: NodePath = NodePath("../Player/Sprite")

No warning at save time. No error in the editor. You find out when the game runs — or when a player does.

What it does

It builds a real index of every node in every scene, resolves every reference against the actual tree, and tells you exactly which ones are broken. Then it rewrites them correctly.

Press Rescan project and you get one row per reference:

• ok — resolves to a real node

• BROKEN — resolves to nothing, with suggested replacements

• partial — fine in some scenes, broken in others

• unknown — runs through an instanced sub-scene, so it can't be verified

• no scene — the script isn't attached to a scene, so nothing can be checked

Click any row to jump straight to that line in the script editor.

Why it isn't find-and-replace

Because find-and-replace gets this wrong.

These two lines are identical text, and they both mean Player/Sprite:

# written on the Player node

@onready var a = $"../Player/Sprite"

# written on the HUD node

@onready var b = $"../Player/Sprite"

After you rename Player to Hero, the first should become $"Sprite" — the node moved underneath the script. The second should become $"../Hero/Sprite" — nothing moved, only the name changed.

A text replace rewrites both the same way, and one of them ends up wrong. This tool resolves each reference to an absolute scene path first, then recomputes the relative path from the new owner. That's the whole trick, and it's why this isn't a grep wrapper.

What it rewrites

• $Player/Sprite and $"Player/Sprite"

• %HealthBar scene-unique names

• get_node(), get_node_or_null(), has_node()

• NodePath(...) in scripts and in .tscn files

• [connection from="Player" to="."] signal connections

What it deliberately won't touch

• Absolute /root/... tree paths. Those follow a different rule, and guessing wrong silently corrupts working code — so they're reported as unknown instead.

• find_child() and find_parent(). Those take wildcard patterns, not paths.

• Node names inside plain strings. "Player" on its own is not a reference.

• Anything inside a comment or a string literal. The scanner is a real tokenizer, not a regex pile, so "%d" % value and # $Player never trigger a hit.

A tool that cries wolf gets uninstalled. Avoiding false positives is the point.

Safe by default

• Every file is backed up to user://node_path_refactor_backups/<timestamp>/ before a single byte changes

• Preview shows the full diff of every edit before you commit anything

• Restore backup puts everything back with one click

• Scene-scoped by default — you choose whether a rename applies to one scene or the whole project

Install

1. Unzip into your project root — the folder that contains project.godot, not into addons/. The zip already contains the addons/ level, so it merges with your existing one. You should end up with:
   If you see addons/addons/node_path_refactor, you unzipped one level too deep. Move the inner folder up a level and delete the duplicate.

1. Project → Project Settings → Plugins → Enable

1. The dock appears as a tab next to Inspector — click it

The folder must stay named node_path_refactor. Godot resolves addon script paths statically (res://addons/node_path_refactor/...), so renaming it breaks the addon silently — the plugin just won't show up in the list. That's normal for Godot addons, not a quirk of this one.

Requires Godot 4.2+. MIT licensed: use it at work, fork it, ship it in a commercial game, whatever. Credit is appreciated but not required

Try it before you install it

The second download is a complete Godot project with the addon already installed and two deliberately broken references in it. Open it, press Rescan project, and you'll see exactly what you're getting before you touch your own codebase.

Known limitations

• GDScript only — C# scripts are not scanned

• Paths that run through an instanced sub-scene are reported as unknown, not verified (the tool can't see inside a scene it hasn't loaded)

• Absolute /root/... paths are not rewritten

• Node names containing / or " are not handled

Found a bug, or a reference it misses? Leave a comment. Every false positive is a bug, and I'd rather hear about it.