### Basic Scene Push Example

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Demonstrates the basic usage of pushing a scene onto the navigation stack using the GlobalSceneNavigator instance and a BuiltInSceneIdentifier.

```C#
ISceneIdentifier identifier = new BuiltInSceneIdentifier("Game");
await GlobalSceneNavigator.Instance.Push(identifier);
```

--------------------------------

### Basic Scene Navigation with SceneEntryPoint

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Illustrates the fundamental usage of Navigathena by defining a scene entry point. This example shows how to handle scene transitions, specifically loading the 'Game' scene when a button is clicked, using `SceneEntryPointBase` and `GlobalSceneNavigator`. It depends on Unity, UniTask, and the Navigathena library.

```csharp
using UnityEngine;
using UnityEngine.UI;
using System.Threading;
using Cysharp.Threading.Tasks;
using MackySoft.Navigathena.SceneManagement;

// Defines the entry point for the scene.
public sealed class HomeSceneEntryPoint : SceneEntryPointBase
{

  // Define the scene to be used.
  static readonly ISceneIdentifier s_GameSceneIdentifier = new BuiltInSceneIdentifier("Game");

  [SerializeField]
  Button m_LoadGameButton;

  IDisposable m_Subscription;

  // The basic lifecycle of the scene is invoked. (OnInitialize, OnEnter, OnExit, OnFinalize...)
  protected override UniTask OnEnter (ISceneDataReader reader, CancellationToken cancellationToken)
  {
    m_Subscription = m_LoadGameButton.OnClickAsAsyncEnumerable().SubscribeAwait(_ => OnLoadGameButtonClick());
    return UniTask.CompletedTask;
  }

  protected override UniTask OnExit (ISceneDataWriter writer, CancellationToken cancellationToken)
  {
    m_Subscription?.Dispose();
    return UniTask.CompletedTask;
  }

  async UniTask OnLoadGameButtonClick ()
  {
    // Perform scene transition operations via GlobalSceneNavigator.
    await GlobalSceneNavigator.Instance.Push(s_GameSceneIdentifier);
  }
}
```

--------------------------------

### Inter-Scene Data Transfer with ISceneData

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Illustrates passing data between scenes using ISceneData, ISceneDataReader, and ISceneDataWriter. Includes an example of a scene entry point handling data initialization and finalization.

```cs
public sealed class HomeSceneData : ISceneData
{
  public HomeScreenType LastDisplayedScreenType { get; init; }
}

public sealed class HomeSceneEntryPoint : SceneEntryPoint
{
  [SerializeField]
  HomeView m_View;

  protected override UniTask OnInitialize (ISceneDataReader reader, CancellationToken cancellationToken)
  {
    if (reader.TryRead(out HomeSceneData sceneData))
    {
      m_View.SetScreen(sceneData.LastDisplayedScreenType);
    }
    return UniTask.CompletedTask;
  }

  protected override UniTask OnFinalize (ISceneWriter writer, CancellationToken cancellationToken)
  {
    writer.Write(new HomeSceneData
    {
      LastDisplayedScreenType = m_View.ScreenType
    });
    return UniTask.CompletedTask;
  }
}
```

--------------------------------

### C# Usage Example: Scene Transition with SimpleTransitionDirector

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Demonstrates how to initiate a scene transition using a custom transition director. This example shows passing a SimpleTransitionDirector instance to the GlobalSceneNavigator for a fade transition.

```C#
// Load a new scene while executing the direction with SimpleTransitionDirector.
await GlobalSceneNavigator.Instance.Push(new BuiltInSceneIdentifier("MyScene"), new SimpleTransitionDirector(m_CanvasGroup));
```

--------------------------------

### Register Standard Scene Navigator with Custom Factory

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Shows the initialization process where `StandardSceneNavigator` is registered with `GlobalSceneNavigator`. This example includes registering a custom `MySceneProgressFactory` to handle scene progress data.

```C#
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
static void Initialize ()
{
  // Initialize and register the StandardSceneNavigator with our own MySceneProgressFactory.
  GlobalSceneNavigator.Instance.Register(new StandardSceneNavigator(TransitionDirector.Empty(), new MySceneProgressFactory()));
}
```

--------------------------------

### TitleSceneEntryPoint.cs Implementation

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Example implementation of a SceneEntryPoint for a title scene. It inherits from SceneEntryPointBase and overrides the OnEnter method to perform asynchronous operations. Requires Cysharp.Threading.Tasks and MackySoft.Navigathena.SceneManagement.

