Extending Unity with Editor Scripting: Put Unity to use for your video games by creating your own custom tools with editor scripting

An editor script is any piece of code that uses methods from the UnityEditor namespace, and its principal objective is to create or modify functionalities in the Unity editor.

To see this working, let's start with a basic example. Create a new project in Unity and then a new script called HelloWorld.cs. Don't worry about where to place the script, we'll talk about that in a bit. Copy the following code:

using UnityEngine;
using UnityEditor;

public class HelloWorld {
    
    [MenuItem ("GameObject/Create HelloWorld")]
    private static void CreateHelloWorldGameObject () {
        if(EditorUtility.DisplayDialog(
            "Hello World", 
            "Do you really want to do this?", 
            "Create", 
            "Cancel")) {
            new GameObject("HelloWorld");
        }
    }
}     

Wait for the compiler to finish and then go to the Unity editor menu and click on GameObject. At the end of the menu, you will see an item called Create HelloWorld, as shown in the following screenshot:

Click on this item, then a dialog window asks whether you really want to create this game object:

After clicking on Create, a new game object with the name HelloWorld is added to the current scene. You can check this in the Hierarchy window:

You created your first editor script using two things:

Don't worry, we will discuss these in depth later in this book. For now, we are going to move forward and discuss something very important in the creation of editor scripts: the Editor folder.

The Editor folder is one of the special folders Unity has, just like the Resources or Plugins folders.

Like the Unity documentation says, all scripts inside a folder with the name Editor will be treated as editor scripts rather than runtime scripts related to your video game. Also, you can have more than one Editor folder in your project at once if you want.

If you have at least one Editor folder with a script inside, you will see something like the following in MonoDevelop (in other IDEs, such as Visual Studio or Xamarin, you may see something slightly different, but the concept is the same):

Two different assemblies will be created: the first assembly, Assembly-CSharp, is for your video game scripts and the second assembly, Assembly-CSharp-Editor, is for your editor scripts. This means that the editor scripts will not be included in your final video game build.

So, what is the problem with HelloWorld.cs? Well, right now it' s not inside an Editor folder, so if you try to build a video game with that script included, the build process will fail because Unity won't be able to find the namespace named UnityEditor:

Most of the editor scripts that we will discuss in this book, like custom inspectors in Chapter 3, Creating Custom Inspectors, or editor windows in Chapter 4, Creating Editor Windows require being saved inside an Editor folder in order to work. However, in some situations, it is possible to achieve this without using the Editor folder.

Let's fix the original HelloWorld.cs file to work outside an Editor folder. In this case, we must tell the compiler to not include the editor-related code if we are making a video game build.

To achieve this, we will use the preprocessor directives #if and #endif with the conditional compilation symbol UNITY_EDITOR. Using both together, we can tell the compiler to exclude a block of code when we create a video game build.

Update HelloWorld.cs as follows:

using UnityEngine;
#if UNITY_EDITOR
using UnityEditor;
#endif
public class HelloWorld {
    
    #if UNITY_EDITOR
    [MenuItem ("GameObject/Create HelloWorld")]
    private static void CreateHelloWorldGameObject () {
        if(EditorUtility.DisplayDialog(
            "Hello World", 
            "Do you really want to do this?", 
            "Create", 
            "Cancel")) {
            new GameObject("HelloWorld");
        }
    }
    #endif
    
    // Add your video game code here
}

If you feel a little overwhelmed, just keep in mind that the last script example is an exception, and as a guideline, all the editor scripts must be inside an Editor folder. to keep everything organized and working

In this video game, the player takes control of Timmy, a guy who likes to collect coins and invests his time searching for hidden treasures. On his journey, he needs to avoid obstacles and enemies to reach the finale of each level and win. You can see how the video game looks in the following screenshots:

To play the video game, you will have to clone or download the project from https://github.com/angelotadres/RunAndJump in GitHub.

When you are ready, open the project in Unity. You will see the following folder structure in the Project browser:

To test the game, open the scene Title inside the Scenes folder and then press the Play button in the Unity toolbar:

To control Timmy, use the left and right arrows on your keyboard. Pressing the space bar makes him jump, and pressing it again while he is in the air makes him perform a double jump.

Currently, there are three levels implemented for this video game to test its functionality. In the next section, you will learn how to add more levels.

In this video game, each level is a Unity scene inside the folder Levels. When you start playing Run & Jump and then select a specific level, the video game call the LevelHandler scene and this starts the script LevelHandlerScene.cs.

This scene has all the GUI necessary for the level, and the script is responsible for the game's status detection (playing, paused, and so on), when the player wins or loses, and loading of the specific level scene using the method Application.LoadLevelAdditive.

Each level scene is composed of several prefabs. We will refer to these in the rest of the book as level pieces prefabs.

Navigate to Prefabs | LevelPieces to check the available level piece prefabs. The following table contains a description of each one:

