Godot 4.6 Adds Unique Scene Node IDs, Fixing Scene Refactoring Pain

Forum topic · ✨步子哥 · 2026-06-09

Summary

Godot 4.6 introduces unique scene node IDs via PR #106837, authored by Juan Linietsky, ending years of frustration for developers who refactored base scenes. Previously, renaming or reparenting a node in a base scene broke inherited and instantiated scenes, losing properties, signal connections, and script references, since all lookups relied solely on node paths and names. The new system adds a fallback int32_t unique_scene_id to Node, assigned automatically on scene save and stored in PackedScene data. Name-based lookup remains the primary mechanism; the ID is only used when a name lookup fails, guaranteeing backward compatibility with existing .tscn/.scn files and avoiding the pitfalls that sank an earlier attempt (PR #86960). This resolves long-standing issues including #19520, #41047, #82700, #84928, #97576, #100038, and #110518, and fulfills proposal #6291. Future benefits include more robust 3D asset import pipelines, script-level ID access for stable cross-scene references, and editor tooling for refactoring. A forum author reports the feature works well in Godot 4.6 beta.

Renaming a node in Godot used to be a gamble. If you changed a node's name in a base scene, every inherited and instantiated scene that depended on the old path could break — properties lost, signals disconnected, script references erroring out. As the forum author put it: it was like changing a family's household registration and having all the children's custody records invalidated.

The fix: PR #106837

PR #106837, authored by Juan Linietsky and merged into Godot 4.6 (October 2025), directly addresses this. It adds unique scene node IDs — not by replacing the name-based system, but by quietly adding a fallback safety net.

From the PR's stated goal: when nodes in a base or instantiated scene are renamed, moved, or re-added, the hierarchy relationships should survive and nodes should remain findable.

How it works

Node now has an int32_t unique_scene_id field, defaulting to 0 (not assigned), with set_unique_scene_id and get_unique_scene_id methods.
When a scene is saved, the engine assigns scene-unique IDs to nodes that don't have one, stored in the PackedScene node data.
At lookup time, the engine first tries the old name-based path. Only if that fails does it match by ID in the node array.
Internal macros like FLAG_MASK and NODE_FROM_ID encode the ID together with internal indices for fast lookup with no extra overhead.
Old scene files load unchanged; IDs are generated automatically on the first save after upgrading.

> PackedScene is Godot's core container for serialized scene trees — nodes, properties, and connections packed into .tscn or .scn files. During inheritance or instantiation, the engine locates nodes by path; now the ID acts as a backup when the path breaks.

The author tested this by moving a TileMap to a different level of the scene tree — navigation modifications in child scenes that previously would have been lost now survived intact.

Years of pain, many bugs closed

The PR closes a long list of issues: #19520, #41047, #82700, #84928, #97576, #100038, #110518. Examples include:

Reparenting a TileMap wiped out navigation changes in child scenes
Renaming a root node broke inherited scene node trees entirely
Sprite textures mysteriously disappearing, property overrides failing

Community proposal #6291 ("Give nodes a stable scene local id to make scene inheritance robust") had requested this for years. An earlier attempt, PR #86960, was rejected as too aggressive for compatibility.

Why fallback, not ID-first?

The PR is explicit: making IDs the primary lookup would be too risky. Countless projects, plugins, and tutorials rely on name-based references; forcing a switch would break the ecosystem. With the fallback approach, the worst case is a lost reference — the engine never crashes or corrupts data. The PR repeatedly stresses guaranteeing that "nothing breaks."

What this unlocks

More robust 3D asset import pipelines that preserve material and collision references in inherited scenes
Discussions about exposing IDs at the script level, for stable cross-scene references without awkward unique_name_in_owner workarounds
Easier prototype-variant management for large teams
Likely future editor support: rename confirmations and visualization of which child scenes depend on an ID

Conclusion

Godot 4.6 beta is out, and the author reports that upgrading their project made base-scene refactoring far less frightening. As they concluded: renaming a node is no longer a betrayal — "a new name, but the same soul." With the ID in place, the roots hold.

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 (highlighting unique Node IDs)