Add UID upgrade tool #102071

Meorge · 2025-01-27T03:42:48Z

Closes godotengine/godot-proposals#11639 .

This PR adds a new tool to the Project > Tools menu, currently titled "Update UIDs...". When run, it finds all of the Resource and PackedScene files in the project and re-saves them, causing the UID references to scripts and shaders to be added to them.

Here is a small project I put together with a few PackedScenes and a custom Resource subclass:
uid-upgrader-test_2025-01-26_19-36-02.zip

After running the tool, you can see that the UIDs have been added to all of the scene and resource files:

The code in this PR is adapted from the "Upgrade Mesh Surfaces..." tool (SurfaceUpgradeTool and SurfaceUpgradeDialog in the source code).

Note

I think it would be nice to have this pop-up display automatically when a project is first opened in 4.4 from a previous version, although I'm not sure yet how easy that would be to do. I hope to look more into that in the coming days, but in the meantime the tool is accessible through the menu bar as described previously.

To Do

Add "Learn More" button to window - should open blog post page
Look into _open_selected_projects_check_warnings for possibility of auto-opening tool when upgrading to 4.4

arkology · 2025-01-27T06:53:13Z

I think it would be nice to have this pop-up display automatically when a project is first opened in 4.4 from a previous version, although I'm not sure yet how easy that would be to do. I hope to look more into that in the coming days, but in the meantime the tool is accessible through the menu bar as described previously.

Try to check ProjectManager::_open_selected_projects_check_warnings().

KoBeWi · 2025-01-27T14:13:21Z

I wonder... We have Surface Upgrade Tool and now the UID Upgrade, but they both serve more or less the same task - open and re-save files. The problem is that they don't handle all files, so if we want to upgrade something else in the future, we will need another upgrade tool.

The script I posted in godotengine/godot-proposals#11639 (comment) handles pretty much all relevant files in a future-proof way, and it's only 27 lines. Maybe we should just have a single universal "upgrade tool" that user is supposed to run manually when opening in a new version? If it handles every resource there won't be any need for new tools, unless for something very specific that involves more than load and save.

editor/uid_upgrade_tool.h

Calinou · 2025-01-27T14:41:18Z

I wonder if we can add a third button in the dialog that opens https://godotengine.org/article/uid-changes-coming-to-godot-4-4/ in a web browser. It would be helpful to give more context to users as to why the change was done, especially if they don't follow changelogs.

At the very least, the dialog's text should state that the new .uid files should be added to version control.

editor/editor_node.cpp

editor/uid_upgrade_tool.cpp

Meorge · 2025-01-27T17:41:06Z

Try to check ProjectManager::_open_selected_projects_check_warnings().

Thanks, I'll give that a look soon!

The script I posted in godotengine/godot-proposals#11639 (comment) handles pretty much all relevant files in a future-proof way, and it's only 27 lines. Maybe we should just have a single universal "upgrade tool" that user is supposed to run manually when opening in a new version? If it handles every resource there won't be any need for new tools, unless for something very specific that involves more than load and save.

I like this idea! As stated previously, this PR is basically just an adaptation of the existing surface tool code anyways, so there's a lot of code there that's at best duplicate-adjacent.

I'm not sure how "hard" the 4.4 feature freeze is; my hope was that, because the UID change introduces such a big friction point for updating and keeping clean version control, this tool could be added to 4.4 so that people could use it to upgrade their projects as soon as 4.4 becomes available. In that case, I'd be a bit nervous about expanding the scope of this PR to act as a more general project updater, since there'd be more possibility of bugs cropping up.

However, if the feature freeze wouldn't allow this to be included until 4.4.1 (or 4.5) then we'd have a lot more time to get it polished and ready for its release. In the meantime, your script and instructions on how to run it could be included in the blog posts about 4.4's release.

I wonder if we can add a third button in the dialog that opens https://godotengine.org/article/uid-changes-coming-to-godot-4-4/ in a web browser. It would be helpful to give more context to users as to why the change was done, especially if they don't follow changelogs.

At the very least, the dialog's text should state that the new .uid files should be added to version control.

I've added a bit of text stating the user should add .uid files. As for the third button, I see that AcceptDialog does have a method to add custom buttons to it, so I can look into adding a "learn more" button to the dialog.

KoBeWi · 2025-01-27T23:32:39Z

