Unity Guide System

English | 中文

A simple novice guidance system that provides novice guidance ideas. The core logic implements the novice guidance process through tag collection, distribution and asynchronous waiting. The presentation layer is determined by the respective project framework.

The World architecture and label collection at the framework level come from the ET framework

Features

• Event-Driven Architecture: Modular guide system using attributes for easy step management
• Visual UI Masks: Interactive mask overlays that highlight specific UI elements
• Async/Await Support: Built with UniTask for smooth asynchronous operations
• Cross-Platform Input: Supports both mouse and touch input for desktop and mobile
• Flexible Guide Types: Extensible system for creating different guide categories
• Canvas-Based: Works with Unity's UI Canvas system
• Click Detection: Precise click detection within highlighted areas
• Sequential Flow: Automatic progression through guide steps

Architecture Overview

Core Components

GuideSingleton

Central manager that orchestrates all guide operations. Handles initialization, guide execution, and step transitions.

GuideEvent

Abstract base class for creating individual guide steps. Each step inherits from this class and implements specific behavior.

GuideMask

Visual component that creates mask overlays with cutout areas to highlight UI elements. Includes click detection and visual feedback.

GuideContext

Provides cancellation token support for managing guide lifecycle and allowing early termination.

GuideManager

MonoBehaviour that initializes the guide system and manages the guide view instance.

Installation

1. Import the GuideSystem folder into your Unity project's Assets directory
2. Ensure UniTask is installed (included in the project)
3. Add the Init component to a GameObject in your scene to initialize the system
4. Set up your GuideManager with the guide view prefab

Quick Start

1. Define Guide Types

namespace GuideSystem
{
    public enum GuideType
    {
        LoginGuideGroup,
        GameplayTutorial,
        SettingsGuide
    }
}

2. Create Guide Steps

[Guide(GuideType.LoginGuideGroup, 0)]
public class LoginStep1_Handler : GuideEvent
{
    protected override async UniTask Run(GuideContext context, Func<UniTask> next)
    {
        var loginView = GameObject.FindObjectOfType<LoginView>();

        // Wait for user to click the username input field
        await GuideManager.Instance.GuideView.Play(loginView.UsernameField.transform);

        Debug.Log("Username field clicked!");

        // Proceed to next step
        next().Forget();
    }
}

3. Start a Guide Sequence

// Start the login guide from the beginning
GuideSingleton.Instance.StartGuide(GuideType.LoginGuideGroup).Forget();

// Or start from a specific step
GuideSingleton.Instance.StartGuide(GuideType.LoginGuideGroup, 2).Forget();

API Reference

GuideSingleton

Method	Description
StartGuide(GuideType, int)	Starts a guide sequence from specified step
StopGuide()	Cancels the current guide sequence

GuideEvent

Method	Description
Run(GuideContext, Func<UniTask>)	Override this method to implement step behavior
NextStep()	Proceed to the next guide step

GuideMask

Property	Description
moveThreshold	Maximum movement allowed for click detection
pressDurationThreshold	Maximum press duration for valid clicks
passThroughInHole	Whether to allow interaction with highlighted elements
padding	Extra padding around highlighted areas

Event	Description
OnTargetClicked	Triggered when user clicks the highlighted area

Project Structure

Assets/
├── GuideSystem/
│   ├── Scripts/
│   │   ├── Core/                 # Core framework components
│   │   │   ├── Singleton.cs      # Singleton pattern implementation
│   │   │   ├── World.cs          # Dependency injection container
│   │   │   └── ...
│   │   ├── Guide/                # Guide system core
│   │   │   ├── GuideSingleton.cs # Main guide manager
│   │   │   ├── GuideEvent.cs     # Base class for guide steps
│   │   │   ├── GuideMask.cs      # Visual mask component
│   │   │   ├── GuideContext.cs   # Cancellation support
│   │   │   └── ...
│   │   └── Init.cs               # System initialization
├── Scripts/                      # Example implementation
│   ├── GuideManager.cs           # Guide manager MonoBehaviour
│   ├── GuideView.cs              # Guide UI view
│   ├── LoginView.cs              # Example UI view
│   └── Handler/                  # Example guide handlers
│       ├── LoginGuideStep1_Handler.cs
│       ├── LoginGuideStep2_Handler.cs
│       └── LoginGuideStep3_Handler.cs
└── Plugins/
    └── UniTask/                  # Async/await support

Example Implementation

Creating a Multi-Step Login Guide

// Step 1: Guide user to username field
[Guide(GuideType.LoginGuideGroup, 0)]
public class UsernameGuideStep : GuideEvent
{
    protected override async UniTask Run(GuideContext context, Func<UniTask> next)
    {
        var loginView = FindObjectOfType<LoginView>();
        await GuideManager.Instance.GuideView.Play(loginView.UsernameField.transform);
        await next();
    }
}

// Step 2: Guide user to password field
[Guide(GuideType.LoginGuideGroup, 1)]
public class PasswordGuideStep : GuideEvent
{
    protected override async UniTask Run(GuideContext context, Func<UniTask> next)
    {
        var loginView = FindObjectOfType<LoginView>();
        await GuideManager.Instance.GuideView.Play(loginView.PasswordField.transform);
        await next();
    }
}

// Step 3: Guide user to login button
[Guide(GuideType.LoginGuideGroup, 2)]
public class LoginButtonGuideStep : GuideEvent
{
    protected override async UniTask Run(GuideContext context, Func<UniTask> next)
    {
        var loginView = FindObjectOfType<LoginView>();
        await GuideManager.Instance.GuideView.Play(loginView.LoginButton.transform);
        // Final step - no next() call needed
    }
}

Advanced Features

Custom Guide Masks

You can customize the appearance and behavior of guide masks by modifying the GuideMask component:

• Adjust padding to control highlight area size
• Modify moveThreshold for click sensitivity
• Configure passThroughInHole for interaction behavior

Cancellation Support

The system supports cancellation through GuideContext:

protected override async UniTask Run(GuideContext context, Func<UniTask> next)
{
    // Check for cancellation
    if (context.Token.IsCancellationRequested)
        return;

    // Your guide step logic here
    await SomeAsyncOperation(context.Token);
    await next();
}

Error Handling

Guide steps automatically handle OperationCanceledException for graceful cancellation.

Dependencies

• UniTask: Async/await support (included in project)

Technical Requirements

• Canvas with GraphicRaycaster for UI interaction
• EventSystem for input handling
• UI elements must be RectTransform-based

Performance Considerations

• Guide masks use mesh generation for efficient rendering
• Click detection uses Unity's built-in raycast system
• Minimal memory allocation during guide execution
• Automatic cleanup on guide completion or cancellation

Best Practices

1. Keep Steps Simple: Each guide step should focus on a single action
2. Error Handling: Always handle potential null references when finding UI elements
3. Testing: Test guides on both desktop and mobile platforms
4. Feedback: Provide clear visual feedback for user interactions
5. Accessibility: Consider adding audio cues or additional visual indicators

Troubleshooting

Common Issues

Guide doesn't start: Ensure Init component is present and GuideSingleton is initialized before calling StartGuide().

UI elements not highlighted: Verify that target UI elements are active and have valid RectTransform components.

Click detection not working: Check that Canvas has GraphicRaycaster and EventSystem is present in the scene.

Guide steps skipped: Ensure guide attributes have correct indices and no duplicate step numbers.

Support

For questions, issues, or feature requests, please refer to your project's issue tracking system or documentation.

---

This guide system provides a solid foundation for creating interactive tutorials in Unity projects. Customize and extend it according to your specific needs.