Resource Cache

Relevant source files

• core/extension/extension_api_dump.cpp
• core/io/resource.cpp
• core/io/resource.h
• core/io/resource_format_binary.cpp
• core/io/resource_format_binary.h
• core/io/resource_importer.cpp
• core/io/resource_importer.h
• core/io/resource_loader.cpp
• core/io/resource_loader.h
• core/io/resource_saver.cpp
• core/io/resource_saver.h
• core/math/expression.cpp
• core/math/expression.h
• core/object/script_language.cpp
• core/object/script_language.h
• core/object/script_language_extension.cpp
• core/object/script_language_extension.h
• core/variant/variant_parser.cpp
• core/variant/variant_parser.h
• doc/classes/Resource.xml
• doc/classes/ResourceFormatLoader.xml
• doc/classes/ResourceFormatSaver.xml
• doc/classes/ResourcePreloader.xml
• doc/classes/ResourceSaver.xml
• doc/classes/Script.xml
• doc/classes/ScriptExtension.xml
• doc/classes/ScriptLanguageExtension.xml
• doc/classes/ViewportTexture.xml
• modules/gdscript/editor/gdscript_docgen.cpp
• modules/gdscript/editor/gdscript_docgen.h
• modules/gdscript/gdscript.cpp
• modules/gdscript/gdscript.h
• modules/gdscript/gdscript_analyzer.cpp
• modules/gdscript/gdscript_analyzer.h
• modules/gdscript/gdscript_byte_codegen.cpp
• modules/gdscript/gdscript_byte_codegen.h
• modules/gdscript/gdscript_cache.cpp
• modules/gdscript/gdscript_cache.h
• modules/gdscript/gdscript_codegen.h
• modules/gdscript/gdscript_compiler.cpp
• modules/gdscript/gdscript_compiler.h
• modules/gdscript/gdscript_disassembler.cpp
• modules/gdscript/gdscript_editor.cpp
• modules/gdscript/gdscript_function.cpp
• modules/gdscript/gdscript_function.h
• modules/gdscript/gdscript_parser.cpp
• modules/gdscript/gdscript_parser.h
• modules/gdscript/gdscript_tokenizer.cpp
• modules/gdscript/gdscript_tokenizer.h
• modules/gdscript/gdscript_vm.cpp
• modules/gdscript/gdscript_warning.cpp
• modules/gdscript/gdscript_warning.h
• modules/gdscript/tests/gdscript_test_runner.cpp
• modules/gdscript/tests/test_gdscript.cpp
• modules/mono/csharp_script.cpp
• modules/mono/csharp_script.h
• modules/mono/editor/bindings_generator.cpp
• modules/mono/editor/bindings_generator.h
• modules/mono/godotsharp_defs.h
• modules/mono/mono_gd/gd_mono.cpp
• modules/mono/mono_gd/gd_mono.h
• scene/resources/resource_format_text.cpp
• scene/resources/resource_format_text.h
• tests/core/io/test_config_file.cpp
• tests/core/variant/test_variant.cpp

The Resource Cache is a centralized, thread-safe global registry that tracks all loaded resources in the engine by their file paths. It enables resource reuse, prevents redundant disk I/O by avoiding duplicate loading of the same asset, and supports hot-reloading of resources during runtime. For information about the loading mechanism itself, see ResourceLoader core/io/resource_loader.cpp31-42

Overview

The resource cache serves as the engine's memory for previously loaded resources. When a resource is loaded from disk, it is registered in the cache so that subsequent load requests for the same path return the existing instance. This system is critical for:

• Memory Efficiency: Sharing resource instances across the scene tree.
• Identity Consistency: Ensuring the same resource file maps to a single object instance, which is vital for shared materials, textures, and scripts.
• Hot-Reloading: Updating resources in-place when files change, facilitated by cache replacement modes.
• Thread Safety: Coordinating access to resources across multiple threads using a global mutex.

Sources: core/io/resource.h57-80 core/io/resource.cpp1-29 core/io/resource_loader.h31-50

