Navigathena Scene Management Framework

If you need to override a transition while it is in progress (e.g., an event scene detects it is no longer valid during OnInitialize), you can call a navigation method like Pop or Push from the GlobalSceneNavigator.Instance.

When a new transition is initiated, Navigathena cancels the CancellationTokenSource managed by the SceneNavigator. This causes the CancellationToken passed into the current lifecycle events (like OnInitialize) to enter a canceled state. Subsequent lifecycle methods, such as OnEnter, will not be called if the transition is interrupted.

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);

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

protected override UniTask OnEnter (ISceneDataReader reader, CancellationToken cancellationToken)
{
  // This will not be called if Pop was called in OnInitialize
  Debug.Log("EventSceneEntryPoint.OnEnter");
  return UniTask.CompletedTask;
}

To pass information from one scene to another (e.g., a selected character ID or the state of a UI menu), use the ISceneData interface.

• Sending Data: Pass an object implementing ISceneData as an argument to ISceneNavigator.Push. This data is available in the destination scene's ISceneEntryPoint.OnInitialize or OnEnter via the ISceneDataReader.
• Saving/Restoring State: Use ISceneDataWriter in ISceneEntryPoint.OnExit or OnFinalize to write data. This allows you to store the state of a scene so it can be restored when the user returns to it.

Best Practice: Define one ISceneData type per scene to maintain type safety and clarity.

// Define the data contract
public sealed class HomeSceneData : ISceneData
{
  public HomeScreenType LastDisplayedScreenType { get; init; }
}

public sealed class HomeSceneEntryPoint : SceneEntryPoint
{
  protected override UniTask OnInitialize (ISceneDataReader reader, CancellationToken cancellationToken)
  {
    // Retrieve saved state from the reader
    if (reader.TryRead(out HomeSceneData sceneData))
    {
      m_View.SetScreen(sceneData.LastDisplayedScreenType);
    }
  }

  protected override UniTask OnFinalize (ISceneWriter writer, CancellationToken cancellationToken)
  {
    // Store current state to be passed to the next scene or restored later
    writer.Write(new HomeSceneData
    {
      LastDisplayedScreenType = m_View.ScreenType
    });
  }
}

To have a scene that persists throughout the entire application lifespan (a "Root" scene), extend ScopedSceneEntryPoint and override the EnsureParentScope method. You can use this phase to load the root scene additively and build its LifetimeScope container.

public sealed class MyProjectScopedSceneEntryPoint : ScopedSceneEntryPoint
{
  const string kRootSceneName = "Root";

  protected override async UniTask<LifetimeScope> EnsureParentScope (CancellationToken cancellationToken)
  {
    // Load root scene additively if not loaded
    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 in the hierarchy
    EditorSceneManager.MoveSceneBefore(rootScene, gameObject.scene);
#endif

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

Navigathena supports Unity Addressables through the AddressableSceneIdentifier. While BuiltInSceneIdentifier is used for standard scenes, AddressableSceneIdentifier allows you to treat Addressable assets as scenes, handling their loading and unloading seamlessly within the framework.

When using AddressableSceneIdentifier, the framework wraps Addressables' LoadSceneAsync and UnloadSceneAsync calls. Note that downloading assets is not handled by Navigathena; you should manage pre-download logic separately.

using MackySoft.Navigathena.SceneManagement;
using MackySoft.Navigathena.SceneManagement.AddressableAssets;

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

  // Use AddressableSceneIdentifier for scenes requiring Addressables dependency resolution
  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");
}

You can display real-time progress (e.g., loading bars or status messages) during a transition by using IProgress<IProgressDataStore>.

1. Define a data type: Create a struct or class (e.g., MyProgressData) to hold the information you want to display.
2. Implement IProgress in your Handle: Your ITransitionHandle should implement IProgress<IProgressDataStore>. In the Report method, use progressDataStore.TryGetData<T>(out var data) to extract your custom data and update your UI.
3. Report progress from SceneEntryPoints: Inside ISceneEntryPoint methods like OnInitialize, use the provided IProgress<IProgressDataStore> to report updates using a ProgressDataStore<T>.

// 1. Define data
public readonly struct MyProgressData
{
  public float Progress { get; }
  public string Message { get; }
  public MyProgressData (float progress, string message) { Progress = progress; Message = message; }
}

// 2. Implement progress in the handle
sealed class SimpleTransitionHandle : ITransitionHandle, IProgress<IProgressDataStore>
{
  void IProgress<IProgressDataStore>.Report (IProgressDataStore progressDataStore)
  {
    if (progressDataStore.TryGetData(out MyProgressData myProgressData))
    {
      m_ProgressText.text = myProgressData.Progress.ToString("P0");
      m_MessageText.text = myProgressData.Message;
      m_ProgressSlider.value = myProgressData.Progress;
    }
  }
}

// 3. Report from SceneEntryPoint
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")));
}

To implement a custom transition, extend ITransitionDirector and create a nested class (or separate class) that implements ITransitionHandle.

In the example below, SimpleTransitionDirector uses a CanvasGroup and DOTween to fade the UI in and out during the transition process.

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);
    }
  }
}

// Usage:
await GlobalSceneNavigator.Instance.Push(new BuiltInSceneIdentifier("MyScene"), new SimpleTransitionDirector(m_CanvasGroup));