Add retrieval methods to ResourceLoader for querying cached resource paths (C++, C#, GDScript)

[TruelyMostWanted]

Describe the project you are working on

Any game, tool or plugin, utilizing externally and internally located Resources that get loaded at runtime

Describe the problem or limitation you are having in your project

Cached Resources (= assigned to any (export) variables or attributes) are internally stored in the ResourceCache's HashMap<string, Ref<Resource>> resources in the form of { Key: "res://icon.svg/", Value: CompressedTexture2D() }
This API is not exposed in all 3 languages ( C++, C#, GDScript) and you can't filter the cached resource paths.
We should extend the ResourceLoader to access the caching system.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

SELECT ALL PATHS WHERE

• TARGET { TypeHint, Path, FileName, FileExtension, BaseDir, ResourceName, ResourcePath, ResourceClass }
• COMPARATOR { Equals, NotEquals, BeginsWith, EndsWith, Contains }
• VALUE (String)

Examples:

get_all_cached_paths()
get_cached_paths_by_filter(target: TYPE_HINT, comparator: EQUALS, value: "Image")
get_cached_paths_by_filter(target: PATH, comparator: BEGINS_WITH, value: "res://")
get_cached_paths_by_filter(target: FILE_NAME, comparator: BEGINS_WITH, value: "Spritesheet_") 
get_cached_paths_by_filter(target: FILE_EXTENSION, comparator: EQUALS, value: "png") 
get_cached_paths_by_filter(target: FILE_EXTENSION, comparator: BEGINS_WITH, value: "t")

"TYPE_HINT" Values: { Image, AudioStreamWAV, PackedScene, JSON, Shader, StandardMaterial3D, ... }
"PATH" (Prefix, Substring) Examples: { "res://", "user://", "/data", "/materials", "/data/audio/", ... }
"FILE_NAME" (Prefix) Examples: { "Spritesheet_", "IMG_", "Sprite_" }
"FILE_EXTENSION" (Substring) Examples: { "tres", "res", "mp3", "wav", "ogg", "jpeg", "png", "json", "csv" "cs", "gd", .... }

Results have the form of:

• Array = [path1, path2, path3, path4, path5, path6]
• Dictionary { "Path1"="TypeHint1", "Path2"="TypeHint2" }

Then these informations can be used to load the specific resources over the ResourceLoader.load(path, typeHint, useWorkerThreads, CacheMode) method --> No breaking changes to existing logic

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

ResourceCache:

• 2 templates for Predicates with 1 method each will be added to the resource_cache

ResourceLoader:

• 2 Enums will be created for the FilterTarget and the FilterComparator
• 4 additional methods will be declared and defined allowing to retrieve
• • all paths (as array + as dictionary)
• • all paths where the filter matches (as array + as dictionary)

Core_Bind:

• Enums and Methods will be registered and exposed to GDScript and C#

If this enhancement will not be used often, can it be worked around with a few lines of script?

No, as the ResourceCache API is not exposed at all.

Yes as users would need to create their own caching and managing systems, requiring to write basically "duplicated code" compared to the already existing ResourceLoader / ResourceCache inside the Godot Source Code.

Is there a reason why this should be core and not an add-on in the asset library?

These methods are particularly useful for retrieval queries in games, editor plugins, asset management tools, and runtime inspection and debugging.

Implementation

godotengine/godot#112217

[TruelyMostWanted]

Proposal has been edited to provide a bigger scope on the problem and the different use cases currently blocked.
Concept has been finalized with more methods for retrieval.

Linked Pull-Request will soon receive a udpate as well

[ydeltastar]

I recommend keeping the API lean. We can't add a method variation for every use case; add only what is not possible with the current exposed methods. These filtered versions can be done by the user using the paths and the String API, or by retrieving the cached resource for the type (using load()), so the only new method required to make it all work is get_cached_paths().

[TruelyMostWanted]

I recommend keeping the API lean. We can't add a method variation for every use case; add only what is not possible with the current exposed methods.

You're absolutely right about that. I've spent some hours researching on the source code and i was able to refactor it down to just 4 methods by just adding and exposing 2 new enums:
FilterTarget = { TypeHint, FileName, FileExtension, Path, BaseDirectory, ResourceName, ResourcePath }
FilterComparator = { Equals, NotEquals, BeginsWith, EndsWith, Contains }

So now all thats left is:

	static PackedStringArray get_cached_paths(); 
//= [ "res://a.png", "res://b.svg" ]
	static Dictionary get_all_cached_paths_typed(); 
//= { "res://a.png": "Image", "res://b.svg": "CompressedTexture2D" }

	static PackedStringArray get_cached_paths_by_filter(const FilterTarget &p_target, const FilterComparator &p_comparator, const String &p_value);
//= [ "res://a.png", "res://b.svg" ]
	static Dictionary get_cached_paths_typed_by_filter(const FilterTarget &p_target, const FilterComparator &p_comparator, const String &p_value);
//= { "res://a.png": "Image", "res://b.svg": "CompressedTexture2D" }

These filtered versions can be done by the user using the paths and the String API, or by retrieving the cached resource for the type

Yes, but passing the parameters over to the C++ side and performing the retrieval there is actually faster performance-wise than doing it on the C# or GDScript side. Also the native implementation allows to open possibilities on extending the search abilities to more areas, like the editor/file_system_dock. Extending the search from just paths to also types, file names, file extensions and more. Thats the next topic i want to look at after this one.

[TruelyMostWanted]

With the feedbacks received i've reworked it, reducing it to only 4 methods.
I'm sure you'll find the cleaned up version (and concept here) even better than before

Also old PR closed (due to coming from master branch) and new PR opened (from a freshly created feature branch)

If you liked/reacted on the original PR, feel free to visit the new PR and do it again ❤️👍🥳

Thanks for the help and feedback so far ❤️
Feel free to leave your opinions on it 😊