Cache Architecture

The following diagram associates the logical cache components with their specific C++ entities within the core/io and core/object modules.

Code Entity Space: ResourceCache and Resource

Core Components:

Component	Type	Purpose
ResourceCache::resources	HashMap<String, Resource *>	Maps absolute resource paths to raw resource pointers. core/io/resource.h57-90
ResourceCache::lock	Mutex	Protects concurrent access to the global resource registry.
Resource::path_cache	String	The internal storage of the resource's current registered path. core/io/resource.h171-172
ResourceCache::resource_path_cache	HashMap	Used primarily in editor contexts to track unique IDs within scenes.

Sources: core/io/resource.h57-96 core/io/resource.h169-182 core/io/resource_loader.h58-70

Cache Modes

The ResourceFormatLoader::CacheMode enum (aliased in ResourceLoader) defines strategies for cache interaction. These modes determine if the engine should return an existing object or force a fresh read.

Cache Mode Details:

Mode	Behavior	Propagation	Use Case
CACHE_MODE_IGNORE	Returns a unique instance; does not check or update cache. core/io/resource_loader.h60	Sub-resources use REUSE.	One-off previews or temporary objects.
CACHE_MODE_REUSE	Returns cached instance if available; otherwise loads and caches. core/io/resource_loader.h61	Sub-resources use REUSE.	Standard gameplay and editor asset loading.
CACHE_MODE_REPLACE	Forces a reload and updates the existing cached instance. core/io/resource_loader.h62	Sub-resources use REUSE.	Hot-reloading a specific modified file.
CACHE_MODE_IGNORE_DEEP	Not cached; dependencies also ignore cache. core/io/resource_loader.h63	Propagates IGNORE.	Full resource isolation.
CACHE_MODE_REPLACE_DEEP	Updates instance and forces reload of all dependencies. core/io/resource_loader.h64	Propagates REPLACE.	Cascade hot-reload of complex scenes.

Sources: core/io/resource_loader.h58-65 core/io/resource_loader.cpp165-182

Cache Lifecycle Operations

Registration and Path Takeover

When Resource::set_path() is called, the resource enters the global registry. If the p_take_over flag is set, the resource will displace any existing entry for that path.

Sources: core/io/resource.h171-182 core/io/resource_loader.cpp58-83

Resource Cleanup

The ResourceCache stores raw pointers (Resource *) to avoid circular reference increments that would prevent RefCounted objects from being freed. When a Resource is destroyed, its destructor ensures it is removed from the global map.

Implementation in Scripting Systems

The cache system is extensively used by scripting backends to manage script dependencies and class resolution:

• GDScriptCache: Manages the lifecycle of parsed and analyzed GDScript files. It uses get_shallow_script to retrieve scripts from the cache or load them if missing. modules/gdscript/gdscript_compiler.cpp161-166
• CSharpLanguage: Maintains script_bindings to map managed C# objects to Godot objects, ensuring that the interop bridge does not duplicate wrappers for the same underlying resource. modules/mono/csharp_script.cpp152-163
• GDScriptAnalyzer: During semantic analysis, it relies on the cache to resolve types from other files via script_path. modules/gdscript/gdscript_analyzer.cpp127-130

Sources: modules/gdscript/gdscript_compiler.cpp156-176 modules/mono/csharp_script.cpp140-165 modules/gdscript/gdscript_analyzer.cpp87-131

Scene-Unique IDs

Beyond file paths, the system supports Scene-Unique IDs (scene_unique_id). These are used to identify resources internal to a specific scene file (e.g., a specific Mesh within a .tscn).

• Internal Registry: The ResourceCache tracks these IDs to facilitate sub-resource retrieval within the ResourceLoader framework. core/io/resource.h74-76
• GDScript Parser Integration: The parser uses these identifiers when resolving @onready nodes or preloaded sub-resources. modules/gdscript/gdscript_parser.cpp146-152

Sources: core/io/resource.h74-76 modules/gdscript/gdscript_parser.cpp143-155