Indie XR Games

Get Started

Guide System Documentation

A comprehensive in-game guide/encyclopedia system for Unity, designed to display categorized information with a clean, navigable UI. Perfect for tutorials, lore compendiums, item databases, character profiles, and more.

Table of Contents

  1. Overview
  2. Features
  3. Installation
  4. Quick Start
  5. Architecture
  6. Data Structure
  7. Components Reference
  8. Editor Extensions
  9. Prefabs
  10. Customization
  11. API Reference
  12. Events
  13. Troubleshooting

Overview

The Guide System is a modular, data-driven UI system that provides an in-game encyclopedia or guide interface. It supports hierarchical content organization with categories, groups, and individual entries, making it ideal for:

  • Game Tutorials – Step-by-step guides organized by topic
  • Lore Compendiums – World-building content, history, locations
  • Item Databases – Equipment, consumables, collectibles
  • Character Profiles – NPCs, enemies, allies
  • Bestiary – Creature information and stats
  • Achievement Guides – Tips and unlockables

Namespace: IndieXRGames.GuideSystem

Features

  • ✅ Two-Panel Navigation – Category selection cards → Content detail view
  • ✅ Hierarchical Data – Categories → Groups → Entries
  • ✅ Collapsible Groups – Expand/collapse content sections
  • ✅ Quick Category Switching – Tab navigation in content view
  • ✅ Dual Input System Support – Legacy Input Manager & New Input System
  • ✅ Game Pause Integration – Optional automatic pause when guide opens
  • ✅ Singleton Pattern – Easy global access via GuideManager.Instance
  • ✅ ScriptableObject Database – Designer-friendly content management
  • ✅ Fully Serialized – All settings exposed in Inspector
  • ✅ Event System – Subscribe to open/close events
  • ✅ Hover & Selection States – Visual feedback on entries

Installation

  1. Copy the GuideSystem folder into your project’s Assets directory
  2. Ensure the following dependencies are present:
    • TextMeshPro (Unity Package Manager)
    • Input System (if using New Input System mode)

Assembly Definition

The system includes a GuideSystem.asmdef to keep scripts organized and improve compile times. It references:

  • Unity.InputSystem
  • Unity.TextMeshPro

Quick Start

Step 1: Create a Guide Database

  1. Right-click in the Project window
  2. Navigate to Create → Guide System → Database
  3. Name it (e.g., GuideDatabase)
  4. Select the asset and populate it with categories, groups, and entries

Step 2: Set Up the Scene

  1. Add the GuideManager prefab to your scene (or create from scratch)
  2. Add the GuideUIController as a child of a Canvas
  3. Assign references:
    • Drag your GuideDatabase asset to the UI Controller
    • Connect all UI elements (panels, containers, prefabs)

Step 3: Configure Input

For New Input System:

  • Create an Input Action asset for the toggle action
  • Assign it to the GuideManager component

For Legacy Input System:

  • Set Input System Type to OldInputSystem
  • Configure Toggle Key Code (default: Tab)

Step 4: Test

Press your toggle key to open the guide. You should see:

  1. Category selection cards
  2. Click a card to view content
  3. Expand groups and select entries
  4. Use tabs to switch categories
  5. Press toggle key or close button to exit

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        GuideManager                              │
│  (Singleton - Input Handling, Game State, Show/Hide Control)    │
└─────────────────────────┬───────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                     GuideUIController                            │
│  (Main UI Logic - Panel Switching, Content Building, Events)    │
└─────────────────────────┬───────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
    ┌──────────┐   ┌─────────────┐   ┌─────────────┐
    │GuideCard │   │GuideCatTab  │   │GuideContent │
    │(Category │   │(Quick Nav)  │   │   Group     │
    │Selection)│   └─────────────┘   └──────┬──────┘
    └──────────┘                            │
                                            ▼
                                   ┌─────────────────┐
                                   │ GuideContent    │
                                   │    Entry        │
                                   └─────────────────┘

Data Flow