Well for 4.4 the current solution makes sense. We could refactor it in the future. The universal tool would replace existing ones.

Meorge · 2025-01-28T02:01:17Z

I've added a "Learn more" button to the dialog box that opens the blog post about UIDs. It appears the current API for AcceptDialog only allows for it to be placed either to the left or to the right of all the buttons, so for now I have it on the right.

I looked at _open_selected_projects_check_warnings and it doesn't sound to me like it would quite fit what we need, since it runs in the project manager before the main editor is open. I also gave a shot at reading through the core/editor code to find where we could detect a 4.3 (or lower) project had been opened in 4.4, but nothing stuck out to me. I may give it another shot tomorrow, but if it looks like it's going to get too complex adding this check in, we may just want to tell people to find the option in the Tools menu.

I looked into it a bit further and found a spot that looks promising! Working on it now.

Meorge · 2025-01-28T04:50:32Z

The tool window is now displayed automatically when the editor is started with a project on 4.3 or less!

Godot.4.4.Display.UID.Upgrade.on.Project.Open.mp4

editor/uid_upgrade_tool.h

KoBeWi · 2025-01-28T14:17:59Z

The dialog appears too early and progress dialog will overlay it:

Meorge · 2025-01-28T17:24:12Z

Thanks for pointing this out! I was feeling like popping it up at the end of the EditorNode constructor wasn't quite right, but I wasn't sure where else to put it...

With your screenshot, it occurred to me that the check could be run immediately after _load_editor_layout when doing the first scan. I'll give that a try soon!

Meorge · 2025-01-29T05:32:08Z

I've changed the order of detecting a 4.3 project and displaying the popup now so that it appears after the progress dialog:

Godot.4.4.Display.UID.Upgrade.v2.mp4

When the EditorNode receives the READY notification, it checks the project's version number before performing an initial save of the project settings. If it detects the project is from 4.3 or before, it activates a flag variable.
Later, when the _sources_changed method is evaluated, it checks that flag variable. If the flag is true, it sets it back to false (to avoid re-triggering the popup in the future) and then displays the popup.

For right now, I'm avoiding squashing commits so that I can refer back to code from previous commits if need be. When it looks good, I can squash them so the resulting single commit is ready to merge 😄

editor/uid_upgrade_tool.cpp

Calinou · 2025-01-29T08:12:57Z

editor/uid_upgrade_tool.cpp

