The Asset Database

With most types of asset, Unity needs to convert the data from the asset’s source file into a format that it can use in a game or real-time application. It stores these converted files, and the data associated with them, in the Asset Database.

The conversion process is required because most file formats are optimized to save storage space, whereas in a game or a real-time application, the asset data needs to be in a format that is ready for hardware, such as the CPU, graphics, or audio hardware, to use immediately. For example, when Unity imports a .png image file as a texture, it does not use the original .png-formatted data at runtime. Instead, when you import the texture, Unity creates a new representation of the image in a different format which is stored in the Project’s Library folder. The Texture class in the Unity engine uses this imported version, and Unity uploads it to the GPU for real-time display.

If you subsequently modify an asset’s source file that you have already imported (or if you change any of its dependencies) Unity reimports the file and updates the imported version of the data. See Refreshing the Asset Database for more information on this process.

The Asset Database also provides an AssetDatabase API that you can use to access Assets, and control or customize the import process.

Note: This documentation refers to the version 2 of the Asset Database. See Asset Database version below for more information.

Asset import dependencies

The Asset Database keeps track of all the dependencies for each asset, and keeps a cache of the imported versions of all the Assets.

An Asset’s import dependencies consists of all of the data that might influence the imported data. For example, the source file of an Asset is a dependency, as well as the Asset’s import settings (such as a texture’s compression type), or the target platform of your Project (for instance, PS4 hardware requires data in a different format to Android hardware). If you modify any of these dependencies, the cached version of the imported Asset becomes invalid and Unity must re-import it to reflect the changes.

Asset caching

The Asset Cache is where Unity stores the imported versions of assets. Because Unity can always recreate these imported versions from the source asset file and its dependencies, these imported versions are treated as a cache of pre-calculated data, which saves time when you use Unity. For this reason, you should exclude the files in the Asset Cache from version control systems.

Unity uses a local cache by default, which means that the imported versions of Assets are cached in the Library folder in your Project’s folder on your local machine. You should use an ignore file to exclude this folder from version control.

However, if you work as part of a team and use a version control system, it might be beneficial to also use Unity Accelerator, which shares the Asset Cache across your LAN.

Because cached Assets are not suitable for storing in a version control system, when your team works together on a Project and uses local caching, every team member’s copy of Unity performs the import process if an Asset or dependency changes, which can be time consuming.

Unity provides a solution to this called Unity Accelerator. One of the Accelerator’s features is a software agent which stores and serves the cached versions of Assets to everyone who is working on the same Project together on the same local network. This means that only one team member needs to import any given asset. The imported version of the Asset is then stored in the Accelerator and the other team members can download the cached version instead of waiting for the import process locally.

Source Assets and Artifacts

Unity maintains two database files in the Library folder, which together are called the Asset Database. These two databases keep track of information about your source asset files, and Artifacts, which is information about the import results.

The source Asset Database

The source Asset Database contains meta-information about your source asset files which Unity uses to determine whether the file has been modified, and therefore whether it should reimport the files. This includes information such as last modified date, a hash of the file’s contents, GUIDs and other meta-information.

The Artifact database

Artifacts are the results of the import process. The Artifact database contains information about the import results of each source asset. Each Artifact contains the import dependency information, Artifact meta-information and a list of Artifact files.

Note: The database files are located in your Project’s Library folder, and as such you should exclude them from version control systems. You can find them in the following locations:

Source Asset Database: Library\SourceAssetDB
Artifact Database: Library\ArtifactDB

Importing an Asset

Unity normalmente importa assets automáticamente cuando son arrastrados al proyecto, pero también es posible importarlos bajo control de scripts. Para hacer esto puedes usar el método AssetDatabase.ImportAsset como en el siguiente ejemplo.

using UnityEngine;
using UnityEditor;

public class ImportAsset {
    [MenuItem ("AssetDatabase/ImportExample")]
    static void ImportExample ()
    {
        AssetDatabase.ImportAsset("Assets/Textures/texture.jpg", ImportAssetOptions.Default);
    }
}

También puedes pasar un parámetro extra del tipo AssetDatabase.ImportAssetOptions para el llamado a AssetDatabase.ImportAsset. En las páginas de referencia de scripting se encuentran descritas las diferentes opciones y sus efectos sobre el comportamiento de la función.

Loading an Asset

