Godot 4.6 Adds Unique Scene Node IDs to Make Node Renaming Safe

*Translated and edited from a Chinese forum post on zhichai.net.*

It's 2 a.m. I want to rename the node called "主角" (Protagonist) in my project to something better. I rename it, save, and switch to the inherited scenes — everything breaks. Properties gone, signals disconnected, script references erroring out.

I'm not the first to hit this. Many in the Godot community have suffered the same. And now, PR #106837 has finally closed the door on this problem. Juan Linietsky personally implemented unique scene IDs — not a radical overhaul, but a quiet safety net added underneath. Names can still be changed freely; IDs quietly keep the references intact. After upgrading to 4.6, refactoring base scenes no longer feels like walking a tightrope.

What changed

Godot's scene system has always been a joy: you build a base scene, others inherit it, tweak properties, add nodes, connect signals. But the "skeleton" of that inheritance was pinned to names. Change a name, break a path, and inheritance collapses.

The PR states its main goal plainly: keep the hierarchy intact and nodes findable when nodes in base or instantiated scenes are renamed, moved, or re-added. Old scene files load unchanged; the new IDs only kick in when needed.

Think of it as issuing everyone an ID card. Day to day, people call you by your nickname; when identity matters, you flash the card. Rename without losing identity.

> PackedScene is the core of Godot's scene serialization — it packs nodes, properties, and connections into .tscn or .scn files. During inheritance or instantiation, the engine locates nodes by path. Previously a broken path meant broken data; now IDs back it up.

I tested it myself: moving a TileMap between layers used to wipe out all navigation modifications in sub-scenes. Now the ID keeps the references alive. Smooth.

Years of pain, finally addressed

The PR directly closes a pile of old issues — #19520, #41047, #82700, #84928, #97576, #100038, #110518 — each one a war story: reparent a TileMap and sub-scene navigation dies; rename a root node and inherited trees snap; sprite textures vanish; property overrides fail. Community proposal #6291 had asked for this for years.

An earlier attempt, PR #86960, was rejected as too aggressive for compatibility. The new approach is smart in being fallback-only: the ID is used only when a node can't be found by name. Worst case, a reference is lost — the engine doesn't crash or corrupt data.

How the ID works

• Node gains an int32_t unique_scene_id (0 = unassigned), with set_unique_scene_id() / get_unique_scene_id() methods.
• On scene save, the engine assigns a scene-unique number to any node without one, stored in the PackedScene node data.
• Lookups go by name first; only on failure does the engine match by ID against the node array. Internal macros like FLAG_MASK and NODE_FROM_ID pack the ID with internal indices for fast, space-free encoding.

The key word is fallback. Names remain the primary mechanism; the ID is a second line of defense. Old projects get IDs generated on their first save after upgrading, after which base-scene refactors are largely safe.

Why fallback and not ID-first?

Because safety beats perfection. Countless projects, plugins, and tutorials rely on name-based references. Switching everyone to IDs overnight would force a mass rewrite. The PR repeatedly emphasizes: at minimum, "nothing breaks." The most-workable choice, not the theoretically optimal one.

What this opens up

• More robust 3D asset imports, preserving material and collision references in inherited scenes.
• Discussions already exist on exposing IDs at the script level, enabling stable cross-scene references without unique_name_in_owner workarounds.
• Editor support may follow — rename warnings that references are protected, or visualizations of which sub-scenes depend on an ID — dramatically lowering refactoring costs.

Closing thoughts

I've upgraded my project to the 4.6 beta. Renaming base scenes no longer terrifies me. A small ID, a large peace of mind. Renaming a node is no longer betrayal — it's "a new name, the same soul."

References

1. Godot Pull Request #106837 - Add unique Node IDs to support base and instantiated scene refactorings (merged into 4.6, October 2025). 2. Godot Proposals #6291 - Give nodes a stable scene local id to make scene inheritance robust. 3. Godot Issue #19520 - Refactoring Scene breaks custom properties in inherited scene. 4. Godot Issue #82700 - Renaming Node Causes Lost Data in Inherited Scenes. 5. Godot 4.6 Beta release notes (explicitly mention the unique Node IDs feature).