GuideDatabase (ScriptableObject)
      │
      ├── GuideCategory[]
      │       ├── DisplayName
      │       ├── IconSprite
      │       ├── CardBackgroundSprite
      │       └── GuideGroup[]
      │               ├── DisplayName
      │               ├── ThumbnailSprite
      │               ├── IsExpandedByDefault
      │               └── GuideEntry[]
      │                       ├── EntryName
      │                       ├── ListThumbnailSprite
      │                       ├── DetailTitle
      │                       ├── DetailDescription
      │                       └── DetailImageSprite

Data Structure

GuideDatabase

The root ScriptableObject containing all guide content.

Property Type Description
Categories IReadOnlyList All top-level categories
CategoryCount int Number of categories

Creation: Assets → Create → Guide System → Database

GuideCategory

Represents a top-level category displayed as a selection card.

Property Type Description
DisplayName string Name shown on card and header
IconSprite Sprite Icon for category tab
CardBackgroundSprite Sprite Large image on selection card
ContentGroups IReadOnlyList Groups within this category
GroupCount int Number of groups

GuideGroup

A collapsible section containing related entries.

Property Type Description
DisplayName string Group header name
ThumbnailSprite Sprite Optional header thumbnail
Entries IReadOnlyList Entries in this group
EntryCount int Number of entries
IsExpandedByDefault bool Start expanded on load

GuideEntry

A single selectable item with detailed content.

Property Type Description
EntryName string Name in the list
ListThumbnailSprite Sprite Small icon next to name
DetailTitle string Title in detail view
DetailDescription string Full description text
DetailImageSprite Sprite Large preview image

Components Reference

GuideManager

File: Scripts/GuideManager.cs

The central singleton manager handling input and state control.

Inspector Properties

Property Type Description
Guide UI Controller GuideUIController Reference to the UI controller
Input System Type enum OldInputSystem or NewInputSystem
Toggle Key Code KeyCode Key to toggle guide (legacy)
Toggle Input Action InputActionReference Action to toggle (new)
Pause Game When Open bool Set Time.timeScale = 0 when open

Public API

// Singleton access
GuideManager.Instance

// Properties
bool IsGuideOpen { get; }

// Methods
void OpenGuide()    // Opens the guide panel
void CloseGuide()   // Closes the guide panel
void ToggleGuide()  // Toggles visibility

// Events
event Action OnGuideOpened
event Action OnGuideClosed

Usage Example

// Check if guide is open
if (GuideManager.Instance.IsGuideOpen)
{
    // Do something
}

// Subscribe to events
GuideManager.Instance.OnGuideOpened += HandleGuideOpened;
GuideManager.Instance.OnGuideClosed += HandleGuideClosed;

// Programmatically control
GuideManager.Instance.OpenGuide();

GuideUIController

File: Scripts/UI/GuideUIController.cs

Main UI controller managing all visual elements and navigation.

Inspector Properties

Section Property Type Description
Data Source Database GuideDatabase The content database
Category Selection Category Selection Panel GameObject Root of selection view
Category Card Container Transform Parent for card instances
Category Card Prefab GameObject Card prefab template
Content Detail Content Detail Panel GameObject Root of detail view
Header Header Title Text TMP_Text Category name display
Category Tab Container Transform Parent for tab instances
Category Tab Prefab GameObject Tab prefab template
Group List Group List Container Transform Parent for groups
Content Group Prefab GameObject Group prefab template
Content Entry Prefab GameObject Entry prefab template
Description Entry Title Text TMP_Text Selected entry title
Entry Description Text TMP_Text Selected entry description
Image Preview Entry Preview Image Image Large detail image
Image Preview Container GameObject Container for hiding
Navigation Close Button Button Close the guide

Public API

void Initialize()                        // Build initial UI
void Show()                              // Show and reset to selection
void Hide()                              // Hide the guide
void HandleCategoryCardSelected(int index)   // Navigate to category
void HandleCategoryTabSelected(int index)    // Switch category in detail view
void HandleContentGroupToggled(GuideContentGroup group)  // Group expand event
void HandleEntrySelected(GuideContentEntry entry, GuideEntry data)  // Entry selection
void NavigateBackToCategorySelection()   // Return to card selection
void RequestCloseGuide()                 // Request close via manager

GuideCard

File: Scripts/UI/GuideCard.cs

UI component for category selection cards on the main panel.

Inspector Properties