```cs
using System.Threading;
using Cysharp.Threading.Tasks;
using MackySoft.Navigathena.SceneManagement;

// タイトルシーンのSceneEntryPointを実装するコンポーネント
public sealed class TitleSceneEntryPoint : SceneEntryPointBase
{
  protected override async UniTask OnEnter (ISceneDataReader reader, CancellationToken cancellationToken)
  {
    await DoSomething(cancellationToken);
  }
}
```

--------------------------------

### C# SimpleTransitionDirector Implementation

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

An example implementation of a transition director that realizes a simple fade-in and fade-out effect using CanvasGroup and DOTween. It creates a handle to manage the transition lifecycle.

```C#
public sealed class SimpleTransitionDirector : ITransitionDirector
{

  readonly CanvasGroup m_CanvasGroup;

  public SimpleTransitionDirector (CanvasGroup canvasGroup)
  {
    m_CanvasGroup = canvasGroup;
  }

  public ITransitionHandle Create ()
  {
    return new SimpleTransitionHandle(m_CanvasGroup);
  }

  sealed class SimpleTransitionHandle : ITransitionHandle
  {

    readonly CanvasGroup m_CanvasGroup;

    public SimpleTransitionHandle (CanvasGroup canvasGroup)
    {
      m_CanvasGroup = canvasGroup;
    }

    public async UniTask Start (CancellationToken cancellationToken = default)
    {
      // Play fade-in with DOTween.
      await m_CanvasGroup.DOFade(1f, 1f).ToUniTask(cancellationToken: cancellationToken);
    }

    public async UniTask End (CancellationToken cancellationToken = default)
    {
      await m_CanvasGroup.DOFade(0f, 1f).ToUniTask(cancellationToken: cancellationToken);
    }
  }
}
```

--------------------------------

### C# Interfaces for Scene Transition Control

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Defines the core interfaces for managing scene transitions in Navigathena. ITransitionDirector acts as a factory for ITransitionHandle, which controls the start and end of transition effects.

```C#
public interface ITransitionDirector
{
  ITransitionHandle CreateHandle ();
}

public interface ITransitionHandle
{
  UniTask Start (CancellationToken cancellationToken = default);
  UniTask End (CancellationToken cancellationToken = default);
}
```

--------------------------------

### Initiate Scene Transition with Custom Director

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Demonstrates how to initiate a scene transition using `GlobalSceneNavigator.Instance.Push`. It shows passing a custom `SimpleTransitionDirector` instance with its required UI components.

```C#
// Pass SimpleTransitionDirector when performing the transition operation.
await GlobalSceneNavigator.Instance.Push(new BuiltInSceneIdentifier("MyScene"), new SimpleTransitionDirector(m_CanvasGroup, m_ProgressText, m_MessageText, m_ProgressSlider));
```

--------------------------------

### Register Custom SceneNavigator

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Illustrates how to register a custom SceneNavigator implementation with the GlobalSceneNavigator at application startup using a RuntimeInitializeOnLoadMethod.

```C#
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
static void Initialize ()
{
  // Register a custom SceneNavigator
  GlobalSceneNavigator.Instance.Register(new MyCustomSceneNavigator());
}
```

--------------------------------

### Unity Editor Single Scene Launch Callback

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Provides an editor-specific callback `OnEditorFirstPreInitialize` for the first scene launched in the Unity editor. This allows writing initial data via `ISceneDataWriter` before `OnInitialize` or `OnEnter` are called, enhancing debugging efficiency. It must be enclosed in a `UNITY_EDITOR` directive.

```csharp
#if UNITY_EDITOR
protected override UniTask OnEditorFirstPreInitialize (ISceneDataWriter writer, CancellationToken cancellationToken)
{
  writer.Write(new IngameSceneData
  {
    CharacterId = m_CharacterId
  });
  return UniTask.CompletedTask;
}
#endif
```

--------------------------------

### Implement Transition Director with Progress Reporting

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Shows how to implement `ITransitionDirector` and `ITransitionHandle` to manage scene transitions and receive progress updates. The `SimpleTransitionHandle` implements `IProgress<IProgressDataStore>` to report progress, updating UI elements like text and sliders.

