Creating custom importers

To add your own support for file formats that aren’t natively supported by Unity, you can use a ScriptedImporter to write custom asset importers in C#.

A scripted importer is a class that inherits from the abstract class ScriptedImporter and has the [ScriptedImporter] attribute. This registers your custom importer to handle one or more file extensions. When Unity detects a file that matches the registered file extensions as being new or changed, it invokes the method OnImportAsset of your custom importer.

Important: Scripted importers can’t handle a file extension that Unity already natively handles. You can use the overrideExts parameter to override this behavior and add the file extension for the existing importer. For a list of files Unity natively supports, refer to Supported asset type reference.

Once you have added a ScriptedImporter script to a project, you can use it the same way as any other file type supported by Unity. For more information, refer to Introduction to importing assets.

Create a scripted importer

The following code example imports asset files with the extension cube into a prefabAn asset type that allows you to store a GameObject complete with components and properties. The prefab acts as a template from which you can create new object instances in the scene. More info
See in Glossary with a cube primitive as the main asset and a default material and color. It then assigns its position from a value read from the asset file:

using UnityEngine;
using UnityEditor.AssetImporters;
using System.IO;

// The importer is registered with Unity's asset pipeline by placing the ScriptedImporter attribute on the
// CubeImporter class. The CubeImporter class implements the abstract ScriptedImporter base class.

[ScriptedImporter(1, "cube")]
public class CubeImporter : ScriptedImporter
{
    public float m_Scale = 1;

    // The ctx argument contains both input and output data for the import event

    public override void OnImportAsset(AssetImportContext ctx)
    {
        var cube = GameObject.CreatePrimitive(PrimitiveType.Cube);
        var position = JsonUtility.FromJson<Vector3>(File.ReadAllText(ctx.assetPath));

        cube.transform.position = position;
        cube.transform.localScale = new Vector3(m_Scale, m_Scale, m_Scale);

        // 'cube' is a GameObject and is automatically converted into a prefab.
        // Only the 'Main Asset' is eligible to become a prefab.
        ctx.AddObjectToAsset("main obj", cube);
        ctx.SetMainObject(cube);

        var material = new Material(Shader.Find("Standard"));
        material.color = Color.red;

        // Assets must be assigned a unique identifier string consistent across imports.
        ctx.AddObjectToAsset("my Material", material);

        // Assets that are not passed into the context as import outputs must be destroyed.
        var tempMesh = new Mesh();
        DestroyImmediate(tempMesh);
    }
}

For more information, refer to the AssetImporters.ScriptedImporter API documentation.

Create a custom import settings window

To create a custom import settings window for your scripted importer, create a class that inherits from ScriptedImporterEditor and decorate it with the [CustomEditor] attribute. For example:

using UnityEditor;
using UnityEditor.AssetImporters;
using UnityEditor.SceneManagement;
using UnityEngine;

[CustomEditor(typeof(CubeImporter))]
public class CubeImporterEditor: ScriptedImporterEditor
{
    public override void OnInspectorGUI()
    {
        var colorShift = new GUIContent("Color Shift");
        var prop = serializedObject.FindProperty("m_ColorShift");
        EditorGUILayout.PropertyField(prop, colorShift);
        base.ApplyRevertGUI();
    }
}

Examples of scripted importers

Unity uses scripted importers for the following file formats:

• Alembic: The Alembic package uses a scripted importer to import .abc file types.
• Universal SceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
  See in Glossary Description (USD): The USD Importer package uses a scripted importer to import .usd file types.

Additional resources

• ScriptedImporter API reference
• Supported asset type reference
• Introduction to importing assets