UnityScreenNavigator

Unity Screen Navigator 日本語ドキュメント(Japanese Documents Available)

Library for screen transitions, transition animations, transition history stacking, and screen lifecycle management in Unity's uGUI.

Table of Contents

Details

• Overview
  • Features
  • Demo
• Setup
  • Requirement
  • Install
• Basic Screen Transition
  • Concept of screens and transitions
  • Create page and transition
  • Create modal and transition
  • Create sheet and transition
  • How to wait for the transition
  • Getting containers with static methods
• Screen Transition Animation
  • Setting common transition animations
  • Setting transition animation for each screen
  • Change transition animation according to partner screen
  • Screen transition animation and drawing order
  • Create simple transition animations easily
  • Implement interactive animation with partner screen
  • Create animation with Timeline
• Lifecycle Events
  • Lifecycle events of the page
  • Lifecycle events of the modal
  • Lifecycle events of the sheet
  • Use async methods instead of coroutines
• Loading Screen Resources
  • Change the loading method of screen resources
  • Use Addressable Asset System for the loading
  • Load synchronously
  • Preloading
• Other Features
  • Pop multiple screens at once
  • Don't stack pages in history
  • Change the backdrop of modals
  • Close the active modal when the backdrop is clicked
  • Enable interaction during transitions
  • Disable masking for container
  • Get information about playing animation information
  • Use loaded Prefab instances when loading screens
  • Changing the Behavior of the Modal Backdrop
• FAQ
  • How to make each Screen with Scene instead of Prefab
  • How to separate view and logic
  • How to pass data to each screen
  • How to reuse popped pages or modals
• License

Overview

Features

• You can create pages, modals, tabs and their transitions easily and flexibly.
• Manage screen lifecycle and memory from load to destroy.
• Separated workflow with animators for complex screen transition animations.
• Well-separated library with no extra functions (ex. GUI library, state machine).
• And standard features such as history stacking and click prevention during transitions.

Demo

You can play the demo scene with the following steps.

1. Clone this repository.
2. Open and play the following scene.
   • https://github.com/Haruma-K/UnityScreenNavigator/blob/master/Assets/Demo/Core/DemoEntryPoint.unity

Please note that some of the images used in this demo are from the following free contents.
For more information, including copyright, please refer to the following website.

• JewelSaviorFREE

Setup

Requirement

• Unity 6 (6000.0) or higher
• uGUI (UIElements not supported)

Install

1. Open the Package Manager from Window > Package Manager
2. "+" button > Add package from git URL
3. Enter the following to install
   • https://github.com/Haruma-K/UnityScreenNavigator.git?path=/Assets/UnityScreenNavigator

Or, open Packages/manifest.json and add the following to the dependencies block.

{
    "dependencies": {
        "com.harumak.unityscreennavigator": "https://github.com/Haruma-K/UnityScreenNavigator.git?path=/Assets/UnityScreenNavigator"
    }
}

If you want to set the target version, specify it like follow.

• https://github.com/Haruma-K/UnityScreenNavigator.git?path=/Assets/UnityScreenNavigator#1.0.0

Basic Screen Transition

Concept of screens and transitions

Unity Screen Navigator classifies screens into three types: "Page", "Modal" and "Sheet".

"Page" is a screen that transitions in sequence.
For example, when you transition from the Page A to Page B, Page A will be stacked in the history.
And when you return from Page B, Page A will be redisplayed with its states intact.

"Modal" is a screen that is stacked in a window.
When it is displayed, all interactions except for the foreground modal will be blocked.

And "Sheet" is used for tab-like GUI.
History is not managed, and only one active screen is displayed.

These screens can be nested.
And, the area of each screen can be freely specified (not necessarily the entire window).

Create page and transition

To create the page transition, first attach the "Page Container" component to an GameObject under the Canvas.
The pages will be displayed to fit it, so adjust the size.

Next, attach the Page component to the root GameObject of the page view.
Place this GameObject under the Resources folder with an arbitrary name.

And call PageContainer.Push() with the Resources path to display the page.
The following is an example of pushing the page placed in Assets/Resources/ExamplePage.prefab.

PageContainer pageContainer;

// Push the page named "ExamplePage".
var handle = pageContainer.Push("ExamplePage", true);

// Wait for the transition to finish.
yield return handle;
//await handle.Task; // You can also use await.
//handle.OnTerminate += () => { }; // You can also use callback.

