unreal.UsdAssetCache¶
- class unreal.UsdAssetCache(outer: Object | None = None, name: Name | str = 'None')¶
Bases:
ObjectThis class is an asset that can be created via the Content Browser and assigned to AUsdStageActors.
Its main purpose is to track generated assets based on the hash of the source prim data: Whenever the AUsdStageActor needs to generate e.g. a MaterialInstance, it will first hash the Material prim, and check whether its UUsdAssetCache3 already has an asset of that class for the resulting hash.
The cache can then be shared by multiple AUsdStageActors to prevent recreating UObjects from identical, already translated prim data.
A “Default Asset Cache” can be set on the project settings, and will be automatically used for any AUsdStageActor that hasn’t had an asset cache manually set beforehand.
C++ Source:
Plugin: USDCore
Module: USDClasses
File: USDAssetCache3.h
Editor Properties: (see get_editor_property/set_editor_property)
asset_directory(DirectoryPath): [Read-Write] Content directory where the asset cache will place newly created assets.Changing this directory to a new location will automatically try to cache any existing assets on that location, if they were generated from USD.
clean_up_unreferenced_assets(bool): [Read-Write] If this is true, every time a UsdStageActor using this asset cache closes a stage or swaps asset caches it will attempt to call DeleteUnreferencedAssets, potentially dropping any unreferenced asset, due to this operation or previous ones.Enable this if you want your AssetDirectory folder to be automatically cleaned up as stages close, and don’t plan on keeping other external references to those assets.
Note: Some asset types may have complicated setups, and may end up with references from other properties, actors and components for some time (e.g. due to a component in a transient package or undo/redo buffer). This means any automatically cleanup may not manage to clean up all untracked assets. Subsequent cleanups should eventually collect all assets, however.
WARNING: This will clear the undo buffer (i.e. transaction history) and run garbage collection after any cleanup operation!
hash_to_asset_paths(Map[str, SoftObjectPath]): [Read-Write] This is the main internal property that maps hashes to asset paths.Add entries to this property (or modify existing entries) and they will be returned by the asset cache whenever that hash is queried.
WARNING: Asset modifications are not currently tracked! Change a static mesh’s vertex color from red to green, and it will show the green cube when opening a stage with this asset cache, even if you open stages where the prim contains red as its vertex color.
only_handle_assets_within_asset_directory(bool): [Read-Write] When true, it means the asset cache will only ever return assets that are currently inside of the AssetDirectory folder. Move the assets out of the folder or change the folder and the asset cache will act as if these assets don’t exist, potentially even losing track of them.When false, it means the asset cache will fully track and use its provided assets wherever they are in the content browser.
- add_asset_referencer(asset, referencer) bool¶
Adds a new UObject referencer to a particular asset, returning true if the operation succeeded. Assets will not be deleted or untracked by the asset cache while the referencer is registered.
- property asset_directory: DirectoryPath¶
[Read-Write] Content directory where the asset cache will place newly created assets.
Changing this directory to a new location will automatically try to cache any existing assets on that location, if they were generated from USD.
- Type:
- cache_asset(hash, asset_path, referencer=None) None¶
Adds an existing asset to the cache attached to a particular hash, and optionally registering a referencer
- Parameters:
hash (str)
asset_path (SoftObjectPath)
referencer (Object)
- property clean_up_unreferenced_assets: bool¶
[Read-Write] If this is true, every time a UsdStageActor using this asset cache closes a stage or swaps asset caches it will attempt to call DeleteUnreferencedAssets, potentially dropping any unreferenced asset, due to this operation or previous ones.
Enable this if you want your AssetDirectory folder to be automatically cleaned up as stages close, and don’t plan on keeping other external references to those assets.
Note: Some asset types may have complicated setups, and may end up with references from other properties, actors and components for some time (e.g. due to a component in a transient package or undo/redo buffer). This means any automatically cleanup may not manage to clean up all untracked assets. Subsequent cleanups should eventually collect all assets, however.
WARNING: This will clear the undo buffer (i.e. transaction history) and run garbage collection after any cleanup operation!
- Type:
(bool)
- delete_unreferenced_assets(show_confirmation=False) None¶
- Deletes all assets that:
Are currently tracked by the asset cache;
Are set as deletable;
Are not used by other UObjects (by external assets, components, undo buffer, Python scripting variables, etc.).
Have no referencers;
Have not been saved to disk;
If bShowConfirmation is true, this will fallback to using engine code for deleting the assets, showing a confirmation dialog listing the assets that will be deleted. If false, it will silently try deleting the assets it can.
WARNING: This will clear the undo buffer (i.e. transaction history) and run garbage collection after deleting.
- Parameters:
show_confirmation (bool)
- delete_unreferenced_assets_with_confirmation() None¶
This is the same as calling DeleteUnreferencedAssets and providing true for bShowConfirmation. It is just exposed in this manner so we automatically get a button for calling this function on details panels of the asset cache.
WARNING: This will clear the undo buffer (i.e. transaction history) and run garbage collection after deleting.
- get_all_tracked_assets() Map[str, SoftObjectPath]¶
Returns a copy of the internal mapping between hashes and asset paths
- Return type:
- get_cached_asset(hash) Object¶
Returns the asset associated with a particular Hash, if any. Returns nullptr if there isn’t any associated path to this Hash, or if the associated path doesn’t resolve to an asset.
WARNING: As this may try loading a package from disk, this can only be called from the game thread!
- get_cached_asset_path(hash) SoftObjectPath¶
Returns the internal FSoftObjectPath associated with Hash, without trying to load the asset. If there is no asset associated with Hash, will return an invalid (empty) FSoftObjectPath.
- Parameters:
hash (str)
- Return type:
- get_hash_for_asset(asset_path) str¶
Returns the hash associated with a particular asset, or the empty string if there isn’t any. Note: The asset cache keeps internal reverse maps, so this should be O(1)
- Parameters:
asset_path (SoftObjectPath)
- Return type:
- get_num_assets() int32¶
Returns the total number of cached asset paths, whether these resolve to assets or not
- Return type:
int32
- get_or_create_cached_asset(hash, class_, desired_name, desired_flags, referencer=None) -> (Object, out_created_asset=bool)¶
Returns the cached UObject of the provided Class for the provided Hash if one exists. Otherwise, finds a new package for it on the cache’s AssetDirectory and creates the asset via a NewObject<Class> call, using with a sanitized version of the desired name and flags.
WARNING: As this may try loading a package from disk or call NewObject, this can only be called from the game thread!
- Parameters:
hash (str) – The string key to check with
class (type(Class)) – The class of the object that we want to retrieve or create from the asset cache
desired_name (str) – The name we want the created object to have (the actual name may have additional suffixes)
desired_flags (int32) – The flags we want the created object to have (the actual applied flags may differ depending on context)
referencer (Object) – The asset will not be deleted or untracked until this referencer is removed (via any of the RemoveAssetReferencer member functions)
- Returns:
The asset that was returned or created
out_created_asset (bool): Set to true if we created the asset that was return, but false if we returned an existing asset
- Return type:
- property hash_to_asset_paths: None¶
[Read-Write] This is the main internal property that maps hashes to asset paths.
Add entries to this property (or modify existing entries) and they will be returned by the asset cache whenever that hash is queried.
WARNING: Asset modifications are not currently tracked! Change a static mesh’s vertex color from red to green, and it will show the green cube when opening a stage with this asset cache, even if you open stages where the prim contains red as its vertex color.
- Type:
(Map[str, SoftObjectPath])
- is_asset_deletable(asset) bool¶
Returns whether a particular asset is currently marked as deletable or not
- is_asset_tracked_by_cache(asset_path) bool¶
Returns true if this asset is currently tracked by the asset cache’s main hash to asset maps
- Parameters:
asset_path (SoftObjectPath)
- Return type:
- load_and_get_all_tracked_assets() Map[str, Object]¶
The same as GetAllTrackedAssets, except that it will automatically try loading all the asset paths before returning, which should be convenient for Python or Blueprint callers.
WARNING: As this may try loading a package from disk, this can only be called from the game thread!
- property only_handle_assets_within_asset_directory: bool¶
[Read-Write] When true, it means the asset cache will only ever return assets that are currently inside of the AssetDirectory folder. Move the assets out of the folder or change the folder and the asset cache will act as if these assets don’t exist, potentially even losing track of them.
When false, it means the asset cache will fully track and use its provided assets wherever they are in the content browser.
- Type:
(bool)
- remove_all_asset_referencers() bool¶
Removes all UObject referencer from all tracked assets, returning true if anything was removed.
- Return type:
- remove_all_referencer_assets(referencer) bool¶
Removes a particular UObject referencer from all tracked assets, returning true if anything was removed. Will do nothing in case Referencer is invalid.
- remove_all_referencers_for_asset(asset) bool¶
Removes all UObject referencers from a particular asset, returning true if anything was removed. Will do nothing in case Asset is invalid.
- remove_asset_referencer(asset, referencer) bool¶
Removes an UObject referencer from a particular asset, returning true if anything was removed. Will do nothing in case Asset or Referencer are invalid.
- rescan_asset_directory() None¶
Checks the current AssetDirectory for any new assets that were generated from USD, and automatically caches them if possible.
Note: This will never overwrite any existing information on the asset cache (i.e. if the newly found asset is associated with a hash that is already in use, it will be ignored)
- set_asset_deletable(asset, is_deletable) None¶
Sets a particular asset as deletable or not. Assets not flagged as deletable will never be deleted by the asset cache when DeleteUnreferencedAssets is called. Assets the cache creates itself via GetOrCreateCachedAsset or GetOrCreateCustomCachedAsset are automatically set as deletable.
- stop_tracking_asset(hash) SoftObjectPath¶
Removes all info about the asset associated with Hash from this cache, if there is any. Note: This will not delete the asset however: Only tracked, unreferenced assets can be deleted by the asset cache, and only when manually created by it or if flagged with SetAssetDeletable
- Parameters:
hash (str)
- Return type: