Saturday, February 15, 2014

Custom file templates for Unity+MonoDevelop

So after being rewriting the same code once and again and again from Unity's (and/or MonoDevelop's) templates just to start working on my own code, I decided to create my very own templates. Looking through the web I found a great addin by Robert 'Quazistax' Benko, open for everyone to play with. My needs and coding style are a bit different, and Unity has changed quite much since the day he wrote them (back in 2011).

You will notice there's an insane amount of comments in them. I'm a maniac when it comes to keep the code documented, and have been a long-time fan of Doxygen and similar documentation standards (.NET XML, JavaDoc...). By far most of the docs are copy-pasted from the official Unity docs, as it's nice to have a reminder of what does everything and their (many) caveats.

Most likely, I will update this addin from time to time as I see fit (probably to add recurring similar-but-different components, shaders, etc.)

Download

You can download the addin with the templates here.

Installation

On Windows, I've installed it in the folder Unity_Installation_Path/MonoDevelop/Addins. Just paste the folder contained in the package there and restart MonoDevelop.

On MacOSX I haven't tried yet. Quazistax states in his post that the installation folder is Contents/MacOS/lib/monodevelop/AddIns in the MonoDevelop application package.

For the details on the installation and how to solve certain (sporadic) problems refer to his original post.

How to use them

Under the file creation dialog in MonoDevelop, if the addin was successfully installed, you will find a new category to the left: Kencho\Unity\C#. Let me explain you what they're for and why.

  • C# class
    This is a simple minimalistic C# class. It's useful when you want to create your own types, particularly if you want them decoupled from Unity.
  • C# Attribute class
    To make your own C# attributes adding semantic meaning to your own types without adding coupling to Unity.
  • C# Exception class
    I think this is self-explanatory. Useful when you want to create your custom exception type to handle errors in runtime.
  • Unity MonoBehaviour (Full)
    A complete template for Unity components. This template will add handlers to all the messages a MonoBehaviour can receive. Most of the time you will only use a subset of them, so remove any handler that you won't need.
  • Unity MonoBehaviour (Advanced)
    This is a subset of the previous template. It only includes the handlers for commonly used messages, like the updating, enabling/disabling of the component, physics and user interaction (through the mouse). You'll want to use this template for the game object with a somewhat complex behavior.
  • Unity MonoBehaviour (Basic)
    An even more reduced subset of the previous template. Adds the most common operations (Awake, Start, Update and FixedUpdate), and is recommended for simplistic game objects, like particle systems or other non-interactive elements.
  • Unity MonoBehaviour (Very Basic)
    The most reduced subset of the MonoBehaviours. Even the documentation is reduced! The equivalent to the default Unity's "new script" template (using my style and encapsulating it into a namespace)
  • Unity Property attribute class
    It's a specialized attribute recognized by Unity (and thus, coupled to it). Useful to add custom semantic to MonoBehaviour properties (it's a new feature added with Unity 4 which also includes a few ones, like Range(min, max) to declare that a property should stay between two fixed values). Specially useful if used with a custom PropertyDrawer (see below).
  • [Editor] Unity Editor
    Base to create custom Unity editors (inspectors) for components. By default behaves like the default inspector. Classes based on this template can only be used in editor mode, and must be included in an Editor folder.
  • [Editor] Unity Editor Window
    To create custom editor windows, like utility windows or floating/panel windows to extend the functionality of the editor. Classes based on this template can only be used in editor mode, and must be included in an Editor folder.
  • [Editor] Unity Property Drawer
    This one comes in two variants. One is used to add a GUI to custom serializable classes that doesn't have an inspector themselves. The other is to add a GUI to properties tagged with a certain PropertyAttribute. It was introduced in Unity 4 and can read more about it here and here. Classes based on this template can only be used in editor mode, and must be included in an Editor folder.