```C#
public sealed class SimpleTransitionDirector : ITransitionDirector
{

  readonly CanvasGroup m_CanvasGroup;
  readonly Text m_ProgressText;
  readonly Text m_MessageText;
  readonly Slider m_ProgressSlider;

  public SimpleTransitionDirector (CanvasGroup canvasGroup, Text progressText, Text messageText, Slider progressSlider)
  {
    m_CanvasGroup = canvasGroup;
    m_ProgressText = progressText;
    m_MessageText = messageText;
    m_ProgressSlider = progressSlider;
  }

  public ITransitionHandle Create ()
  {
    return new SimpleTransitionHandle(m_CanvasGroup, m_ProgressText, m_MessageText, m_ProgressSlider);
  }

  // By implementing IProgress<IProgressDataStore>, it is possible to receive progress information during the transition direction.
  sealed class SimpleTransitionHandle : ITransitionHandle, IProgress<IProgressDataStore>
  {

    readonly CanvasGroup m_CanvasGroup;
    readonly Text m_ProgressText;
    readonly Text m_MessageText;
    readonly Slider m_ProgressSlider;

    public SimpleTransitionHandle (CanvasGroup canvasGroup, Text progressText, Text messageText, SLider progressSlider)
    {
      m_CanvasGroup = canvasGroup;
      m_ProgressText = progressText;
      m_MessageText = messageText;
      m_ProgressSlider = progressSlider;
    }

    public async UniTask Start (CancellationToken cancellationToken = default)
    {
      await m_CanvasGroup.DOFade(1f,1f).ToUniTask(cancellationToken: cancellationToken);
    }

    public async UniTask Complete (CancellationToken cancellationToken = default)
    {
      await m_CanvasGroup.DOFade(0f,1f).ToUniTask(cancellationToken: cancellationToken);
    }

    void IProgress<IProgressDataStore>.Report (IProgressDataStore progressDataStore)
    {
      // Extract MyProgressData from IProgressStore.
      if (progressDataStore.TryGetData(out MyProgressData myProgressData))
      {
        m_ProgressText.text = myProgressData.Progress.ToString("P0");
        m_MessageText.text = myProgressData.Message;
        m_ProgressSlider.value = myProgressData.Progress;
      }
    }
  }
}
```

--------------------------------

### Report Progress During Scene Initialization

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Illustrates how to report progress updates from within a scene's initialization process (`OnInitialize`). It uses a `ProgressDataStore<MyProgressData>` to wrap custom data and reports it via the provided `IProgress<IProgressDataStore>`.

```C#
// ...

// When notifying progress, it gets notified up to the SimpleTransitionDirector.
protected override UniTask OnInitialize (ISceneDataReader reader, IProgress<IProgressDataStore> progress, CancellationToken cancellationToken)
{
  ProgressDataStore<MyProgressData> store = new();

  progress.Report(store.SetData(new MyProgressData(0.5f, "Generate Map")));

  await m_MapGenerator.Generate(cancellationToken);

  progress.Report(store.SetData(new MyProgressData(1f, "Complete")));
}
```

--------------------------------

### Interrupt Scene Transition with IAsyncOperation

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Demonstrates how to pass an IAsyncOperation to the GlobalSceneNavigator.Push method to execute processes between scene unloading and loading.

```cs
IAsyncOperation op = m_PreloadAsyncOperation;
await GlobalSceneNavigator.Push(nextScene, interruptOperation: op);
```

--------------------------------

### Load Persistent Root Scene in Unity

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Demonstrates loading a persistent 'Root scene' in Unity using Navigathena's `ScopedSceneEntryPoint`. It ensures the root scene is loaded additively if not already present and handles its integration into the application's lifecycle, potentially reordering it in the editor and building its `LifetimeScope`.

```csharp
public sealed class MyProjectScopedSceneEntryPoint : ScopedSceneEntryPoint
{

  const string kRootSceneName = "Root";

  protected override async UniTask<LifetimeScope> EnsureParentScope (CancellationToken cancellationToken)
  {
    // Load root scene.
    if (!SceneManager.GetSceneByName(kRootSceneName).isLoaded)
    {
      await SceneManager.LoadSceneAsync(kRootSceneName, LoadSceneMode.Additive)
        .ToUniTask(cancellationToken: cancellationToken);
    }

    Scene rootScene = SceneManager.GetSceneByName(kRootSceneName);

#if UNITY_EDITOR
    // Reorder root scene.
    EditorSceneManager.MoveSceneBefore(rootScene, gameObject.scene);
#endif

    // Build root LifetimeScope container.
    if (rootScene.TryGetComponentInScene(out LifetimeScope rootLifetimeScope, true) && rootLifetimeScope.Container == null)
    {
      await UniTask.RunOnThreadPool(() => rootLifetimeScope.Build(), cancellationToken: cancellationToken);
    }
    return rootLifetimeScope;
  }
}
```

--------------------------------

### IAsyncOperation Interface and Usage

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Defines the IAsyncOperation interface for asynchronous tasks during scene transitions and shows utility methods for creating and combining operations.

