Build a Context-Sensitive Help System in Unity That Doesn't Suck

Alright, let’s ditch the endless tutorials that tell you what to do and focus on how to truly build a context-sensitive help system in Unity that doesn’t suck. We’re not just slapping tooltips on things; we’re crafting an intuitive experience that empowers users, and more importantly, prevents rage quits. This means leveraging the power of ScriptableObjects for clean data management, creating a robust selection-based trigger, and building a UI that’s both functional and aesthetically pleasing.

The Power of ScriptableObjects for Help Text

Forget clunky text files or hardcoding help strings directly into your scripts. ScriptableObjects are the unsung heroes of data management in Unity, and they’re perfect for storing and organizing your help text.

Create a new script called HelpText.

using UnityEngine;

[CreateAssetMenu(fileName = "NewHelpText", menuName = "Help/HelpText")]
public class HelpText : ScriptableObject
{
    [TextArea(3, 10)] // Allows for multi-line text in the Inspector
    public string description;
}

This simple script creates a ScriptableObject that you can create directly from the Unity editor (Right-click in the Project window -> Create -> Help -> HelpText). The TextArea attribute makes editing the description a breeze.

Pitfall: A common mistake is to forget the CreateAssetMenu attribute. Without it, you can’t create the ScriptableObject from the editor.

Actionable Insight: Organize your HelpText ScriptableObjects into folders based on game areas or functionality. This keeps your project clean and manageable.

Implementing a Selection-Based Help Trigger

This is where things get interesting. We want the help text to dynamically update based on the currently selected object in the scene or hierarchy. Here’s how we can implement a selection-based help trigger using the Selection class.

using UnityEngine;
using UnityEditor;

public class HelpTrigger : MonoBehaviour
{
    public HelpText helpText;

    void OnEnable()
    {
        Selection.selectionChanged += OnSelectionChanged;
    }

    void OnDisable()
    {
        Selection.selectionChanged -= OnSelectionChanged;
    }

    void OnSelectionChanged()
    {
        GameObject selectedObject = Selection.activeGameObject;

        if (selectedObject != null)
        {
            HelpTrigger trigger = selectedObject.GetComponent<HelpTrigger>();

            if (trigger != null)
            {
                // Update the help UI with trigger.helpText
                // (Implementation in the next section)
                Debug.Log("Help Text: " + trigger.helpText.description); //Temporary debug
            }
            else
            {
              // Clear the help UI if no HelpTrigger found.
              Debug.Log("No Help Text"); //Temporary debug
            }
        } else {
             Debug.Log("No Help Text"); //Temporary debug
        }
    }
}

Attach this script to any GameObject you want to provide help for. Assign the corresponding HelpText ScriptableObject in the Inspector.

Challenge: The Selection.selectionChanged event fires frequently, even when the selection hasn’t meaningfully changed.

Solution: Implement a debounce mechanism to prevent unnecessary UI updates. Only update the UI if the helpText has actually changed.

Concrete Example: Use a simple boolean flag.

private HelpText currentHelpText;

    void OnSelectionChanged()
    {
        GameObject selectedObject = Selection.activeGameObject;

        if (selectedObject != null)
        {
            HelpTrigger trigger = selectedObject.GetComponent<HelpTrigger>();

            if (trigger != null)
            {
                if(trigger.helpText != currentHelpText)
                {
                    // Update the help UI with trigger.helpText
                    currentHelpText = trigger.helpText;
                    Debug.Log("Help Text: " + trigger.helpText.description); //Temporary debug
                }

            }
            else
            {
                currentHelpText = null;
              // Clear the help UI if no HelpTrigger found.
              Debug.Log("No Help Text"); //Temporary debug
            }
        } else {
            currentHelpText = null;
             Debug.Log("No Help Text"); //Temporary debug
        }
    }

Building a Simple UI to Present Help Information

Now, let’s create a basic UI to display the help text. This example uses a simple Text element in a Canvas.

1. Create a Canvas in your scene (GameObject -> UI -> Canvas).
2. Add a Text element to the Canvas (GameObject -> UI -> Text).
3. Create a new script called HelpUI.

using UnityEngine;
using UnityEngine.UI;

public class HelpUI : MonoBehaviour
{
    public Text helpTextDisplay;

    public void UpdateHelpText(string newText)
    {
        helpTextDisplay.text = newText;
    }

    public void ClearHelpText()
    {
      helpTextDisplay.text = "";
    }

}

Attach the HelpUI script to a GameObject in your scene (ideally on the Canvas). Drag the Text element to the helpTextDisplay field in the Inspector.

Now, modify the HelpTrigger script to call the UpdateHelpText function.

    private HelpText currentHelpText;
    public HelpUI helpUI;

    void OnSelectionChanged()
    {
        GameObject selectedObject = Selection.activeGameObject;

        if (selectedObject != null)
        {
            HelpTrigger trigger = selectedObject.GetComponent<HelpTrigger>();

            if (trigger != null)
            {
                if(trigger.helpText != currentHelpText)
                {
                    // Update the help UI with trigger.helpText
                    currentHelpText = trigger.helpText;
                    helpUI.UpdateHelpText(trigger.helpText.description);
                }

            }
            else
            {
                currentHelpText = null;
                helpUI.ClearHelpText();
            }
        } else {
            currentHelpText = null;
            helpUI.ClearHelpText();
        }
    }

Remember to link the HelpUI script in the inspector of any object with the HelpTrigger.

Common Mistake: Forgetting to properly reference the Text element in the Inspector.

Real-World Application: Integrate this system into a custom editor window to provide context-sensitive help while designers are working in the Unity editor.

The Developer’s Edge: Beyond the Basics

This is just the foundation. Here are some ways to elevate your context-sensitive help system:

• Rich Text Support: Use rich text tags in your ScriptableObjects to format the help text with bold, italics, and colors.
• Hyperlinks: Implement clickable hyperlinks in the help text to link to specific sections of your documentation or external websites.
• Localization: Use Unity’s localization tools to provide help text in multiple languages.
• Dynamic Hints: Add logic to dynamically display helpful hints based on the player’s current state or actions.

By understanding the power of ScriptableObjects and mastering the selection-based trigger, you can create a truly intuitive and helpful experience for your users. Don’t just tell them what to do; show them how to succeed.