+}
+
+void UIDUpgradeTool::prepare_upgrade() {
+	EditorSettings::get_singleton()->set_project_metadata("uid_upgrade_tool", "run_on_restart", true);


"uid_upgrade_tool" could be moved to a static class string constant to avoid typos and benefit from autocompletion, e.g:

static constexpr const char *META_UID_UPGRADE_TOOL = "uid_upgrade_tool";

editor/editor_node.cpp

Calinou

Tested locally on various demo projects (with GDScripts and shaders), it works as expected. Code looks good to me.

I've also tested --import, --headless --import, --export and --headless --export (each time in a clean 4.3 repository) and they all work as expected.

editor/editor_node.cpp

Apply suggestions from code review Co-authored-by: Tomasz Chabora <kobewi4e@gmail.com> memdelete the UID upgrade tool Remove redeclaration of singleton Add note about committing .uid files to version control Add "Learn more" button that links to Godot blog post about UIDs Detect project from 4.3 or less and automatically display UID upgrade window Display popup after first run of `_sources_changed` Apply suggestions from code review Co-authored-by: Hugo Locurcio <hugo.locurcio@hugo.pro> Co-authored-by: Tomasz Chabora <kobewi4e@gmail.com> Replace magic strings with constants Update editor/editor_node.cpp Co-authored-by: Tomasz Chabora <kobewi4e@gmail.com>

Repiteo · 2025-01-30T17:42:55Z

Thanks!

QwertTheWert · 2025-02-08T11:49:55Z

Is there a way to manually enable this tool? Since i have updated my project to 4.4 beta-1 before and so the dialogue doesn't show up.

AThousandShips · 2025-02-08T11:54:04Z

Does it not work when using the tool menu button "Upgrade UIDs..."?

QwertTheWert · 2025-02-08T12:51:28Z

I... missed that. whoops

AThousandShips added enhancement topic:editor usability labels Jan 27, 2025

AThousandShips added this to the 4.x milestone Jan 27, 2025

AThousandShips requested a review from a team January 27, 2025 08:46

KoBeWi reviewed Jan 27, 2025

View reviewed changes

editor/uid_upgrade_tool.h Outdated Show resolved Hide resolved

KoBeWi reviewed Jan 27, 2025

View reviewed changes

editor/editor_node.cpp Outdated Show resolved Hide resolved

KoBeWi reviewed Jan 27, 2025

View reviewed changes

editor/uid_upgrade_tool.cpp Outdated Show resolved Hide resolved

Meorge force-pushed the feat/uid-upgrader branch from 9777af8 to 8a93cea Compare January 27, 2025 17:24

Meorge force-pushed the feat/uid-upgrader branch from 8a93cea to 0e13dbc Compare January 28, 2025 04:49

Meorge requested a review from KoBeWi January 28, 2025 05:12

KoBeWi reviewed Jan 28, 2025

View reviewed changes

editor/uid_upgrade_tool.h Outdated Show resolved Hide resolved

Repiteo modified the milestones: 4.x, 4.4 Jan 28, 2025

Meorge requested a review from KoBeWi January 29, 2025 05:47

Calinou reviewed Jan 29, 2025

View reviewed changes

editor/uid_upgrade_tool.cpp Outdated Show resolved Hide resolved

Calinou reviewed Jan 29, 2025

View reviewed changes

editor/editor_node.cpp Outdated Show resolved Hide resolved

Calinou reviewed Jan 29, 2025

View reviewed changes

KoBeWi reviewed Jan 29, 2025

View reviewed changes

editor/editor_node.cpp Outdated Show resolved Hide resolved

KoBeWi approved these changes Jan 29, 2025

View reviewed changes

Meorge force-pushed the feat/uid-upgrader branch from 453da08 to d034d12 Compare January 30, 2025 16:42

Repiteo merged commit 5f4a0be into godotengine:master Jan 30, 2025
19 checks passed

AThousandShips mentioned this pull request Jan 30, 2025

Add options to control if ".uid" files are generated #100973

Open

Meorge deleted the feat/uid-upgrader branch February 3, 2025 17:27

juliohq mentioned this pull request Mar 10, 2025

Update to Godot 4.4 unknown-horizons/godot-port#129

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add UID upgrade tool #102071

Add UID upgrade tool #102071

Meorge commented Jan 27, 2025 •

edited

Loading

arkology commented Jan 27, 2025

KoBeWi commented Jan 27, 2025

Calinou commented Jan 27, 2025 •

edited

Loading

Meorge commented Jan 27, 2025

KoBeWi commented Jan 27, 2025

Meorge commented Jan 28, 2025 •

edited

Loading

Meorge commented Jan 28, 2025

KoBeWi commented Jan 28, 2025

Meorge commented Jan 28, 2025

Meorge commented Jan 29, 2025

Calinou Jan 29, 2025 •

edited

Loading

Calinou left a comment

Repiteo commented Jan 30, 2025

QwertTheWert commented Feb 8, 2025

AThousandShips commented Feb 8, 2025

QwertTheWert commented Feb 8, 2025

Add UID upgrade tool #102071

Add UID upgrade tool #102071

Conversation

Meorge commented Jan 27, 2025 • edited Loading

To Do

arkology commented Jan 27, 2025

KoBeWi commented Jan 27, 2025

Calinou commented Jan 27, 2025 • edited Loading

Meorge commented Jan 27, 2025

KoBeWi commented Jan 27, 2025

Meorge commented Jan 28, 2025 • edited Loading

Meorge commented Jan 28, 2025

KoBeWi commented Jan 28, 2025

Meorge commented Jan 28, 2025

Meorge commented Jan 29, 2025

Calinou Jan 29, 2025 • edited Loading

Choose a reason for hiding this comment

Calinou left a comment

Choose a reason for hiding this comment

Repiteo commented Jan 30, 2025

QwertTheWert commented Feb 8, 2025

AThousandShips commented Feb 8, 2025

QwertTheWert commented Feb 8, 2025

Meorge commented Jan 27, 2025 •

edited

Loading

Calinou commented Jan 27, 2025 •

edited

Loading

Meorge commented Jan 28, 2025 •

edited

Loading

Calinou Jan 29, 2025 •

edited

Loading