El editor sólo carga assets cuando sea necesario, p.ej. si son agregados a la escena o editados desde el panel Inspector. Sin embargo, puedes cargar y acceder assets desde un script usando AssetDatabase.LoadAssetAtPath, AssetDatabase.LoadMainAssetAtPath, AssetDatabase.LoadAllAssetRepresentationsAtPath y AssetDatabase.LoadAllAssetsAtPath. Ver la documentación de scripting para más detalles.

using UnityEngine;
using UnityEditor;

public class ImportAsset {
    [MenuItem ("AssetDatabase/LoadAssetExample")]
    static void ImportExample ()
    {
        Texture2D t = AssetDatabase.LoadAssetAtPath("Assets/Textures/texture.jpg", typeof(Texture2D)) as Texture2D;
    }
}

File Operations using the AssetDatabase

Puesto que Unity mantiene los metadatos de los archivos de assets, nunca debes crear, mover o borrar estos assets usando el sistema de archivos. En su lugar, puedes usar AssetDatabase.Contains, AssetDatabase.CreateAsset, AssetDatabase.CreateFolder, AssetDatabase.RenameAsset, AssetDatabase.CopyAsset, AssetDatabase.MoveAsset, AssetDatabase.MoveAssetToTrash y AssetDatabase.DeleteAsset.

public class AssetDatabaseIOExample {
    [MenuItem ("AssetDatabase/FileOperationsExample")]
    static void Example ()
    {
        string ret;
        
        // Create
        Material material = new Material (Shader.Find("Specular"));
        AssetDatabase.CreateAsset(material, "Assets/MyMaterial.mat");
        if(AssetDatabase.Contains(material))
            Debug.Log("Material asset created");
        
        // Rename
        ret = AssetDatabase.RenameAsset("Assets/MyMaterial.mat", "MyMaterialNew");
        if(ret == "")
            Debug.Log("Material asset renamed to MyMaterialNew");
        else
            Debug.Log(ret);
        
        // Create a Folder
        ret = AssetDatabase.CreateFolder("Assets", "NewFolder");
        if(AssetDatabase.GUIDToAssetPath(ret) != "")
            Debug.Log("Folder asset created");
        else
            Debug.Log("Couldn't find the GUID for the path");
        
        // Move
        ret = AssetDatabase.MoveAsset(AssetDatabase.GetAssetPath(material), "Assets/NewFolder/MyMaterialNew.mat");
        if(ret == "")
            Debug.Log("Material asset moved to NewFolder/MyMaterialNew.mat");
        else
            Debug.Log(ret);
        
        // Copy
        if(AssetDatabase.CopyAsset(AssetDatabase.GetAssetPath(material), "Assets/MyMaterialNew.mat"))
            Debug.Log("Material asset copied as Assets/MyMaterialNew.mat");
        else
            Debug.Log("Couldn't copy the material");
        // Manually refresh the Database to inform of a change
        AssetDatabase.Refresh();
        Material MaterialCopy = AssetDatabase.LoadAssetAtPath("Assets/MyMaterialNew.mat", typeof(Material)) as Material;
        
        // Move to Trash
        if(AssetDatabase.MoveAssetToTrash(AssetDatabase.GetAssetPath(MaterialCopy)))
            Debug.Log("MaterialCopy asset moved to trash");
        
        // Delete
        if(AssetDatabase.DeleteAsset(AssetDatabase.GetAssetPath(material)))
            Debug.Log("Material asset deleted");
        if(AssetDatabase.DeleteAsset("Assets/NewFolder"))
            Debug.Log("NewFolder deleted");
        
        // Refresh the AssetDatabase after all the changes
        AssetDatabase.Refresh();
    }
}

Asset Database version

This documentation refers to the version 2 of the Asset Database, which is the default in new Projects created with Unity 2019.3 or newer. The legacy version (version 1) was the default in earlier versions of Unity, which behaves in a different way. If you want to import an older Project into Unity 2019.3 or newer, you can choose to upgrade to the new Asset Database to get the benefits of the newer version.

You can switch between the legacy (v1) or current (v2) mode in your Project’s settings. Go to Edit > Project Settings to open the Project Settings window. Then select the Editor section on the left, and find Asset Pipeline in the list of settings on the right. You can then change the version using the Mode dropdown.

Importing local Asset packages

Refreshing the Asset Database