> For the complete documentation index, see [llms.txt](https://stonesoft-studios.gitbook.io/stonesoft-studios-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stonesoft-studios.gitbook.io/stonesoft-studios-docs/scene-revealer-pro-documentation.md).

# Scene Revealer Pro - Documentation

## Scene Revealer Pro - Documentation | v1.4.0

#### Dynamic Entrance Animations & More!

**Publisher:** StoneSoft Studios **Support:** [Discord](https://discord.gg/tZ9e2TKK89) | <StoneSoftStudios@Gmail.com> **Documentation Date:** June 14, 2025

#### **Table of Contents**

1. **Introduction**
2. **What's New & Awesome in v1.4.0**
3. **System Requirements & Installation**
4. **Quick Start Guide**
   * ManualList Mode: Your First Reveal
   * SceneCollectionRoot Mode: For Organized Scenes
   * Message Cycler Magic: Quick Intro
5. **Core Concepts: Scene Reveal Manager (SRP)**
   * The SS\_SceneRevealManager Component
   * Operating Modes: Choose Your Adventure!
   * Reveal Behaviors: The Spice of Animation
6. **NEW! Understanding Hierarchy & Operating Modes**
   * ManualList Mode Hierarchy
   * AutoSceneRoots Mode Hierarchy
   * SceneCollectionRoot Mode Hierarchy
7. **The Message Cycler System**
8. **The SRP Custom Editor: Your Command Center**
   * Main Sections (Foldouts) & Runtime Controls
   * Editor Actions (Persistence & Runtime Controls)
   * Gizmo Focus with Inspector Selections
   * Editor Themes
9. **SRP Inspector Deep Dive**
   * ManualList Mode Settings
   * AutoSceneRoots Mode Settings
   * SceneCollectionRoot Mode Settings
   * Overall Timing & Control
   * Debug & Gizmo Options
10. **Configuring Reveal Behaviors**
    * Common Behavior Settings
    * Behavior Types Explained
    * Adding Randomization
11. **Advanced SRP Features**
    * Unreveal Sequence (Hiding Objects)
    * Handling UI Elements
    * Group Completion Synchronization
12. **Manual Control via Scripting (SRP)**
13. **Manual Control via Scripting (Message Cycler)**
14. **Troubleshooting & FAQ**
15. **Changelog**

## 1. Introduction

✨ **Lights, Camera, Action! Welcome to Scene Revealer Pro v1.4.0!** ✨

Get ready to dazzle your players! Scene Revealer Pro (SRP) is your all-in-one solution for creating stunning, sequential reveal and unreveal animations for GameObjects in your Unity scenes. Whether you're crafting epic intros, guiding players through tutorials, or making your UI pop, SRP provides the tools to do it with style and ease.

From grand entrances to subtle UI hints, SRP empowers you to animate objects into (or out of) view using a variety of built-in behaviors like scaling, moving, rotating, color tinting, and fading. With v1.4.0's new systems, you can now add perfectly timed sound effects to every animation and customize the editor's appearance to your liking for a truly professional workflow.

SRP is incredibly versatile, perfect for:

* Cinematic intros, stunning title screens, and engaging cutscenes.
* Interactive tutorials and smooth onboarding flows.
* Dynamic UI element reveals, transitions, and information displays.
* Atmospheric environment pop-ins and immersive level introductions.
* Gracefully animating objects to hide or clear the scene for transitions.
* ...and any scenario where you need controlled, sequential object animation!

### 2. What's New & Awesome in v1.4.0

Version 1.4.0 builds on the powerful features of previous versions and adds new systems for audio and editor customization!

🔊 **MAJOR NEW FEATURE! Per-Behavior Audio System:**

* **Audio on Animation:** Each individual `RevealBehavior` now contains its own `RevealAudioSettings` section, allowing you to assign specific sounds to specific animations (e.g., a "swoosh" for a Move, and a "thump" for a Scale).
* **Precise Timing:** A new `audioTriggerPoint` slider `[Range(0,1)]` lets you define exactly *when* the sound plays during a behavior's animation (0 for the start, 0.5 for halfway, 1 for the end).
* **Flexible Playback:** Audio settings include options for randomized playback delay, clip selection order (random or sequential from a list), and randomized volume/pitch to add variety.
* **Centralized Pooling:** All audio is played through a high-performance, persistent `SS_AudioPool` singleton, which creates and reuses `AudioSource` components as needed, preventing scene clutter and ensuring efficiency.
* **Editor Testing:** A "Test Sound" button in the inspector lets you preview your audio settings directly in the editor.

🎨 **NEW! Customizable Editor Themes:**

* **Personalize Your Workflow:** Change the look and feel of the SRP and Message Cycler inspectors to match your preference with `ScriptableObject`-based themes.
* **Live Customization:** A new "Editor Theme" foldout in the inspector allows you to modify the colors of the current theme in real-time.
* **Save & Share:** Save your color configurations as new Theme assets (`SS_EditorTheme`) to reuse across projects or share with your team.
* **Built-in Themes:** Comes with "StoneSoft Dark" (default) and "Classic Light" themes out of the box.

*(Features new in v1.3.0 are also included!)*

* **Message Cycler System:** A dedicated system (`SS_MessageCycler`) for managing and displaying sequences of GameObjects, with seamless SRP animation integration.
* **Fade (CanvasGroup) Reveal Behavior:** Animate `CanvasGroup.alpha` for smooth UI and sprite-based object fade effects.
* **Advanced Randomization for Move/Rotate Offsets:** Control randomness with `OffsetDistribution` types.
* **Enhanced Gizmos & Debugging:** Master toggles, category toggles, and an option to focus gizmos on the currently selected item.
* **Editor Play Mode Persistence:** Optionally save changes made to the SRP manager during Play Mode back to your scene.

### 3. System Requirements & Installation

* **Unity Version:** Unity 2021.3 LTS or newer is recommended.
* **Render Pipeline:** Compatible with Built-in, Universal Render Pipeline (URP), and High Definition Render Pipeline (HDRP).
* **Dependencies:** None. Relies only on core Unity features.

**Installation:**

1. If you obtained Scene Revealer Pro from the Unity Asset Store, open the Package Manager (`Window -> Package Manager`).
2. In the Package Manager, select "My Assets" from the dropdown at the top left.
3. Find "Scene Revealer Pro" in your list of purchased assets.
4. Click "Download" (if not already downloaded) and then "Import".
5. An "Import Unity Package" window will appear. Review the files and click "Import". The asset files will typically be added under `Assets/StoneSoftStudios/SceneRevealerPro`.

### 4. Quick Start Guide

Let's get you animating in minutes!

#### 4.1 ManualList Mode: Your First Reveal

Perfect for when you have a specific list of objects to animate.

1. **Create Manager GameObject:** In your scene's Hierarchy, create an empty GameObject (Right-click -> "Create Empty"). Name it something like `_SceneRevealManager_Main`.
2. **Add Component:** Select `_SceneRevealManager_Main`. In the Inspector, click "Add Component," search for "Scene Reveal Manager" (`SS_SceneRevealManager`), and add it.
3. **Operating Mode:** Ensure `Operating Mode` is set to `ManualList` (this is often the default).
4. Expand the "Objects To Reveal Configuration" foldout.
5. In the "Objects To Reveal" list, click the `+` button twice to add two elements.
6. Drag GameObjects from your scene Hierarchy into the "Object to Reveal" slots for "Element 0" and "Element 1". The order here is your reveal sequence!
7. **Configure Behaviors (Per Object):**
   * Click an element's foldout arrow to expand its settings.
   * Under "Standard Reveal," in its "Reveal Behaviors" list, click `+`.
   * Set its `Type` to `Scale`. Adjust `Duration` to 0.5.
   * Add another RevealBehavior. Set its `Type` to `Move` and set `Move Offset` to X: -5, Y: 0, Z: 0 (it'll slide in from the left).
8. **Configure Timing:**
   * Expand the "Overall Timing & Control" foldout.
   * Set `Delay Between Objects` to 0.25 seconds for a nice stagger.
   * Ensure `Start Objects Hidden` is checked (enabled). **This is key!**
   * Ensure `Start Automatically` is checked (enabled).
9. Press Play! Watch your objects animate into the scene!

#### 4.2 SceneCollectionRoot Mode: For Organized Scenes

Ideal if your scene objects are already grouped under parent GameObjects.

1. **Create Manager & Set Mode:** Add the `SS_SceneRevealManager` component as above. Change `Operating Mode` to `SceneCollectionRoot`.
2. Expand the "Scene Root Groups Setup" foldout and click `+` on the "Scene Root Collection Groups" list.
3. **Assign Group Root Object:** Expand "Group 0". Drag your main parent GameObject (e.g., an empty `_Environment_Master` that holds `_Buildings_Collection` and `_Roads_Collection` as its direct children) into the `Group Root Object` slot.
4. **Populate Child Collections:** Click the "Populate/Refresh Collections for this Group" button. This auto-creates entries in "Child Collections" for the direct children of your Group Root Object. These "Child Collections" are the GameObjects whose own children will be revealed.
5. **Global Item Defaults (Optional):** Expand "Global Collection Item Settings." Add a RevealBehavior (e.g., Scale, Duration: 0.4). Set Delay Between Collection Items to 0.1. These apply to the items within each child collection unless a specific collection overrides them.
6. **Customize a Specific Collection (Example):** In "Group 0," find your `_Buildings_Collection` entry (under "Child Collections") and expand it. Check `Override Global Collection Item Settings`. In `Specific Item Reveal Behaviors`, add a `Move` behavior with Y: -5.
7. **Timing & Start:** Ensure `Start Objects Hidden` and `Start Automatically` are checked.
8. Press Play! Items within `_Buildings_Collection` will move up, then items within `_Roads_Collection` (if any) will use the global defaults.

#### 4.3 Message Cycler Magic: Quick Intro

Want to show a sequence of tutorial messages, animated by SRP?

1. **Create Message Cycler:** Create an empty GameObject, name it `_TutorialCycler`. Add the `SS_MessageCycler` component.
2. In `_TutorialCycler`'s Inspector, expand "Message Collections." Click `+`. Name "Collection 0" to "Intro Steps."
3. Expand its "Messages" array. Click `+` twice.
4. Create two UI Text/Image GameObjects in your Canvas (e.g., `TutorialStep1`, `TutorialStep2`).
5. Drag `TutorialStep1` to "Message 0 -> Message Object" and `TutorialStep2` to "Message 1 -> Message Object."
6. Initially, make `TutorialStep1` and `TutorialStep2` inactive in the Hierarchy.
7. **Link to SRP:** Go to your `_SceneRevealManager_Main` GameObject. In its `Objects To Reveal` list (assuming `ManualList` mode), add a new element.
8. Drag your `_TutorialCycler` GameObject into this new element's `Object to Reveal` slot.
9. Check the **Is Message Cycler Host** box for this element.
10. In `Message Item Reveal Behaviors` for this element, add a `Scale` behavior and a `Fade` behavior (ensure each message object like `TutorialStep1` has a `CanvasGroup` for Fade to work).
11. Press Play! When SRP reaches the `_TutorialCycler` in its sequence, it will tell the Cycler to show its first message, which SRP will then animate in using the Scale and Fade behaviors. Clicking a UI button (you'd script this to call `_TutorialCycler.ShowNextMessage()`) will then animate out the first and animate in the second!

### 5. Core Concepts: Scene Reveal Manager (SRP)

#### 5.1 The SS\_SceneRevealManager Component

The `SS_SceneRevealManager` script is the heart of the system. Add this MonoBehaviour to a GameObject in your scene. It's responsible for:

* Figuring out what to animate based on the `OperatingMode`.
* Storing and applying your animation settings (defined as `RevealBehavior`s).
* Controlling the overall timing, delays, sequencing, and looping.
* Handling automatic or manual triggering of reveals and un-reveals.
* Executing the animations and providing `UnityEvent` callbacks for key sequence moments.

#### 5.2 Operating Modes: Choose Your Adventure!

The `Operating Mode` dictates how SRP identifies and organizes GameObjects:

* **ManualList:** For precise, individual control over a specific set of GameObjects. You manually populate the `Objects To Reveal` list. Each entry can be a single GameObject or a parent whose direct children will be revealed sequentially. Offers the most granular control.
* **AutoSceneRoots:** For simple scenarios where you want to reveal all top-level (root) GameObjects in your scene with a uniform set of animations. If `Objects To Reveal` is empty, SRP automatically finds all active root GameObjects and applies behaviors from the `Default Reveal Behaviors` section.
* **SceneCollectionRoot:** Ideal for large, complex scenes with hierarchically organized objects (e.g., an environment with "Buildings," "Props," "Vehicles"). You define `SceneRootCollectionGroups`. Each group has a `Group Root Object`. Its direct children become "Child Collections." Items within these "Child Collection" GameObjects are then revealed sequentially. You can set global defaults for item behaviors and override them per collection.

#### 5.3 Reveal Behaviors: The Spice of Animation

A `RevealBehavior` defines a single animation effect. Multiple `RevealBehavior`s can be applied to the same object for combined effects! Key properties:

* **Type:** The kind of animation (Scale, Move, Rotate, ColorTint, Fade).
* **AnimationMode:** How it plays (Once, Loop, PingPong).
* **Duration:** Base time for one animation cycle.
* **Curve:** `AnimationCurve` for easing (smoothness).
* **Type-Specific Settings:** E.g., Move Offset, Start Color Tint, Start Alpha.
* **Randomization Options:** For Duration and Offset (Move/Rotate).
* **NEW! Audio Settings:** A collapsible section for all audio properties.
  * **enabled:** A checkbox to turn audio on or off for this specific behavior.
  * **playbackDelayRange:** A random delay to wait before playing the sound.
  * **audioClips:** A list of clips to choose from.
  * **clipOrder:** Random or Sequential playback from the list.
  * **Volume & Pitch:** Configure static or randomized volume and pitch.
* **NEW! Audio Trigger Point:** A slider `[Range(0,1)]` that determines when the sound plays during the behavior's animation (e.g., 0=start, 0.5=halfway, 1=end).

### 6. NEW! Understanding Hierarchy & Operating Modes

How you organize your GameObjects in the Hierarchy is crucial for how SRP operates, especially outside of `ManualList` mode.

#### 6.1 ManualList Mode Hierarchy

This mode is the most flexible and has **no strict hierarchy requirements.** You can drag any GameObject from anywhere in your scene into the `Objects To Reveal` list.

The only time hierarchy matters is when you check `Reveal Children Sequentially` on an `ObjectToReveal` entry. In that case, SRP will animate the *direct children* of the GameObject you assigned.

#### 6.2 AutoSceneRoots Mode Hierarchy

This mode only operates on **root GameObjects**. A root GameObject is one that has no parent and sits at the top level of your scene hierarchy. Any objects that are nested inside other objects will be ignored.

**Example Hierarchy for `AutoSceneRoots`:**

```
_SRP_Manager
MainCamera
Directional Light
Player_Character (Will be revealed)
Environment_Art (Will be revealed)
  - Walls
  - Floors
UI_Canvas (Will be revealed)
  - MainMenu

```

#### 6.3 SceneCollectionRoot Mode Hierarchy

This is the most structured mode and relies on a specific **three-tier hierarchy**.

1. **Group Root Object:** The top-level parent you assign in the `Scene Root Collection Groups` list. This is just an organizer.
2. **Collection Objects:** The **direct children** of the `Group Root Object`. SRP discovers these and treats them as "collections." These are also just organizers and are not animated themselves.
3. **Revealable Items:** The **direct children** of a `Collection Object`. These are the actual GameObjects that SRP will animate.

**Example Hierarchy for `SceneCollectionRoot`:**

```
_SRP_Manager
_Level_01_Art (This is the Group Root Object)
  - _Props (This is a Collection Object)
    - Prop_Crate_01 (This is a Revealable Item)
    - Prop_Barrel_02 (This is a Revealable Item)
  - _Buildings (This is a Collection Object)
    - Building_Main_01 (This is a Revealable Item)
    - Building_Garage_01 (This is a Revealable Item)
    - Building_Shed_03 (This is a Revealable Item)
  - _VFX (This is a Collection Object)
    - Fog_Effect (This is a Revealable Item)
    - Fire_Particles (This is a Revealable Item)

```

In this example, if there is any delay between collections it would first animate all items under `_Props`, then all items under `_Buildings`, and finally all items under `_VFX`. If there are no delays all objects are animated at once.

### 7. The Message Cycler System

*(This section is a summary. For detailed setup, see the Quick Start Guide or the Inspector Deep Dive.)*

The `SS_MessageCycler` is a powerful system for managing and displaying sequences of GameObjects, like tutorial messages, UI panels, or narrative text. It can be used standalone or integrated with SRP for animated transitions.

* **Core Components:**
  * **`SS_MessageCycler` (Component):** The main component you add to a GameObject. It holds all the settings and logic.
  * **`MessageCollection` (Class):** A container for a group of related messages, with settings for looping and starting behavior.
  * **`MessageItem` (Class):** Represents a single message, holding a reference to the `GameObject` to show/hide and its specific events.
* **Events:** The Message Cycler provides several `UnityEvent`s to let other systems react to its state changes, including `OnBeforeShowMessage` and `OnBeforeHideMessage` which SRP uses for integration.

### 8. The SRP Custom Editor: Your Command Center

The custom inspector for the `SS_SceneRevealManager` is designed to be powerful yet intuitive.

#### 8.1 Main Sections (Foldouts) & Runtime Controls

The editor is primarily structured with these collapsible sections:

* **Mode of Operation:** The crucial dropdown at the very top.
* **Object/Group Configuration:** This is your main content setup area and changes based on the selected `Operating Mode`.
* **Overall Timing & Control:** Global timing, looping, and sequence-wide events.
* **Debug & Gizmo Options:** For visualization and troubleshooting.
* **Editor Actions:** Contains the Play Mode Persistence toggle and Runtime Controls.
* **Editor Theme:** Customize the look and feel of the inspector.

#### 8.2 Editor Actions (Persistence & Runtime Controls)

**Runtime Controls**

Visible only when in Play Mode, this section provides buttons for immediate control over the sequence:

* **Reset & Set Initial:** Stops all playing animations and forces all objects back to their initial hidden/offset state. Does not restart the sequence.
* **Start Reveal:** Manually triggers the reveal sequence from the beginning. If a sequence is already playing, it will be reset and restarted.
* **Start Unreveal:** Manually triggers the unreveal sequence.

**Editor Play Mode Persistence**

* **Editor Persist Play Mode Changes** \[Toggle Button]:

  * **OFF (Default):** Changes made to the SRP manager's properties during Play Mode are discarded when you exit Play Mode.

  * **ON (Green):** Serializable changes you make (e.g., to lists, delays, durations, booleans) while in Play Mode will be saved back to your scene object when you exit.

  > **Caution:** This is a powerful feature for fine-tuning! Be mindful that changes can become permanent. Non-serializable runtime states (like active coroutines) are not saved.

#### 8.3 Gizmo Focus with Inspector Selections

To make it easier to visualize complex setups, SRP's Gizmos can now focus on what you've selected in the inspector (when `Show Only Selected Gizmos` is checked):

* **ManualList Mode:** When you select an element in the "Objects To Reveal" list, the Scene View Gizmos will attempt to draw only for that selected item and its potential children.
* **SceneCollectionRoot Mode:** Selecting a `SceneRootCollectionGroup` or a specific `CollectionRootSettings` entry will focus gizmos on that part of the hierarchy.

#### 8.4 Editor Themes

New in v1.4.0, you can now customize the appearance of the `Scene Reveal Manager` and `Message Cycler` inspectors.

* **What are Themes?** Themes are `ScriptableObject` assets of type `SS_EditorTheme`. They store color settings for the inspector UI. You can create new ones via **Assets > Create > StoneSoft Studios > Editor Theme**.
* **Changing Themes:** At the bottom of the manager inspector, you'll find an **Editor Theme** foldout. Here you can use the **Current Theme** dropdown to select any `SS_EditorTheme` asset found in your project. The change is applied instantly.
* **Live Customization:** Once a theme is selected, you can change its colors directly in the foldout. This will modify the selected theme asset in real-time.
* **Saving a New Theme:** After tweaking the colors to your liking, click the **"Save as New Custom Theme"** button. This will prompt you to save a *new* theme asset, preserving the original. Your inspector will automatically switch to using this new theme.

### 9. SRP Inspector Deep Dive

#### 9.1 ManualList Mode Settings

* **Objects To Reveal Configuration \[Foldout]:** This is where you build your sequence. Drag GameObjects into the reorderable list.
* **Configuring an `ObjectToReveal` Element:**
  * **Object to Reveal \[Slot]:** The target `GameObject`.
  * **Reveal Behaviors:** A list of animations to apply to this object.
  * **Use External Scaling:** If checked, any `Scale` behaviors are ignored.
  * **waitForCompletion:** If checked, the manager waits for this item to finish before starting the next.
  * **Reveal Children Sequentially:** If checked, animates direct children instead of the parent.
  * **Is Message Cycler Host:** If checked, this object will animate messages from a linked `SS_MessageCycler` component.

#### 9.2 AutoSceneRoots Mode Settings

* **Default Behaviors for Scene Roots \[Foldout]:** If the `Objects To Reveal` list is empty and this mode is active, the manager automatically finds all active root GameObjects and applies the `RevealBehavior`s from this list to each one.

#### 9.3 SceneCollectionRoot Mode Settings

* **Scene Root Groups Setup \[Foldout]:** Define your "master" root GameObjects here. The order of groups determines their reveal sequence.
* **"Populate/Refresh Collections" \[Button]:** Auto-populates the "Child Collections" list with the direct children of the assigned `Group Root Object`.
* **Configuring Child Collections:**
  * You can override timing, behaviors, and delays for each collection individually.
  * **Wait For This Collection Completion:** If true, the manager waits for all items in this collection to finish before starting the next collection.
* **Global Collection Item Settings \[Foldout]:** These are the fallback settings used for items within any collection that does not have `Override Global...` checked.

#### 9.4 Overall Timing & Control

These settings apply globally to the entire sequence.

* **Overall Reveal Delay:** Initial delay before the entire sequence begins.
* **Delay Between Objects / Scene Root Groups:** Time gap between one top-level item starting and the next.
* **Start Objects Hidden:** **(Highly Recommended)** Automatically hides all configured objects at startup.
* **Start Automatically:** If true, the sequence begins on scene load. If false, you must trigger it via script.
* **Loop Sequence & Loop Delay:** Settings to make the entire reveal sequence restart after completion.
* **Manage Colliders:** If true, disables colliders on objects while they are animating.
* **Group Completion Synchronization:** Advanced settings to force child-sequential groups to finish in a specific target duration.

#### 9.5 Debug & Gizmo Options

This section helps you visualize and troubleshoot your sequences.

* **Enable Debug Logs:** If checked, SRP will print detailed log messages to the Unity Console.
* **Enable Gizmos:** Master toggle for all Scene View Gizmos drawn by SRP.
* **(Conditional) Gizmo Display Settings:**
  * **Show Only Selected Gizmos:** If true, Gizmos are only drawn for the item currently selected in the SRP inspector's lists.
  * **Gizmo Category Visibility:** Checkboxes to toggle visibility for Move, Rotate, Randomization Ranges, etc.

### 10. Configuring Reveal Behaviors

#### 10.1 Common Behavior Settings

These settings are available for all `RevealBehavior` types:

* **Type \[Enum]:** The kind of animation to perform.
* **Animation Mode \[Enum]:** `Once`, `Loop`, or `PingPong`.
* **Duration \[Float]:** The base duration for one cycle of the animation.
* **Curve \[AnimationCurve]:** Defines the easing or timing of the animation over its `Duration`.
* **NEW! audioSettings \[Foldout]:** Contains all settings for playing audio for this behavior.
* **NEW! audioTriggerPoint \[Slider]:** Controls the timing of the audio playback relative to the `Duration`.

#### 10.2 Behavior Types Explained

Each `Type` has specific settings:

* **Scale:** Animates `transform.localScale`, typically from `Vector3.zero`.
* **Move:** Animates `transform.position` (or `RectTransform.anchoredPosition` for UI) from an offset.
* **Rotate:** Animates `transform.localRotation` or `transform.rotation` from an offset.
* **ColorTint:** Animates a specified color property of a Material.
* **Fade:** Animates the `alpha` of a `CanvasGroup` component. Requires a `CanvasGroup` on the target object.

#### 10.3 Adding Randomization

Inject life into your animations! These settings are found within each `RevealBehavior`.

* **Randomize Duration:** If checked, the static `Duration` field is ignored, and a random duration between `Duration Range Min/Max` is used for each object.
* **Randomize Offset:** (Applies to `Move` and `Rotate` only). If checked, an additional random offset is added to the base offset.
* **NEW! Offset Distribution Type \[Enum]:** Dictates how the random offset is calculated (`UniformBox`, `UniformSphereSurface`, etc.).
* **NEW! Sphere Radius \[Float]:** Used by sphere distribution modes.
* **NEW! Offset Magnitude Curve \[AnimationCurve]:** Used by `PerAxisCurveScaled` mode to artistically control the distribution of random values.

### 11. Advanced SRP Features

#### 11.1 Unreveal Sequence (Hiding Objects)

SRP isn't just for making things appear; it can make them disappear with equal flair!

* **Triggering:** Call `StartUnrevealManually()` on the `SS_SceneRevealManager` component.
* **Behavior During Unreveal:**
  * **Reverse Order:** Objects and collections are processed in the exact reverse order of their reveal sequence.
  * **Reversed Animations:** `RevealBehaviors` play "in reverse"—from their fully revealed state back to their initial hidden/offset state.
  * **Forced "Once" Mode:** All `RevealBehaviors` are effectively treated as `AnimationMode.Once` during unreveal.
  * **Smooth Deactivation:** If `Start Objects Hidden` is true, GameObjects will be set `SetActive(false)` immediately after their individual unreveal animation completes.

#### 11.2 Handling UI Elements

Animating UI elements requires special attention:

* **RectTransform.anchoredPosition for Move:** When a `Move` behavior is applied to a UI element, SRP intelligently animates its `RectTransform.anchoredPosition` (a `Vector2`) instead of its world position, providing more stable movement within a Canvas.
* **Fade Behavior with CanvasGroup:** The `Fade` behavior is perfect for UI. Ensure the UI GameObject (or its parent) has a `CanvasGroup` component.
* **Layout Groups (Important Caveat!):** If your UI element is directly controlled by an active `Layout Group` (e.g., `VerticalLayoutGroup`), the Layout Group will typically override any positional changes from SRP's `Move` behavior. For these elements, prefer using `Scale`, `ColorTint`, or `Fade`.

#### 11.3 Group Completion Synchronization

This advanced feature allows you to define a target duration for groups of objects that reveal their children sequentially. The system will then attempt to adjust animation durations and/or delays within that group to meet the target. See the inspector tooltips for `Force Synchronized Group Completion` for more details.

### 12. Manual Control via Scripting (SRP)

If `Start Automatically` is disabled on the `SS_SceneRevealManager`, you can trigger sequences programmatically. First, get a reference to your manager.

#### 12.1 Available Public Methods

* **`public void StartRevealManually()`**
  * Call this method to begin the reveal sequence. It respects all configured settings (delays, looping, etc.). If a sequence is already running, it will be stopped, reset, and restarted. This is the primary way to kick off a reveal.
* **`public void StartUnrevealManually()`**
  * Call this to initiate the unreveal sequence. It will stop any currently running reveal/unreveal sequence from this manager. Objects animate from their current state to their hidden/offset state in reverse order.
* **`public void ResetManagerAndSetInitialState()`**
  * Call this method to immediately stop any and all animations and force all configured objects back to their initial "hidden" or "offset" state. This does not automatically restart the sequence; it's purely for resetting the visual state.

#### 12.2 Example Script

```
using UnityEngine;
using StoneSoftStudios.SRP; // ADD THE NAMESPACE

public class MyGameController : MonoBehaviour 
{
    public SS_SceneRevealManager mainIntroSequenceManager; // Assign in Inspector

    void Start() 
    {
        if (mainIntroSequenceManager == null) 
        {
            Debug.LogError("SceneRevealManager reference not set!", this);
            return;
        }

        // Example: Start sequence after a delay if not auto-starting
        if (!mainIntroSequenceManager.startAutomatically)
        {
            // You could invoke it, or call it from another event
            // Invoke("PlayIntroSequence", 2.0f);
        }
    }

    // Public methods to be called from UI Buttons or other events
    public void PlayIntroSequence() 
    {
        if (mainIntroSequenceManager != null) 
        {
            mainIntroSequenceManager.StartRevealManually();
        }
    }

    public void HideIntroElements() 
    {
        if (mainIntroSequenceManager != null) 
        {
            mainIntroSequenceManager.StartUnrevealManually();
        }
    }

    public void ResetIntroVisuals() 
    {
        if (mainIntroSequenceManager != null) 
        {
            mainIntroSequenceManager.ResetManagerAndSetInitialState();
        }
    }

    // Example for testing with keyboard input
    void Update() 
    {
        if (Input.GetKeyDown(KeyCode.P)) PlayIntroSequence();
        if (Input.GetKeyDown(KeyCode.H)) HideIntroElements();
        if (Input.GetKeyDown(KeyCode.R)) ResetIntroVisuals();
    }
}

```

### 13. Manual Control via Scripting (Message Cycler)

You can control the `SS_MessageCycler` component from your own scripts to create interactive tutorials, dialogues, and more.

#### 13.1 Available Public Methods

* **`void ShowNextMessage()`**: Triggers the process of hiding the current message and showing the next one in the sequence. This is the most common method you will call.
* **`void ShowPreviousMessage()`**: Hides the current message and shows the previous one.
* **`void GoToCollection(int collectionIndex)`**: Immediately switches to a specific `MessageCollection` by its index in the list.
* **`void GoToNextCollection()`**: Switches to the next collection in the list, looping if enabled.
* **`void GoToPreviousCollection()`**: Switches to the previous collection in the list, looping if enabled.
* **`void ResetCurrentCollectionMessages()`**: Resets the state of the *currently active* collection (hides messages, resets index to -1 or 0 if `alwaysShowFirstMessageOnStart` is true).
* **`void ResetEntireCycler()`**: Resets the entire component to its initial state, including setting the active collection index back to the beginning.
* **`MessageCollection GetCurrentMessageCollection()`**: Returns the currently active `MessageCollection` object, allowing you to inspect its properties.

#### 13.2 Example Script

This example shows how to hook up a UI Button to advance through messages.

```
using UnityEngine;
using UnityEngine.UI; // Required for Button
using StoneSoftStudios.SRP; // Your asset's namespace

public class TutorialNavigation : MonoBehaviour 
{
    // Assign the GameObject with the SS_MessageCycler component in the Inspector
    public SS_MessageCycler tutorialCycler; 
    
    // Assign the "Next" button from your Canvas in the Inspector
    public Button nextButton;
    public Button previousButton; // Optional

    void Start() 
    {
        if (tutorialCycler == null)
        {
            Debug.LogError("Tutorial Cycler reference not set!", this);
            return;
        }

        if (nextButton != null) 
        {
            // Add a listener to the button's onClick event that calls our method
            nextButton.onClick.AddListener(OnNextClicked);
        }

        if (previousButton != null)
        {
            previousButton.onClick.AddListener(OnPreviousClicked);
        }
    }

    // This method will be called every time the "Next" button is clicked
    public void OnNextClicked() 
    {
        if (tutorialCycler != null) 
        {
            tutorialCycler.ShowNextMessage();
        }
    }

    // This method will be called by the "Previous" button
    public void OnPreviousClicked()
    {
        if (tutorialCycler != null)
        {
            tutorialCycler.ShowPreviousMessage();
        }
    }
}

```

### 14. Troubleshooting & FAQ

* **Q: My objects "pop in" briefly before animating.**
  * **A:** Ensure **Start Objects Hidden** is checked on your `SS_SceneRevealManager`. This is the #1 reason for this behavior.
* **Q: Animations aren't playing at all.**
  * **A:** Check if `Start Automatically` is enabled, or if you are correctly calling `StartRevealManually()` from a script. Also, ensure `Duration` values in your `RevealBehaviors` are greater than 0. Check the console for any error messages from `[SRM]`.
* **Q: My audio isn't playing for a behavior.**
  * **A:** Check:
    1. In the `RevealBehavior`, is `Audio Settings > Enabled` checked?
    2. Is at least one `AudioClip` assigned?
    3. Is there an `AudioListener` in your scene?
    4. Is the `playbackDelayRange` reasonable?
* **Q: My UI elements are in the wrong position after a Move animation.**
  * **A:** If the UI element is a child of a `Layout Group`, the layout group will override its position. Prefer `Scale`, `ColorTint`, or `Fade` behaviors on such elements.

### 15. Changelog

#### **v1.4.0 (June 14, 2025)**

This is a major update focusing on adding a comprehensive new audio system, a powerful editor theming system, and significant under-the-hood improvements to stability, workflow, and visualization.

#### ⭐ **Major New Features** ⭐

* **NEW: Per-Behavior Audio System**
  * A complete audio system has been integrated directly into `RevealBehavior`s.
  * **`RevealAudioSettings`:** Each behavior now has its own collapsible section for audio, allowing you to assign unique sounds to specific animations (e.g., a "swoosh" for Move, a "thump" for Scale).
  * **`audioTriggerPoint` Slider:** Precisely control *when* a sound plays during an animation's duration (from 0.0 at the start to 1.0 at the end).
  * **`SS_AudioPool` Singleton:** A new, persistent audio manager handles the creation and reuse of `AudioSource` components efficiently, preventing scene clutter and ensuring high performance.
  * **Flexible Playback:** Audio settings include randomized playback delay, clip selection order (random or sequential), and randomized volume/pitch.
  * **`SS_RevealAudioSettingsDrawer`:** A new custom inspector drawer provides a clean UI for all audio settings, including a **"Test Sound"** button to preview your audio configuration directly in the editor.
* **NEW: Customizable Editor Themes**
  * **`SS_EditorTheme` ScriptableObject:** You can now create, save, and share custom editor themes to personalize the inspector's appearance. Create new themes via `Assets > Create > StoneSoft Studios > Editor Theme`.
  * **Live Theme Customization:** A new "Editor Theme" foldout in the `SS_SceneRevealManager` and `SS_MessageCycler` inspectors allows you to select from existing themes and modify their colors in real-time.
  * **Save & Share:** Save your customized color settings as a new theme asset directly from the inspector.
  * **Built-in Themes:** The asset now includes "StoneSoft Dark" (default) and "Classic Light" themes to get you started.

#### 🚀 **Improvements & Enhancements** 🚀

* **IMPROVED: State Management & Reliability**
  * Implemented a new "ground truth" state capture system. The manager now captures and stores the definitive original state (position, rotation, scale, color, alpha) of all objects on `Awake`. This makes animations, especially after resets or in complex UI scenarios, significantly more reliable and predictable.
  * The core initialization flow in `Awake()` and `Start()` has been refactored for better stability and a more logical order of operations.
* **IMPROVED: Editor UI & Workflow**
  * The custom inspectors for both `SS_SceneRevealManager` and `SS_MessageCycler` now use the new theming system for a more polished and consistent user interface.
  * The reorderable lists in the inspector now use dedicated custom drawers (`SS_ObjectToRevealDrawer`, `SS_RevealBehaviorDrawer`), resulting in cleaner layouts and more maintainable code.
  * The inspector foldouts have been reorganized for better clarity, with runtime controls and persistence options now grouped under a dedicated "Editor Actions" section.
  * The UI for `SceneCollectionRoot` mode, particularly the nested lists for collections and their overrides, has been improved for better readability.
* **IMPROVED: Gizmo System**
  * Gizmos are now significantly more accurate in Play Mode, as they use the "ground truth" data captured at startup for their positioning.
  * The "Show Only Selected Gizmos" feature is now fully implemented, linking inspector list selections directly to which gizmos are drawn in the Scene View for a less cluttered workflow.
* **IMPROVED: API & Method Calls**
  * The public API has been streamlined. `StartRevealManually()` is now the definitive method for starting a sequence via script. Older, more complex methods have been deprecated internally.
  * Public methods like `ResetManagerAndSetInitialState()` and `StartUnrevealManually()` are now more robust as they leverage the new ground-truth state system.

#### 🐞 **Fixes** 🐞

* **FIXED:** The `DeepCopyBehaviors` method now correctly copies all properties, including the new `audioSettings` and `audioTriggerPoint`, preventing issues when using default behaviors or collection overrides.
* **FIXED:** Collider state management is now more robust, preventing cases where colliders might not be re-enabled correctly after an unreveal sequence or reset.
* **FIXED:** Resolved potential null reference exceptions in editor scripts that could occur if a target object was destroyed while the inspector was visible.
* **FIXED:** The logic for drawing reorderable list backgrounds and handles has been corrected to prevent visual glitches in different Unity versions.

**v1.3.0 ( June 5, 2025)**

* **MAJOR NEW FEATURE: Message Cycler System (**`**SS_MessageCycler**`**)**
  * Introduced `SS_MessageCycler` component for managing sequences of GameObjects (messages).
  * Supports multiple `MessageCollection`s, each with an array of `MessageItem`s.
  * Collection-level settings: `loopThisCollection`, `stopAndHideAllOnNextClick`, `alwaysShowFirstMessageOnStart`.
  * Master cycling behavior: `cycleThroughCollectionsOnEnable`, `loopCollectionList`, `CompleteInitialSetupOnFirstEnable`.
  * Rich set of UnityEvents: `OnBeforeShowMessage`, `OnBeforeHideMessage` (for SRP integration), `onMessageShown`, `onMessageHidden`, and collection-level events.
  * Full scripting API for manual control including `GoToNextCollection()` and `GoToPreviousCollection()`.
  * Custom editor `SS_MessageCyclerEditor` for easy configuration.
* **NEW: Scene Reveal Manager Integration with Message Cycler**
  * `ObjectToReveal` (in `ManualList` mode) can now act as a "Message Cycler Host."
  * Added `isMessageCyclerHost` (bool) to `ObjectToReveal`.
  * Added `messageItemRevealBehaviors` (List<`RevealBehavior`>) to `ObjectToReveal` to define SRP animations for Cycler messages.
  * Added `respectCyclerInitialState` (bool) to `ObjectToReveal` for nuanced initial display of the first message when SRP's `startObjectsHidden` is active.
  * SRP now listens to `OnBeforeShowMessage`/`OnBeforeHideMessage` from a hosted Cycler and calls `NotifyMessageActuallyShown`/`NotifyMessageActuallyHidden` back after animating.
* **NEW: Fade (CanvasGroup) Reveal Behavior**
  * Added `Fade` to `RevealBehavior.BehaviorType`.
  * Animates `CanvasGroup.alpha`. Requires `CanvasGroup` component on the target.
  * Added `startAlpha` (float) property to `RevealBehavior`.
* **NEW: Per-ObjectToReveal Events**
  * Added `onMainRevealStart`, `onMainRevealComplete`, `onMainUnrevealStart`, `onMainUnrevealComplete` UnityEvents to `ObjectToReveal` for fine-grained control over individual item sequences.
* **ENHANCED: Advanced Randomization for Move/Rotate Offsets in** `**RevealBehavior**`
  * Added `OffsetDistribution` enum: `UniformBox`, `UniformSphereSurface`, `UniformSphereVolume`, `PerAxisCurveScaled`.
  * Added `sphereRadius` (float) field for sphere distribution modes.
  * Added `offsetMagnitudeCurve` (`AnimationCurve`) for `PerAxisCurveScaled` distribution.
* **ENHANCED: Gizmos & Debugging for Scene Reveal Manager**
  * Separated `enableDebugLogs` (for console output) from Gizmo visibility.
  * Added master `enableGizmos` toggle.
  * Added fine-grained Gizmo category toggles: `showMoveGizmos`, `showRotateGizmos`, `showRandomizationRanges`, `showChildStaggerConnections`, `showSceneCollectionGroupGizmos`, `showLabels`.
  * Added `showOnlySelectedGizmos` option to focus Gizmos on the inspector-selected item.
  * Gizmos now attempt to draw in Edit Mode.
* **NEW: Editor Play Mode Persistence for Scene Reveal Manager**
  * Added `editorPersistPlayModeChanges` (bool) toggle. When ON, serializable SRP manager changes made during Play Mode are saved back to the scene.
* **NEW: Runtime Controls in Inspector**
  * Added "Runtime Controls" box in the SRP inspector (visible in Play Mode) with buttons: "Reset & Set Initial", "Start Reveal", "Start Unreveal".
* **IMPROVED: Global Event Naming & Behavior**
  * Global event `onOverallRevealStarted` (formerly potentially misconstrued) now clearly documented to fire only ONCE at the beginning of the entire sequence. Consistent naming `onOverallUnrevealStarted`.
* **IMPROVED: Editor UI & Workflow**
  * `SS_ObjectToRevealDrawer`: Foldout label now shows the name of the assigned GameObject for better identification in lists.
  * `SS_SceneRevealManagerEditor`:
    * UI for new Gizmo toggles and Play Mode Persistence.
    * Gizmo focus now linked to inspector list selections.
    * Better handling of mutually exclusive options in `ObjectToReveal` (e.g., `isMessageCyclerHost` vs. `revealChildrenSequentially`).
* **FIXED:** Resolved potential null reference issues in editor scripts if target was destroyed.
* **DOC:** This documentation completely revised and updated for v1.3.0.

**v1.2.0 (May 21, 2025)**

* NEW: `OperatingMode` Enum (`ManualList`, `AutoSceneRoots`, `SceneCollectionRoot`).
* NEW: `SceneCollectionRoot` Mode Implemented. (Initial version, later refined)
* NEW: Group Completion Synchronization feature.
* NEW: Full Unreveal Sequence via `StartUnrevealManually()`.
* NEW: `onUnrevealStarted` and `onUnrevealComplete` UnityEvents (original names, later updated to `onOverall...`).
* NEW: `manageColliders` option.
* IMPROVED: Handling UI Elements for `Move` behaviors.
* IMPROVED: Custom Editor with dynamic sections, nested lists, better labels.
* FIXED: Various minor bugs and editor quirks.
* DOC: Documentation extensively revised.

**v1.1.0 (May 19, 2025)**

* NEW: "Wait for Completion" option (`waitForCompletion`) in `ObjectToReveal`.
* IMPROVED: Demo scene with more examples.

**v1.0.0 (May 15, 2025)**

* Core behaviors: `Scale`, `Move`, `Rotate`, `ColorTint`.
* `ManualList` and `AutoSceneRoots` operating modes.
* Basic timing controls, looping, randomization.
* `onRevealStarted`, `onRevealComplete` UnityEvents (original names, later updated).

Happy Animating! *- StoneSoft Studios*