Also, use PageContainer.Pop() to discard the active page and display the previous page.

PageContainer pageContainer;

// Pop the active page.
var handle = pageContainer.Pop(true);

// Wait for the transition to finish.
yield return handle;

If you want to skip a certain page when call Pop(), you can disable stacking to history by using the optional argument.

Create modal and transition

To create the modal transition, first attach the "Modal Container" component to an GameObject under the Canvas.
In general, modals are designed to cover the entire window with their backdrop and block clicks.
Therefore, the size of the RectTransform of the GameObject should basically be set to match the window size.

Next, attach the Modal component to the root GameObject of the modal view.
This root GameObject will be adjusted to fit the size of the Modal Container.
So if you want to create the modal with margins, create a child GameObject with a smaller size and create the content inside it.

Place this GameObject under the Resources folder with an arbitrary name.

And call ModalContainer.Push() with the Resources path to display the page.
The following is an example of pushing the modal placed in Assets/Resources/ExampleModal.prefab.

ModalContainer modalContainer;

// Push the modal named "ExampleModal".
var handle = modalContainer.Push("ExampleModal", true);

// Wait for the transition to finish.
yield return handle;
//await handle.Task; // You can also use await.
//handle.OnTerminate += () => { }; // You can also use callback.

Also, use ModalContainer.Pop() to discard the active modal and display the previous modal.

ModalContainer modalContainer;

// Pop the active modal.
var handle = modalContainer.Pop(true);

// Wait for the transition to finish.
yield return handle;

Note that you can change the modal backdrop as you like.

Create sheet and transition

To create the sheet transition, first attach the "Sheet Container" component to an GameObject under the Canvas.
The sheets will be displayed to fit it, so adjust the size.

Next, attach the Sheet component to the root GameObject of the sheet view.
Place this GameObject under the Resources folder with an arbitrary name.

Call SheetContainer.Register() with the Resources path to create the sheet.
After it is created, you can change the active sheet by calling SheetContainer.Show().
At this time, if there is already an active sheet, it will be deactivated.

The following is an example of displaying the sheet placed in Assets/Resources/ExampleSheet.prefab.

SheetContainer sheetContainer;

// Instantiate the sheet named "ExampleSheet"
var registerHandle = sheetContainer.Register("ExampleSheet");
yield return registerHandle;

// Show the sheet named "ExampleSheet"
var showHandle = sheetContainer.Show("ExampleSheet", false);
yield return showHandle;

Note that when multiple sheets with same resource keys are instantiated by the Register() method, the identity of the sheet instance cannot guaranteed by the resource key.
In such case, use the sheet ID instead of the resource key, as shown below.

SheetContainer sheetContainer;

// Instantiate the sheet named "ExampleSheet" and get the sheet id.
var sheetId = 0;
var registerHandle = sheetContainer.Register("ExampleSheet", x =>
{
    sheetId = x.sheetId;
});
yield return registerHandle;

// Show the sheet with sheetId.
var showHandle = sheetContainer.Show(sheetId, false);
yield return showHandle;

Also, to hide the active sheet instead of switching it, use the Hide() method.

SheetContainer sheetContainer;

// Hide the active sheet.
var handle = sheetContainer.Hide(true);

// Wait for the transition to finish.
yield return handle;

How to wait for the transition

Each method for transition returns AsyncProcessHandle as the return value.
Using this object, you can wait for the transition process to finish.

You can use coroutines, asynchronous methods, and callbacks to do this.
To wait in a coroutine, use yield return as shown below.

yield return pageContainer.Push("ExamplePage", true);

To wait in an asynchronous method, use await for AsyncProcessHandle.Task as follows.

await pageContainer.Push("ExamplePage", true).Task;

And use AsyncProcessHandle.OnTerminate if you want to use a callback.

pageContainer.Push("ExamplePage", true).OnTerminate += () => { };

Getting containers with static methods

Each container (PageContainer/ModalContainer/SheetContainer) has static methods to get the instance.

Using the Container.Of() as follows, you can get the container that is attached to the nearest parent from the given Transform or RectTransform.

var pageContainer = PageContainer.Of(transform);
var modalContainer = ModalContainer.Of(transform);
var sheetContainer = SheetContainer.Of(transform);

Also, you can set the Name property in the container's Inspector to get the container by its name.
In this case, use the Container.Find() method as follows.

var pageContainer = PageContainer.Find("S