Unity PropertyAttribute – Wie man eine Hilfe-Box im Unity Inspector Window implementiert

Bei vielen Unity-Komponenten sieht man im Inspector kleine Text-Boxen mit Beschreibung der Komponente oder deren Properties. Wir zeigen, wie man das macht.

In Unity sind bereits einige nützliche Attribute integriert, um seine Komponente im Inspector benutzerfreundlich darzustellen (z.B. Header, Tooltip, Space). Manchmal genügt aber ein Tooltip nicht und man möchte dem Benutzer mehr Informationen dazu anzeigen, wie man die Komponente verwendet. So wie in folgendem Beispiel.

Von Haus aus gibt es so ein Help-Attribute in Unity nicht, bei GitHub gibt es aber eine Implementierung von Benutzer johnearnshaw: unity-inspector-help.

„Unity has these awesome little info boxes you may see popping up in the IDE, they can have a little icon and display helpful information for the IDE user to see. I thought it would be nice for the Unity guys to make it publicly available to use as an Attribute. I couldn’t find it anywhere so I rolled my own for personal use and I’m releasing it under MIT license. Feel free to use it in your projects commercial or non-commercial.“ [johnernshaw]

Installation und Verwendung

Dazu lädt man sich einfach die HelpAttribute.cs herunter und legt diese irgendwo in die Assets des Unity-Project.
Dann kann man das Attribute einfach im eigenen Code verwenden.

[Help("This is some help text!")]
float inspectorField = 1440f;

Das komplette Skript zur oben dargestellten Komponente würde dann so aussehen.

using UnityEngine;

namespace Computerhalbwissen {
  public class HalbwissenHelper : MonoBehaviour {
    private const string largeDescription = "Das ist eine Textbox, die man in vielen Komponenten verschiedener Assets sieht.\n" +
    "Sie kann zur Beschreibung der Komponente und deren Properties verwendet werden.\n" +
    "Optional kann man sogar ein Icon angeben.";

    [Header("Component Settings")]
    [Help(largeDescription, UnityEditor.MessageType.Info)]

    public float value1;
    public float value2;
  }
}

Icons

Standardmäßig wird das Info-Icon angezeigt, man kann dem Attribut aber als zweiten Parameter auch ein anderes Icon mitgeben oder gar keins. Der zweite Parameter sollte nur innerhalb einer #IF UNITY_EDITOR Anweisung stehen.

#if UNITY_EDITOR
[Help("Textbox mit Error-Icon", UnityEditor.MessageType.Error)]
#endif
public float value3;

#if UNITY_EDITOR
[Help("Textbox mit Warning-Icon", UnityEditor.MessageType.Warning)]
#endif
public float value4;

#if UNITY_EDITOR
[Help("Textbox ohne Icon.\nZeilenumbrüche lassen sich mit '\\n' erzwingen. \n\nSo lassen sich z.B. auch Listen darstellen\n- Element 1\n- Element 2", UnityEditor.MessageType.None)]
#endif
public float value5;

So sehen diese Boxen dann aus.

Einschränkungen

Wie bei anderen PropertyAttributes gibt es auch hier einige Einschränkungen und Konflikte. So funktioniert das Attribute für die meisten primitiven Feldtypen (bool, int, float, etc). Bei verschachtelten Properties, also alle, die über einen Dropdown-Pfeil verfügen (Arrays, Listen), funktioniert das Attribute nicht, sowie in Kombination mit einigen anderen PropertyAttributen, z.B. Multiline und Range.

Fazit

Trotz Einschränkungen eine tolle Sache. Einfach zu implementieren. Einfach anzuwenden. Genau das, was ich brauche, um die Funktionsweise einer Komponente im Inspector beschreiben zu können.

Ich hoffe wie immer, diese erstbeste Anleitung war hilfreich.

 

---

Quellen:

• unity-inspector-help bei GitHub
• Beitrag im Unity-Forum