This is very helpful and much needed! I opened #82830 the other day and it appears that some of the perceived inconsistencies may be expected behaviors.

Since I just spent a chunk of time trying (and failing) to effectively use CacheModes, I wanted to share some questions/requests for clarifications that I hope will be useful as feedback coming from a user who does not have experience with this source code.

I say this because perhaps some things here may be working as expected and in accordance with the edits in this PR, but just not in a way that would be obvious to a user like me without deeper understanding of the engine.

CACHE_MODE_IGNORE:

The resource is always loaded from disk, even if a cache entry exists for its path, and the newly loaded copy will not be cached. Instances loaded with this mode will exist independently.

• PackedScenes that contain saved branches still load any resources located inside of subresources of the saved branches from cache (and save them to cache), while saved branches with subresources do load those subresources from disk. Is this intentional behavior that should also be documented here?

CACHE_MODE_REUSE:

If a resource is cached, returns the cached reference. Otherwise it's loaded from disk.

If the resource has sub-resources, they will not use cache and will always be loaded anew.

• It appears that resources located inside internal sub-resources of the resource being loaded are still loaded from cache. If this is expected behavior, perhaps this could be clarified?

CACHE_MODE_REPLACE:

If a resource is cached, returns the cached reference. Otherwise it's loaded from disk.

If the resource has sub-resources, they will be fetched from cache if available and/or stored in resource cache using their local paths.

• It appears that sub-resources are also loaded from disk in replace mode, even if a cached version exists. The exception is if they are a resource inside an internal subresource in a saved branch, in which case they use the cached version.

In addition, whether resources stored in subresources that are saved externally use the cache or are loaded from disk appears to vary based on the type of external resource. If this is expected behavior, should it be noted here that it can vary by resource type?

PackedScenes that contain saved branches still load any resources located inside of subresources of the saved branches from cache

I think PackedScenes might be an exception, especially when you need to instantiate them to reach the subresources.

CACHE_MODE_REUSE

The description I written was based only on the source code, but it's so convoluted that apparently I got it wrong. From my testing now, CACHE_MODE_REUSE and REPLACE do exactly the same, so no idea what's the difference. Maybe I'm testing wrong.

Not sure about the other quirks; they can be left for another PR.

Seems like this PR depends on #84167 now, because the current behavior is wrong. I could document how it's supposed to work, but it might be confusing.

Feel free to update the descriptions now, if it's required!

Updated the description of CACHE_MODE_REPLACE.

Also removed the mentions of sub-resources, as I'm not that sure about their inner workings. Possibly they are irrelevant for cache mode and should be mentioned somewhere else.

Thanks!