Level Piece	Description
	Timmy (Player.prefab): You control this character in the game. Timmy's abilities are run, jump and double jump. There's nothing to envy about the Italian plumber.
	Angry Blob (EnemyAngryBlob.prefab): This character moves over platforms from one side to the other with an angry face. You don't like him and he doesn't like you so don't touch him or you will lose a life!
	Coins (InteractiveCoin.prefab): It is not a real platform video game without something to collect. Coins are one of the collectibles, and when you pick one, your score increases by 100 points.
	Treasure (InteractiveTreasure.prefab): Usually, this collectable is well hidden in order to motivate the player to explore the level. When you pick one, your score increases by 1,000 points.
	Sign (InteractiveSign.prefab): This will display a message on the screen when the player is around the sign board. The sign is used to give the player hints or miscellaneous information about the current level.
	Spikes (HazardSpike.prefab): These sharp spikes are placed in locations that make it harder to reach your objective. Don't touch them or you will lose a life!
	Dirt (SolidDirt.prefab): This is used as a building block for the level.
	Grass (SolidGrass.prefab): Like Dirt, this too is used as a building block for the level. The only difference is this it's green on the top.
	Goal flag (InteractiveGoalFlag.prefab): The main objective of the video game is to reach the Goal flag at the end of each level. A well-designed level will have a lot of hazards and enemies between you and the goal flag.

To get a better understating of what is involved in creating levels, let's create a new one. The goal is to copy the following level (or at least try to do so):

For this, you need to perform the following steps:

Run & Jump comes with a custom tool that allows you to set up the order and the name of the levels and also add these to the Scenes in Build list automatically. We must use this in order of make our level usable by the video game (one of the requirements is to include the suffix _level in the name of the scene).

In the Unity editor menu, navigate to Tools | Level Packager | Show Levels Package:

This will display the following in the Inspector window:

Currently, there are only three levels listed, so click on the + icon to create a new item in the list. Now, add the scene you created in right column and add the string My Level in the left column. This will add your level as the fourth one.

Save the changes by clicking on the Commit Levels button.

To check the scene you created, open the scene Title inside the Scenes folder, and then click on the Play button to run the video game:

Now you know the necessary amount of effort it takes to create a level for this game; so let's make this level creation process the first thing to improve.

In the rest of this chapter, we will work on the first scripts of the Level Creator tool in order to automate the creation of a scene capable to be used as a level.

The goals here are:

We need to create a few folders to keep our development organized. Remember, for this entire book, we are working on the Run & Jump project.

You will find a folder called Tools in the root of the project. Right now this folder has one inside with the scripts of the tool we used to add our levels to the game.

Inside the Tools folder, create a new folder called LevelCreator and then match the folder structure, as shown in the following screenshot:

This folder structure is just a suggestion, but you must always consider creating a root folder for your custom tools.

As we were saying, we want to create a scene capable to be used as a level, but instead doing this manually in Unity, we are going to achieve the same using code.

We are going to implement a few methods to do this. Inside the folder Tools/LevelCreator/Editor, create a new script called EditorUtils.cs and add the following code:

using UnityEngine;
using UnityEditor;
using System.Collections.Generic;

namespace RunAndJump.LevelCreator {
  public static class EditorUtils {
        
    // Creates a new scene
    public static void NewScene () {
      EditorApplication.SaveCurrentSceneIfUserWantsTo ();
      EditorApplication.NewScene ();
    }

    // Remove all the elements of the scene
    public static void CleanScene () {
      GameObject[] allObjects = Object.FindObjectsOfType<GameObject> ();
      foreach (GameObject go in allObjects) {
        GameObject.DestroyImmediate (go);
      }
    }

    // Creates a new scene capable to be used as a level
    public static void NewLevel () {
      NewScene ();
      CleanScene ();
      GameObject levelGO = new GameObject ("Level");
      levelGO.transform.position = Vector3.zero;
      levelGO.AddComponent<Level> ();
    }
  }
}

The NewLevel method is the one that executes all the work using the help of the following two methods:

Similar to the HelloWorld example we created at the beginning of this chapter, we need to make the NewLevel method accessible through the Unity editor menu using the MenuItem attribute.

Inside the folder Tools/LevelCreator/Editor, create a new script called MenuItems.cs. We will use this to add all the future menu items that the tool requires; for now, add the following code:

using UnityEngine;
using UnityEditor;

namespace RunAndJump.LevelCreator {
  public static class MenuItems {
        
        [MenuItem ("Tools/Level Creator/New Level Scene")]
        private static void NewLevel () {
            EditorUtils.NewLevel ();
        }
    }        
}

Now, the NewLevel method will be available when you navigate to Tools | Level Creator | New Level Scene. Save all the scripts changes and for Unity to compile, then click on New Level Scene:

A dialog window will ask you whether you want to save the current changes of the scene (if this one has modifications):

After this, a new scene will be created with the game object containing the level script:

Congratulations! We have the starting point for the Level Creator tool creating a level scene with just one click!