Getting Started

This introductory section is essentially Odin 101; it will get you started with Odin, and tell you everything you need to know to become a proficient user. It will in general skip over the deeper technical details, and instead aims to give you an overview over Odin's out-of-the-box capabilities and how to use them.

Power-users aiming to extend Odin, or those who simply wish to understand Odin's underlying systems more thoroughly, are advised to read this introductory section, and then proceed to the in-depth technical sections Drawers in Depth and Serialization in Depth.

And of course, if you're in need of knowledge about a more specific class or method in Odin, you can always look it up in the documentation.

Odin is supported in Unity from version 5.3 and up; it will not work in 5.2 and below.

Installation

For now, Odin is installed using Unity's standard .unitypackage format. Installation is very straightforward; simply unpack the entire package into your project, then wait for the editor to load all of the assemblies - Odin will then be installed. If Unity asks you whether to make an API upgrade, go ahead and do so. After this, you may take the Sirenix folder which contains Odin and its assemblies, and place it anywhere you please in your project; Odin will automatically detect where it is placed in the project. By default, it will be placed in the Plugins folder.

Do note that it is extremely inadvisable to change the internal structure of the Sirenix folder itself or renaming the folder in any way; this will in rare cases cause Odin to be unable to find its location in the project, and result in assets being generated in unwanted locations.

Using Odin with source control

Odin is perfectly compatible with common source control systems. It may, however, be advisable to ignore the contents of the Sirenix/Assemblies/AOT folder, as this may contain generated .dll's for AOT compatibility that you do not want to track in your source control system. This is, however, mostly a question of preference.

In older versions of Odin (1.0.4.1 and down) there are a few files which Odin continuously regenerates, and while it causes no harm to include these in your source control, it is best to ignore them and leave them as local files only, since they will be changing constantly. We advise that you upgrade Odin to a newer version where this doesn't happen, but if, for some reason, you can't, then the files in question are located in the Sirenix/Assemblies/Editor folder, and are called GeneratedOdinEditors.dll and GeneratedOdinEditors.mdb. You should also ignore the associated .meta files, if you are working in a project with those enabled.

Editor Only Mode: using Odin without the special serialization

Odin's custom serialization is supported on all platforms but the non-IL2CPP Universal Windows Platform build target (.NET Core), and lets you use dictionaries, interfaces and more in the inspector. However, not all projects are in need of this, and for IL2CPP builds, including the serialization assemblies can increase your build size, since the serialization assemblies will not have code stripping performed on them. Odin is built in a modular fashion, and it is possible to completely remove Odin's serialization system from all of your builds, if you are using Odin in its compiled .dll form and not as source files. This also lets you target UWP in versions 1.0.5 and up.

In versions 1.0.5 and up, Odin includes a special Editor Only Mode. To remove the serialization system, go to Tools -> Odin Inspector -> Preferences -> Editor Only Mode and click the "Enable Editor Only Mode" button.

In versions 1.0.4.1 and down, you must delete the following files and folders from Odin:

  • Sirenix/Assemblies/link.xml
  • Sirenix/Assemblies/NoEditor/Sirenix.Serialization.dll
  • Sirenix/Assemblies/NoEditor/Sirenix.Serialization.mdb
  • Sirenix/Assemblies/NoEditor/Sirenix.Serialization.pdb
  • Sirenix/Assemblies/NoEmitNoEditor/Sirenix.Serialization.dll
  • Sirenix/Assemblies/NoEmitNoEditor/Sirenix.Serialization.mdb
  • Sirenix/Assemblies/NoEmitNoEditor/Sirenix.Serialization.pdb
  • Sirenix/Demos/Odin Inspector (Many demo scripts reference the serialization system, and will cause build errors)

Once you have done this, Odin's serialization system will no longer be included when you build a player.

Note that the serialization system will still be present in the editor, and you will be able to use it in the editor. However, if you reference it anywhere in build code, you will get compiler errors once you attempt to build a player, and you will have to remove those references before you are able to build a player.

Using Odin's source in your project

If you have a distribution of Odin with the source included, you will find a Source.zip file containing Odin's full source code in Sirenix/Source.

Odin supports being used as source, instead of as assemblies, from version 5.3.7 of Unity and up (with assemblies, Odin supports 5.3.0 and up).

If you wish to use the source in your project, first install Odin regularly.

If you have already configured Odin and changed its config asset files (found in Sirenix/Odin Inspector/Config), this configuration may be lost and your config asset files may become corrupt and have to be deleted. In order to preserve this configuration, you must ensure that you are forcing Unity to serialize using its text format. You may find this option at Edit -> Project Settings -> Editor -> Asset Serialization -> Mode; set it to Force Text. When this option is enabled, Odin will automatically fix the config assets for you after a script reload has happened.

After you have done this, delete the Sirenix/Assemblies folder, and unzip the source file. Apart from the source itself, you will find an unzipped folder called MoveFilesToRoot. Take the contents of that folder (csc.rsp, gmcs.rsp and smcs.rsp), and move them to the root asset folder of your project. These files contain compilation settings for allowing Odin to be compiled, as Odin uses unsafe code to speed up its binary serialization. If you already have some or all of these files in your project, you will have to merge them, or otherwise change your own files to enable unsafe compilation in your project.

After you have done this, and Unity has recompiled, you may get some messages about config asset m_Script guids being corrected. This is fine - Odin is ensuring that your old configuration assets are still usable. If you instead get warning messages about being unable to load configs, and m_Script guids being corrupt, see the above note about retaining your Odin configuration for how to resolve this issue.

After this, you may move the source wherever you wish, so long as it is still in a subfolder of Sirenix. As with assemblies, you may still place the Sirenix folder wherever you wish in your project, though it is advisable to keep it as a subfolder of Plugins, to cut down your compilation time when working on game code. (See Unity Special Folder Names.)

Working with Odin

Once you've installed Odin, the main difference you'll notice is that your inspector will look a little nicer. Lists and arrays in particular will have undergone quite an upgrade; list elements are now draggable, long lists have paging, and so on. You now have a right-click context menu for every property in the inspector, that provides contextual actions for that property, such as copying and pasting, resetting changed prefab values to their original, and so on.

Odin offers you many options to configure where it applies. In its default configuration, Odin applies itself to all types that do not already have a custom editor defined, but you can adjust this in the advanced preferences for Odin, under Tools -> Odin Inspector -> Preferences -> Editor Types.

Once a component is being drawn by Odin, it integrates seamlessly into your pre-existing Unity workflow. There's no boilerplate code, and no complicated setup - it all just works out of the box. You still create your fields, decorate them with attributes, and edit them in the inspector.

However, with Odin, you now have a vast array of choices to configure how your inspector looks and acts, with dozens of built-in attributes and great ease of extendability. Furthermore, if you inherit from one of our specially serialized classes, such as SerializedMonoBehaviour, you can use fields of any type; those not serialized by Unity will be serialized by Odin instead.