Property Type Description
Background Image Image Card background
Icon Image Image Category icon
Title Text TMP_Text Category name
Select Button Button Click handler
Normal Color Color Default state
Highlighted Color Color Hover/selected state
Dimmed Color Color Inactive state

Public API

void Initialize(int index, GuideCategory category, GuideUIController controller)
void SetHighlighted(bool isHighlighted)

GuideCategoryTab

File: Scripts/UI/GuideCategoryTab.cs

Tab buttons for quick category switching in the content panel header.

Inspector Properties

Property Type Description
Icon Image Image Category icon
Background Image Image Tab background
Tab Button Button Click handler
Inactive Color Color Non-selected state
Active Color Color Selected state

Public API

void Initialize(int index, Sprite iconSprite, bool isSelected, GuideUIController controller)
void SetSelected(bool isSelected)

GuideContentGroup

File: Scripts/UI/GuideContentGroup.cs

Collapsible group headers containing entry lists.

Inspector Properties

Property Type Description
Group Name Text TMP_Text Group title
Thumbnail Image Image Optional group icon
Expand Arrow Image Image Expand/collapse indicator
Header Button Button Toggle expand on click
Entries Container Transform Parent for entries
Entry Prefab GameObject Entry template
Expanded Arrow Rotation float Arrow angle when open
Collapsed Arrow Rotation float Arrow angle when closed

Public API

bool IsExpanded { get; }

void Initialize(GuideGroup groupData, GuideUIController controller)
void ToggleExpandedState()
void Expand()
void Collapse()

GuideContentEntry

File: Scripts/UI/GuideContentEntry.cs

Selectable entry items with hover and selection feedback.

Implements: IPointerEnterHandler, IPointerExitHandler

Inspector Properties

Property Type Description
Entry Name Text TMP_Text Entry name
Thumbnail Image Image Small icon
Background Image Image Entry background
Border Image Image Selection border
Select Button Button Click handler
Background Colors
Normal Background Color Color Default state
Hover Background Color Color Mouse over state
Selected Background Color Color Selected state
Border Colors
Normal Border Color Color Default border
Selected Border Color Color Selected border

Public API

void Initialize(GuideEntry entryData, GuideUIController controller)
void SetSelected(bool isSelected)

Editor Extensions

ShowIfAttribute

File: Scripts/Editor/ShowIfAttribute.cs

A custom attribute for conditional field visibility in the Inspector.

Usage

[SerializeField] private bool _useAdvancedSettings;

[ShowIf(nameof(_useAdvancedSettings), true)]
[SerializeField] private float _advancedValue;

// Enum example
[SerializeField] private InputSystemType _inputType;

[ShowIf(nameof(_inputType), InputSystemType.NewInputSystem)]
[SerializeField] private InputActionReference _inputAction;

Supported Types

  • bool – Direct boolean comparison
  • enum – Enum value comparison
  • int – Integer comparison
  • string – String comparison

ShowIfPropertyDrawer

File: Scripts/Editor/ShowIfPropertyDrawer.cs

The property drawer that implements ShowIfAttribute functionality. Automatically handles:

  • Conditional visibility
  • Proper height calculation (returns 0 when hidden)
  • Multiple property types

Prefabs

Located in GuideSystem/Prefab/:

Prefab Description
Category Card Prefab.prefab Selection card for categories
GuideCategoryTab.prefab Tab button for header navigation
GuideContentEntry.prefab Selectable entry item
GuideContentGroup.prefab Collapsible group container

Prefab Hierarchy Recommendations

Category Card Prefab
├── Background (Image)
├── Icon (Image)
├── Title (TextMeshPro)
└── Button (Button component on root)

GuideCategoryTab
├── Background (Image)
├── Icon (Image)
└── Button (Button component on root)

GuideContentGroup
├── Header
│   ├── Arrow (Image - rotates)
│   ├── Thumbnail (Image)
│   ├── GroupName (TextMeshPro)
│   └── HeaderButton (Button)
└── EntriesContainer (VerticalLayoutGroup)

GuideContentEntry
├── Background (Image)
├── Border (Image)
├── Thumbnail (Image)
├── EntryName (TextMeshPro)
└── SelectButton (Button)

Customization

Styling

