Unity3d is a great game engine to work with and gets more features added all the time. When the built in tools don't suffice there are even more ready made tolls available to download from different sources including Unity's Assets store and github.com. But what do you do when you cant find what you are looking for? The answer is easy: build your own. Unity3d has a quite extensive editor API designed for this purpose.


Purpose of the tool

We recently downloaded an asset pack from the Asset store filled with visual effects, specifically particle systems prefabs, to use in a game project but many of them did not comply with our desired format. Most of the effect hade an empty root object, containing only a transform component, and then had the actual particle system as a child. There is nothing fundamentally wrong with this setup but our special effects system requires a particle system to reside in the root of a special effects prefab. We also require each special effect to have a custom script attached to the prefab root, either

IndividualParticleSystemVisualEffect.cs
for non-looping effects or
ContionousParticleSystemVisualEffect.cs
for looping ones.

The goal of this tool is therefor to create a Unity Editor allowing us to see all prefabs, to preview them and see if any action is required, select it and finally removed the empty root if required and attach either of the two scripts.


Creating your own Unity tool from scratch

In this first part we will focus solely on creating and opening a custom editor window while leaving the UI design and all functionality to later posts.


Accessing Unity's Editor API.

For performance reason Unity has chosen to split their API up in several different parts. The Editor part of Unity is needed when playing the game and is therefor not included or accessible from normal game play code. All if Unity's Editor classes resides in the

UnityEditor
namespace (the core resides in
UnityEngine
) If you where to create a normal new MonoBehaviour derived class and try access UnityEditor, your compiler will give you an error trying to build the game saying
The type or namespace name 'Editor' could not be found (are you missing a using directive or an assembly reference?)
In order to get this to work you must place any editor extensions of tools in a folder namned Editor. You can create as many of these as you like and place them wherever you want in your project and Unity will pick them up and build them as part of the UnityEditor.


Unity builds into C# assemblies. The normal game play code is build into
Assembly-CSharp
and only depends on UnityEngine. Any .cs files found in an Editor folder is instead built into a separate assembly named
Assembly-CSharp-Editor
and depends on
UnityEngine
,
Assembly-CSharp
(you can access any code and classes you written as part of the gameplay code) as well as
UnityEditor
.


Getting started.

Now lets get started for real. Begin by creating a new folder named VfxFixingTool in the root folder of your Unity project. (You can of course name it whatever you want but this is where its expected to reside when referencing it ). In that folder create a new folder named Editor. This time its very important that the folder is actually named Editor (for the reason given in the previous paragraph). Here, lets create the editor script. Create a .cs file and name it

VfxFixingToolEditorWindow.cs
. Open the file with an editor of your choice and we can start writing the code.


We will begin by adding some Using statements at the top for namespaces we need (including

UnityEngine
and
UnityEditor
). We will also wrap the all the code in a namespace of our own to remove the possibilities of having name collisions with other packages. I'll use the namespace Fyrvall.VfxFixingTool. Fyrvall is my last name and pretty much ensures naming collisions are impossible as its a very uncommon last name. VfxFixing tool is of course the name the pool we're creating and its common in C# to wrap every code file in a package in a namespace named after the package. In this file create a single class named
VfxFixingToolEditorWindow
and make it inherit from Untity's built-in class
EditorWindow
. When getting started, make sure you code likes as below.

using System.Collections.Generic;
using UnityEngine;
using UnityEditor;
using System.Linq;
using UnityEditor.IMGUI.Controls;

namespace Fyrvall.VfxFixingTool
{
   public class VfxFixingToolEditorWindow : EditorWindow
   {
   }
}


Create a way to open the editor

In order to use our editor, we need to create a way to open it. We will add it to Unity's top bar menu under Window, where custom editor belongs. If you are making lots of custom tools for you project and don't intend to share them, you could create you own top level menu and pop them there instead.


The first step now is to set the name of our tool. By creating a constant variable with the name we can use it repeatadly and if we ever changes the name of this tool, we only need to change it in one place. Add the following line to the top of your VfxFixingToolEditorWindow class.

private const string EditorWindowName = "VFX Fix tool";


Add this code snipped right under it.

public static void OpenEditor()
{
    var window = EditorWindow.GetWindow<VfxFixingToolEditorWindow>();
    window.titleContent = new GUIContent(EditorWindowName);
    window.Show();
}

We've just created a public static method responsible for opening out editor. EditorWindow.GetWindow<T>() gets a reference to an existing instance of the editor specified or creates a new instance if none existed. This means only one instance of this editor window can be opened at the time. If you want Unity to create a new window instance every time use EditorWindow.CreateInstance<T>() instead (inherited from ScriptableObject). Once we have a reference to the window, we sets its title names. If we don't to this, the title will default to the class's fully qualified class name (Fyrvall.VfxFixingTool.VfxFixingToolEditorWindow) which is quite ugly. As title is GUIContent instance it can support icons as well. They need to be exactly 16 x 16 pixels large. To display the editor in Unity with a default window behaviour we use

EditorWindow.Show()
. There are other alternatives and I will show a few others in later posts. If you want to explore them yourself, look at Unity's own documentation.


Finally, we need to hook this static method into Unity's menu system via the MenuItemAttribute. By adding this attribute to out static method, Unity will create a new menu item and when that item is pressed this method will run and display our editor. Custom menu items can be really useful for other quick tiny tools and I suggest you remember it as an option. Add the following line just above the

OpenEditor
method.

[MenuItem("Window/" + EditorWindowName)]

Open Unity and let it compile. If you have done everything correct, in the top menu under Window you will find the new item VfxFixingTool, and pressing it will open your newly created, but still very empty, custom editor.


In the next post we will create a UI layout for the editor.


Complete code reference so far

using System.Collections.Generic;
using UnityEngine;
using UnityEditor;
using System.Linq;
using UnityEditor.IMGUI.Controls;

namespace Fyrvall.VfxFixingTool
{
   public class VfxFixingToolEditorWindow : EditorWindow
   {
       private const string EditorWindowName = "VFX Fix tool";

       [MenuItem("Window/" + EditorWindowName)]
       public static void OpenEditor()
       {
           var window = EditorWindow.GetWindow<VfxFixingToolEditorWindow>();
           window.titleContent = new GUIContent(EditorWindowName);
           window.Show();
       }
  }
}