```APIDOC
IAsyncOperation Interface:
  ExecuteAsync(IProgress<IProgressDataStore> progress, CancellationToken cancellationToken = default)
    - Performs asynchronous operations between scene transitions.
    - Parameters:
      - progress: An interface for reporting progress.
      - cancellationToken: A token to signal cancellation.

AsyncOperation Utility Methods:
  Create(Func<IProgress<IProgressDataStore>, CancellationToken, UniTask> asyncAction)
    - Creates an IAsyncOperation from a lambda expression.
    - Parameters:
      - asyncAction: The asynchronous logic to execute.

  Combine(params IAsyncOperation[] operations)
    - Merges multiple IAsyncOperation instances into a single operation.
    - Parameters:
      - operations: An array of IAsyncOperation instances to combine.
```

--------------------------------

### ISceneNavigator Interface Methods

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Defines the core scene navigation operations provided by the ISceneNavigator interface. These methods manage scene transitions, history, and reloading.

```APIDOC
interface ISceneNavigator
{
  // Load the specified scene and add it to the history.
  UniTask Push (ISceneIdentifier identifier, ITransitionDirector transitionDirector = null, ISceneData sceneData = null, IAsyncOperation interruptOperation = null, CancellationToken cancellationToken = default);

  // Remove the head scene in the history and load the previous one.
  UniTask Pop (ITransitionDirector overrideTransitionDirector = null, IAsyncOperation interruptOperation = null, CancellationToken cancellationToken = default);

  // Load the specified scene and overwrite the history with only that scene.
  UniTask Change (ISceneIdentifier identifier, ITransitionDirector transitionDirector = null, ISceneData sceneData = null, IAsyncOperation interruptOperation = null, CancellationToken cancellationToken = default);

  // Load the specified scene and overwrite the head of the history.
  UniTask Replace (ISceneIdentifier identifier, ITransitionDirector transitionDirector = null, ISceneData sceneData = null, IAsyncOperation interruptOperation = null, CancellationToken cancellationToken = default);

  // Reload then current scene.
  UniTask Reload (ITransitionDirector overrideTransitionDirector = null, IAsyncOperation interruptOperation = null, CancellationToken cancellationToken = default);
}
```

--------------------------------

### ISceneEntryPoint Interface Methods

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Defines the interface for SceneEntryPoint components, outlining the lifecycle events that can be observed and handled during scene transitions. These methods allow custom logic execution at various stages of scene loading and unloading.

```APIDOC
ISceneEntryPoint:
  // Called after the start of the transition direction.
  UniTask OnInitialize (ISceneDataReader reader, IProgress<IProgressDataStore> transitionProgress, CancellationToken cancellationToken);

  // Called after the end of the transition direction.
  UniTask OnEnter (ISceneDataReader reader, CancellationToken cancellationToken);

  // Called before the start of the transition direction.
  UniTask OnExit (ISceneDataWriter writer, CancellationToken cancellationToken);

  // Called after the start of the transition direction.
  UniTask OnFinalize (ISceneDataWriter writer, IProgress<IProgressDataStore> transitionProgress, CancellationToken cancellationToken);

#if UNITY_EDITOR
  // Called before `OnInitialize` in the first loaded scene when executed in the editor. (Editor only)
  UniTask OnEditorFirstPreInitialize (ISceneDataWriter writer, CancellationToken cancellationToken);
#endif

// Method Signatures:
// OnInitialize(reader: ISceneDataReader, transitionProgress: IProgress<IProgressDataStore>, cancellationToken: CancellationToken): UniTask
// OnEnter(reader: ISceneDataReader, cancellationToken: CancellationToken): UniTask
// OnExit(writer: ISceneDataWriter, cancellationToken: CancellationToken): UniTask
// OnFinalize(writer: ISceneDataWriter, transitionProgress: IProgress<IProgressDataStore>, cancellationToken: CancellationToken): UniTask
// OnEditorFirstPreInitialize(writer: ISceneDataWriter, cancellationToken: CancellationToken): UniTask (Editor only)

// Parameter Descriptions:
// reader: Provides data from the previous scene or transition.
// writer: Allows writing data to be passed to the next scene or transition.
// transitionProgress: Reports progress during scene transitions.
// cancellationToken: Signals cancellation of the operation.

// Return Values:
// UniTask: Represents an asynchronous operation.
```

--------------------------------

### VContainer DI Integration with SceneLifecycle

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Shows how to integrate Navigathena with VContainer for dependency injection. Instead of inheriting from SceneEntryPoint, you register types implementing ISceneLifecycle with the DI container, decoupling scene lifecycle management from MonoBehaviours.

```csharp
using VContainer.Unity;
using VContainer.Internal;

public class ExampleSceneLifecycle : SceneLifecycle
{
  public override void Configure (IContainerBuilder builder)
  {
    builder.RegisterSceneLifecycle<TitleSceneLifecycle>();
  }
}
```

