Search public documentation:
The asset consolidation tool provides a simple way within the editor to consolidate multiple assets to one asset. As an example, consider a texture that has become duplicated numerous times over the course of development, resulting in a waste of resources by storing multiple copies of what amounts to the exact same texture. The asset consolidation tool allows the user to select all such uses as desired and have them all point to one particular instance of the texture instead.
The asset consolidation is fairly simple to use, but caution must be exercised to utilize it properly.
| Here a texture has been duplicated many times! Selecting them|
all and right-clicking grants the option to 'Consolidate...'
| Inside the consolidate dialog, selecting an asset marks it as the|
'object to consolidate to'
|All of the duplicates have been consolidated to the chosen asset!|
The actual consolidation process occurs in multiple steps. First, for any valid objects that are to be consolidated, the tool attempts to replace all references of those objects with references to the "object to be consolidated to" within objects/packages that are already loaded and in memory. What this means is if you have a map or package already open that is referring to one of the objects to be consolidated, the tool will attempt to update it immediately. Next, the tool attempts to delete the objects to be consolidated directly (there is a potential for this to fail, see Limitations and Caveats). Finally, if the deletion was successful, the tool leaves behind object redirectors in the place of the deleted objects. These will redirect unloaded packages with references to the deleted objects to the object you consolidated them to.
- Improper use of the Asset Consolidation Tool can be extremely dangerous given the nature of what it does. Users of the tool should always think carefully about what they are about to do and decide if the resulting operation would make sense in the context of their assets. The tool attempts to guard against some obviously incorrect consolidations, but users should still always exercise caution in order to avoid ruining packages. Keep in mind that the tool will delete consolidated assets and route previous uses of them to the selected object; it is not an alternative method of doing a "replace actor"-type operation.
- The Asset Consolidation Tool makes heavy use of object redirectors, meaning it is a good idea to occasionally make use of the Fixup Redirects Commandlet some time after the use of the Asset Consolidation Tool.
- While the Asset Consolidation Tool will attempt to forcibly replace references to objects to consolidate in packages/maps that are currently loaded and in memory, it is best to maximize the chance of a successful consolidation by having as few things referencing the objects to consolidate as possible while using the tool. In particular, it is extremely ill-advised to have sub-editors (such as the AnimSet editor) open and utilizing assets that are about to be consolidated.
While useful, the Asset Consolidation Tool does have some limitations and caveats, outlined below:
- To prevent the user from accidentally destroying their packages, the Asset Consolidation Tool can only be invoked on assets that share the same class/type, with an exception made if all objects are a type of material or a type of texture(meaning that a material could be consolidated to a decal material, even though they are not strictly the same type). This restriction is in place to prevent consolidations that would certainly cause crashes and/or package destruction, such as consolidating a material into a static mesh. Even where cross-type consolidation is allowed, the tool presents a clearly visible warning that multiple types have been chosen for consolidation.
- The Asset Consolidation Tool can not always consolidate the assets the user has selected. If a user selects an "asset to consolidate to" that contains references to one of the assets to consolidate, that particular asset to consolidate will not be consolidated. Allowing such an operation would make the "asset to consolidate to" refer to itself, which would certainly lead to trouble. Additionally, root packages cannot be consolidated, though they should never show up as a valid option in the first place. At the end of a consolidation operation, the user is warned which, if any, of their assets were skipped for consolidation.
- The Asset Consolidation Tool can sometimes fail to consolidate an otherwise valid asset if not all of its references could be cleared, or it could not be deleted for some reason. This type of failure is critical, resulting in "partial consolidation," in which some uses of an asset have been consolidated and some have not. This type of failure should be quite rare, but should the situation arise, the user is warned with a dialog showing the affected assets and potentially affected packages. The user should NOT save any of the affected assets/packages or they will be accepting a potentially disastrous partial consolidation.
- As mentioned in Best Practices, it is extremely ill-advised to utilize the Asset Consolidation Tool while potentially affected assets are being used in various sub-editors, such as the AnimSet editor. Ultimately most sub-editors as of yet do not respond well to having references swapped from under them, so using the sub-editors while consolidating can lead to the sub-editors being put into invalid states and/or potentially crashing.
- For now, once a consolidation operation has been successfully performed, it is advised to save the relevant packages before attempting to load into memory any unloaded packages that also reference one of the consolidated objects. A currently outstanding Content Browser/Object Redirector bug can cause consolidated assets to reappear in the browser if a referencing package is loaded before saving.
- The Asset Consolidation Tool only replaces references to the consolidated objects in packages that were already loaded at the time of the operation. It relies on object redirectors to fix up the remaining references in unloaded packages. This means care should be taken to not perform an action that will trample on, overwrite, delete, etc. the redirectors, unless specifically desired. Otherwise, some packages will correctly be fixed up and some won't. As outlined earlier, making use of the Fixup Redirects Commandlet can alleviate this issue.