All visual elements can be customized through:

  1. Prefab Modifications – Edit prefab layouts, add animations
  2. Color Properties – Adjust serialized color fields in Inspector
  3. CSS-like Approach – Create UI style ScriptableObjects (custom extension)

Adding New Features

Custom Entry Types

Extend GuideEntry for specialized content:

[Serializable]
public class VideoGuideEntry : GuideEntry
{
    [SerializeField] private VideoClip _videoClip;
    public VideoClip VideoClip => _videoClip;
}

Animations

Add animation components to prefabs:

// In GuideContentGroup
[SerializeField] private Animator _animator;

private void UpdateExpandedVisualState()
{
    _animator?.SetBool("IsExpanded", _isExpanded);
}

Search Functionality

Extend GuideUIController:

public List SearchEntries(string query)
{
    var results = new List();
    foreach (var category in _database.Categories)
    {
        foreach (var group in category.ContentGroups)
        {
            results.AddRange(group.Entries.Where(e => 
                e.EntryName.Contains(query, StringComparison.OrdinalIgnoreCase)));
        }
    }
    return results;
}

API Reference

Quick Reference Table

Class Key Methods Purpose
GuideManager OpenGuide(), CloseGuide(), ToggleGuide() Global control
GuideUIController Show(), Hide(), Initialize() UI management
GuideCard Initialize(), SetHighlighted() Card display
GuideCategoryTab Initialize(), SetSelected() Tab control
GuideContentGroup Expand(), Collapse(), ToggleExpandedState() Group control
GuideContentEntry Initialize(), SetSelected() Entry display

Static Access

// Always available via singleton
GuideManager.Instance.OpenGuide();
GuideManager.Instance.CloseGuide();
GuideManager.Instance.IsGuideOpen;

Events

GuideManager Events

// Fired when guide opens
public event Action OnGuideOpened;

// Fired when guide closes
public event Action OnGuideClosed;

Usage Example

public class PlayerController : MonoBehaviour
{
    private void OnEnable()
    {
        if (GuideManager.Instance != null)
        {
            GuideManager.Instance.OnGuideOpened += DisablePlayerInput;
            GuideManager.Instance.OnGuideClosed += EnablePlayerInput;
        }
    }
    
    private void OnDisable()
    {
        if (GuideManager.Instance != null)
        {
            GuideManager.Instance.OnGuideOpened -= DisablePlayerInput;
            GuideManager.Instance.OnGuideClosed -= EnablePlayerInput;
        }
    }
    
    private void DisablePlayerInput() => enabled = false;
    private void EnablePlayerInput() => enabled = true;
}

Troubleshooting

Common Issues

Guide Doesn’t Open

  1. Check Input Configuration

    • Verify InputSystemType matches your project setup
    • For New Input System: Ensure actions are assigned and enabled
    • For Legacy: Verify KeyCode settings

  2. Missing References

    • Check GuideUIController is assigned on GuideManager
    • Ensure GuideDatabase is assigned on GuideUIController

  3. Input System Package

    • If using New Input System, ensure package is installed
    • Enable it in Project Settings → Player → Active Input Handling

No Content Displaying

  1. Empty Database

    • Open your GuideDatabase asset
    • Add at least one category with groups and entries

  2. Missing Prefabs

    • Verify all prefab references are assigned
    • Check prefabs have correct components attached

  3. Container References

    • Ensure all container Transforms are assigned
    • Containers should have appropriate Layout Groups

Visual Glitches

  1. Layout Issues

    • Add VerticalLayoutGroup to containers
    • Configure ContentSizeFitter components
    • Check Canvas Scaler settings

  2. Images Not Showing

    • Verify sprites are assigned in database
    • Check Image components have Preserve Aspect if needed
    • Ensure sprites are imported with correct settings

Performance

  1. Many Entries
    • Consider implementing object pooling for entries
    • Use virtual scrolling for large lists
    • Lazy-load images

Debug Mode

Add debug logging:

// In GuideManager
public void OpenGuide()
{
    Debug.Log($"[GuideSystem] Opening guide. Current state: {_isGuideOpen}");
    // ... rest of method
}

Version History

Version Date Changes
1.0.0 Initial Core system release

Support

For issues, feature requests, or contributions, please contact the development team or submit through your project’s issue tracker.