In this article, we’ll develop a custom editor tool to streamline placing objects in the scene. We’ll cover several helpful editor APIs, including EditorTool, PrefabUtility, Handles and HandleUtility.<\/p>\n\n\n\n
As mentioned, we’re building a tool to streamline placing objects in the scene. I want to drop an object every time I click. The object can either be a prefab or a clone of a GameObject from the scene. So, we’ll need a field to specify which thing we’re placing. Finally, I’d like to select a new object by right-clicking to pick the GameObject under the mouse cursor.<\/p>\n\n\n\n
Given these requirements, we’ll build a simple tool. I hope this process demonstrates how to make quick and dirty tools to streamline your workflows and increase productivity. When you build tools like this, it’s ok for them to be rough. The goal is to create something that benefits our project, not make a generic commercial tool. Project-specific tools are significantly faster to write. Additionally, when you tailor a tool to your needs, it can outperform generic tools.<\/p>\n\n\n\n
So let’s build!<\/p>\n\n\n\n
There are several ways to extend the Unity Editor. For this particular tool, I chose the Here’s our barebones script starting point.<\/p>\n\n\n\n By the way, you can override Let’s start by blocking out what we want to do.<\/p>\n\n\n\n Some of this work is more complicated than it seems, so let’s take it one step at a time.<\/p>\n\n\n\n First, we’ll ensure the preconditions are met.<\/p>\n\n\n\n Pay attention to the ToolManager.IsActiveTool, because the Next, let’s draw a circle at the current mouse position in world space.<\/p>\n\n\n\n We’ll use the Here we pass in a position, normal and radius for wireframe disc. To calculate the position, I wrote a helper function that returns the position at which an object would spawn if we were to drag it into the scene. In other words, if it finds a surface, it’ll snap to it, and otherwise, it’ll choose a position in space.<\/p>\n\n\n\n Here we see another valuable class: The next step is to instantiate our selected object. There are a couple of cases to handle. If the selected object is a prefab or belongs to a prefab, we’ll instantiate a linked prefab. Otherwise, we’ll instantiate a clone of the original game object. Append this code after the There are couple of unfamiliar fields here: So we take the selected object and check if it’s part of a prefab. If it is, we get the path to the prefab asset, load the prefab asset, and instantiate it. Otherwise, we instantiate a regular game object clone. After instantiating the object, set its position to the mouse position. To be a good editor citizen, we notify the Finally, we The last step in The reason is that the Scene View doesn’t automatically update at a real-time frame rate, like 60fps. Instead, it updates whenever it receives an event worthy of an update. We want our tool to feel responsive, so we’ll repaint as long as it’s the active tool.<\/p>\n\n\n\n Here’s the entire There’s a lot more to cover, but this is a good place for a break. Since the code in this post alone won’t be enough to compile, I shared the complete tool at the end. You can explore the finished code and try the tool while I write the next section.<\/p>\n\n\n\n So in this post, we learned about some useful APIs to build Editor tools, including Check out the finished project <\/strong>here<\/strong><\/a> on Github. If you want to be notified when the next part is released, <\/strong>join my mailing list<\/strong><\/a>.<\/strong><\/strong><\/p>\n","protected":false},"excerpt":{"rendered":" In this article, we’ll develop a custom editor tool to streamline placing objects in the scene. We’ll cover several helpful editor APIs, including EditorTool, PrefabUtility, Handles and HandleUtility. What’s the goal? As mentioned, we’re building a tool to streamline placing objects in the scene. I want to drop an object every time I click. The […]<\/p>\n","protected":false},"author":1,"featured_media":491,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[43,1],"tags":[45,44,8,5],"class_list":["post-488","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-editor-tools","category-unity-programming","tag-editor-scripting","tag-editor-tools","tag-game-development","tag-unity"],"_links":{"self":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts\/488","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/comments?post=488"}],"version-history":[{"count":3,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts\/488\/revisions"}],"predecessor-version":[{"id":492,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts\/488\/revisions\/492"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/media\/491"}],"wp:attachment":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/media?parent=488"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/categories?post=488"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/tags?post=488"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}EditorTool<\/code> API. Subclassing EditorTool<\/code> creates a new tool in the main toolbar. By that, I mean the toolbar containing the Move, Rotate, Scale, Hand, etc. Since our tool relies on the left and right mouse buttons to function, it makes sense to make it an EditorTool<\/code>; otherwise, we’d fight with whichever tool the user has selected at any given moment. So, create a new class called PlaceObjectsTool<\/code> that inherits from EditorTool. By the way, since this is for Editor use only, you must put the script file in a folder called “Editor”. Doing so prevents the script from being compiled into builds of the project, which would fail because we rely on several Editor-only APIs.<\/p>\n\n\n\nusing System;\nusing UnityEngine;\nusing UnityEditor;\nusing UnityEditor.EditorTools;\n\n[EditorTool(\"Place Objects Tool\")]\nclass PlaceObjectsTool : EditorTool\n{\n [SerializeField] Texture2D _toolIcon; \n GUIContent _iconContent;\n\n void OnEnable()\n {\n _iconContent = new GUIContent()\n {\n image = _toolIcon,\n text = \"Place Objects Tool\",\n tooltip = \"Place Objects Tool\"\n };\n }\n\n public override GUIContent toolbarIcon\n {\n get { return _iconContent; }\n }\n\n public override void OnToolGUI(EditorWindow window)\n {\n }\n}<\/code><\/pre>\n\n\n\ntoolbarIcon<\/code> to give your tool an icon, but I won’t bother. Aside from that, the most important method is OnToolGUI<\/code>. This method is essentially the EditorTool<\/code> equivalent of Update<\/code> in that it runs every time an editor window repaints.<\/p>\n\n\n\nOnToolGUI<\/h2>\n\n\n\n
public override void OnToolGUI(EditorWindow window)\n{\n \/\/If we're not in the scene view, exit.\n if (!(window is SceneView))\n return;\n\n \/\/If we're not the active tool, exit.\n if (!ToolManager.IsActiveTool(this))\n return;\n\n \/\/If we don't have a placeable object, exit.\n if (!HasPlaceableObject)\n return;\n...<\/code><\/pre>\n\n\n\nToolManager<\/code> is a valuable class when writing EditorTools. Here we’re using it to make sure our tool is the active tool. The reason we do this is that the editor could continue to call OnToolGUI<\/code> on our tool after being initialized, even if it’s not currently the actively selected tool. There’s also a HasPlaceableObject<\/code> property that we’ll return to later.<\/p>\n\n\n\nThe Handles API<\/h2>\n\n\n\n
Handles<\/code> class to draw our GUI in the Scene View. If you haven’t used Handles<\/code> before, you’re in for a treat. This class contains many ways to draw debug tools in the Scene View, including shapes, lines, labels, and existing Unity tools like the Move, Scale and Rotate tools. I highly encourage you to check it out. So follow up the previous line of code with this.<\/p>\n\n\n\n\/\/Draw a positional Handle.\nHandles.DrawWireDisc(GetCurrentMousePositionInScene(), Vector3.up, 0.5f);\n\n...<\/code><\/pre>\n\n\n\nVector3 GetCurrentMousePositionInScene()\n{\n Vector3 mousePosition = Event.current.mousePosition;\n var placeObject = HandleUtility.PlaceObject(mousePosition, out var newPosition, out var normal);\n return placeObject ? newPosition : HandleUtility.GUIPointToWorldRay(mousePosition).GetPoint(10);\n}<\/code><\/pre>\n\n\n\nHandleUtility<\/code>. This class contains tons of utility functions that are the backbone of the built-in Scene View tools. So using HandleUtility<\/code> does the heavy lifting and keeps your tools consistent with the built-in ones.<\/p>\n\n\n\nObject Instantiation<\/h2>\n\n\n\n
DrawWireDisc<\/code> line.<\/p>\n\n\n\n\/\/If the user clicked, clone the selected object, place it at the current mouse position.\nif (_receivedClickUpEvent)\n{\n var newObject = `_prefabObjectField.value;\n\n GameObject newObjectInstance;\n if (PrefabUtility.IsPartOfAnyPrefab(newObject))\n {\n var prefabPath = PrefabUtility.GetPrefabAssetPathOfNearestInstanceRoot(newObject);\n var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(prefabPath);\n newObjectInstance = (GameObject)PrefabUtility.InstantiatePrefab(prefab);\n }\n else\n {\n newObjectInstance = Instantiate((GameObject)newObject);\n }\n newObjectInstance.transform.position = GetCurrentMousePositionInScene();\n\n Undo.RegisterCreatedObjectUndo(newObjectInstance, \"Place new object\");\n \n Event.current.Use();\n _receivedClickUpEvent = false;\n}<\/code><\/pre>\n\n\n\n_receivedClickUpEvent<\/code> and _prefabObjectField<\/code>. We’ll come back to these later. The main thing I want to introduce right now is the PrefabUtility<\/code> class. This class contains a bunch of prefab-related utility functions for the editor. For example, you can use PrefabUtility.InstantiatePrefab<\/code> to create a linked prefab in the scene instead of an unlinked game object clone.<\/p>\n\n\n\nUndo<\/code> system that we created a new object so Ctrl+Z will remove it.<\/p>\n\n\n\nUse()<\/code> the current event. By the way, calling Use()<\/code> on events is extremely important because it notifies the other editor systems to ignore the event. For example, when we receive a MouseUp<\/code> event, we want to place an object, but the Scene View selects the object under the mouse by default. So, by calling Use()<\/code>, we tell the Scene View to ignore it instead of picking an object.<\/p>\n\n\n\nOnToolGUI<\/code> is to repaint the window.<\/p>\n\n\n\n\/\/Force the window to repaint.\nwindow.Repaint();<\/code><\/pre>\n\n\n\nOnToolGUI<\/code> function.<\/p>\n\n\n\npublic override void OnToolGUI(EditorWindow window)\n{\n \/\/If we're not in the scene view, we're not the active tool, we don't have a placeable object, exit.\n if (!(window is SceneView))\n return;\n\n if (!ToolManager.IsActiveTool(this))\n return;\n\n if (!HasPlaceableObject)\n return;\n\n \/\/Draw a positional Handle.\n Handles.DrawWireDisc(GetCurrentMousePositionInScene(), Vector3.up, 0.5f);\n\n \/\/If the user clicked, clone the selected object, place it at the current mouse position.\n if (_receivedClickUpEvent)\n {\n var newObject = _prefabObjectField.value;\n\n GameObject newObjectInstance;\n if (PrefabUtility.IsPartOfAnyPrefab(newObject))\n {\n var prefabPath = PrefabUtility.GetPrefabAssetPathOfNearestInstanceRoot(newObject);\n var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(prefabPath);\n newObjectInstance = (GameObject)PrefabUtility.InstantiatePrefab(prefab);\n }\n else\n {\n newObjectInstance = Instantiate((GameObject)newObject);\n }\n newObjectInstance.transform.position = GetCurrentMousePositionInScene();\n\n Undo.RegisterCreatedObjectUndo(newObjectInstance, \"Place new object\");\n \n Event.current.Use();\n _receivedClickUpEvent = false;\n }\n\n \/\/Force the window to repaint.\n window.Repaint();\n}<\/code><\/pre>\n\n\n\nEditorTool<\/code>, PrefabUtility<\/code>, Handles<\/code> and HandleUtility<\/code>. We learned how to differentiate between plain Game Objects and Prefabs. We also learned how to instantiate a linked Prefab. Finally, we learned how to draw GUI in the Scene View. Later we’ll go deeper into editor events, build a simple GUI with UIToolkit and create a custom context menu.<\/p>\n\n\n\n