--------------------------------

### Interrupting Scene Transitions with Pop

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Demonstrates how to interrupt a current scene transition process and initiate a new one, such as returning to a previous scene using `Pop`. This is handled by Navigathena by canceling the `CancellationTokenSource` managed by the `SceneNavigator`, preventing subsequent `OnEnter` calls for the interrupted scene.

```csharp
protected override async UniTask OnInitialize (ISceneDataReader reader, IProgress<IProgressDataStore> progress, CancellationToken cancellationToken)
{
  // Assume the event has expired.
  bool isExpired = true;

  if (isExpired) {
    // NOTE: The cancellationToken is not passed to the transition operation because the cancellation state is canceled when the transition operation is performed.
    await GlobalSceneNavigator.Instance.Pop(CancellationToken.None);

    // true
    Debug.Log(cancellationToken.IsCancellationRequested);
  }
}

protected override UniTask OnEnter (ISceneDataReader reader, CancellationToken cancellationToken)
{
  Debug.Log("EventSceneEntryPoint.OnEnter");
  return UniTask.CompletedTask;
}
```

--------------------------------

### ISceneIdentifier and ISceneHandle Interfaces

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Defines the core interfaces for scene identification and handling within Navigathena. ISceneIdentifier creates an ISceneHandle, which is responsible for the actual loading and unloading process, abstracting away the underlying scene management implementation.

```csharp
using Cysharp.Threading.Tasks;
using System.Threading;
using UnityEngine.SceneManagement;
using System;

public interface ISceneIdentifier
{
  ISceneHandle CreateHandle ();
}

public interface ISceneHandle
{
  UniTask<Scene> Load (IProgress<float> progress = null, CancellationToken cancellationToken = default);
  UniTask Unload (IProgress<float> progress = null, CancellationToken cancellationToken = default);
}
```

--------------------------------

### Addressables SceneIdentifier Usage in C#

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Demonstrates how to use AddressableSceneIdentifier for scenes managed by Unity's Addressables package. This identifier requires Addressables dependencies to be resolved and is used for scenes that are not built-in.

```csharp
using MackySoft.Navigathena.SceneManagement;
using MackySoft.Navigathena.SceneManagement.AddressableAssets;

// Definition of scenes used in the project
public static class SceneDefinitions
{

  // Use BuiltInSceneIdentifier for splash
  public static ISceneIdentifier Splash { get; } = new BuiltInSceneIdentifier("Splash");

  // For post-splash scenes, use AddressableSceneIdentifier because Addressables dependencies need to be resolved
  // Pass `object key` as argument
  public static ISceneIdentifier Title { get; } = new AddressableSceneIdentifier("Title");
  public static ISceneIdentifier Introduction { get; } = new AddressableSceneIdentifier("Introduction");
  public static ISceneIdentifier Home { get; } = new AddressableSceneIdentifier("Home");
  public static ISceneIdentifier Game { get; } = new AddressableSceneIdentifier("Game");
}
```

--------------------------------

### Define Custom Progress Data Structure

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Defines a custom struct `MyProgressData` to hold progress percentage and a message for transition feedback. This structure is used to pass specific progress information through the `IProgressDataStore`.

```C#
public readonly struct MyProgressData
{
  
  public float Progress { get; }
  public string Message { get; }

  public MyProgressData (float progress, string message)
  {
    Progress = progress;
    Message = message;
  }
}
```

--------------------------------

### Manipulating Scene History with ISceneHistoryBuilder

Source: https://github.com/mackysoft/navigathena/blob/main/README.md

Explains how to directly manipulate the scene history of an `ISceneNavigator` using the `ISceneHistoryBuilder` interface, accessed via `IUnsafeSceneNavigator.GetHistoryBuilderUnsafe`. This allows operations like removing history entries or adding new ones before a transition. History manipulation must be completed before initiating a transition operation.

```csharp
using MackySoft.Navigathena.SceneManagement;
using MackySoft.Navigathena.SceneManagement.Unsafe; // Required for IUnsafeSceneNavigator features

//...

// Remove all except the current scene from the current history, add the Home scene as one previous scene, and reconstruct the history.
GlobalSceneNavigator.Instance.GetHistoryBuilderUnsafe()
  .RemoveAllExceptCurrent()
  .Add(new SceneHistoryEntry(SceneDefinitions.Home, TransitionDefinitions.Loading, new SceneDataStore())))
  .Build();

// Pop to return to the Home scene.
await GlobalSceneNavigator.Instance.Pop();
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.