Unity Screen Navigator

Unity Screen Navigator is a library for Unity's uGUI designed to manage screen transitions, transition animations, screen transition history (stacks), and screen lifecycle management.

Key Features

• Flexible UI Construction: Easily build pages, modals, tabs, and their transitions.
• Lifecycle & Memory Management: Manages the entire lifecycle of a screen from loading to destruction.
• Decoupled Animation Workflow: Allows implementing complex transition animations separately from the Animator.
• Single-Purpose Design: A well-separated, lightweight library that does not include unnecessary features like GUI libraries or state machines.
• Standard Features Included: Built-in support for history stacking and preventing interactions during transitions.

Unity Screen Navigator classifies screens into three distinct types based on how they manage history and interaction:

• Page: Sequential screens that use a history stack. When transitioning from Page A to Page B, Page A is stored in history. Returning from Page B restores Page A with its state intact.
• Modal: Window-based screens stacked on top of others. When a Modal is active, all interactions with the background are blocked.
• Sheet: Used for tab-like GUIs. History is not managed; only one active sheet is displayed at a time.

Screens can be nested, and their display area can be customized to any size (not restricted to the full window).

The library does not enforce a specific pattern for data passing (e.g., it does not provide a built-in data injection system). This allows you to use your preferred method, such as:

• Passing data manually once loading is completed.
• Using a Dependency Injection (DI) container to set data on the screen instance.

When animating transitions involving a partner screen (e.g., an animation where the incoming screen covers the outgoing one), use the Rendering Order property to control which screen is drawn on top.

• Screens are drawn in order of decreasing Rendering Order values.
• Note: Modals do not have a Rendering Order property because the newest modal is always displayed in front.

Unity Screen Navigator classifies screens into three distinct types, each with different lifecycle and interaction behaviors:

1. Pages: Screens that transition sequentially. When moving from Page A to Page B, Page A is stacked in the history. Returning from Page B restores Page A with its state preserved.
2. Modals: Screens that stack on top of existing content. While a modal is active, interactions with any other modal behind it are blocked.
3. Sheets: Used for GUI elements like tabs. They do not maintain a history; only one active sheet is displayed at a time.

Screens can be nested, and their display area can be customized (they do not have to be full-screen).

Popped pages and modals are destroyed immediately upon being popped and cannot be reused directly. If you need to address specific reuse requirements, consider these strategies:

1. To reduce loading time: Use Preloading to keep resources ready.
2. To preserve state: Decouple state from the view so it can be reconstructed. For UI patterns like 'Tabs' where state retention is expected, use Sheets instead of standard page transitions, as state is preserved in Sheet transitions.

If you implement a custom reuse mechanism, you are responsible for managing the lifecycle, including calling the Cleanup method to destroy instances and free memory.

You can trigger specific animations only when transitioning to or from a specific screen (the "partner screen").

1. In the Animation Container settings, enter the name of the target screen in the partner screen property.
2. Identifier Logic: By default, the Prefab name is used as the screen name. To use a custom name, uncheck Use Prefab Name As Identifier and fill in the Identifier property.
3. Regex Support: The Partner Page Identifier Regex property supports regular expressions for matching partner screens.
4. Evaluation Order: If multiple animations are specified, they are evaluated in order from top to bottom.

A "Partner Screen" is the screen that is exiting when a new screen enters (e.g., if Screen A enters and Screen B exits, B is the partner of A). You can trigger specific animations only when certain partner screens are involved.

Configuration Steps

1. Identify the Screen: By default, the prefab name is used as the screen name. To use a custom name, uncheck Use Prefab Name As Identifier and set the Identifier property.
2. Set the Partner Match: In the animation settings, enter the name of the target partner screen in the property field. You can use regular expressions in the Partner Page Identifier Regex property.
3. Priority: If multiple animations are configured, they are evaluated in order from top to bottom.

To create animations that react to the state of the screen being transitioned to/from (e.g., scaling an image of the previous modal while transitioning to a new one), implement TransitionAnimationObject or TransitionAnimationBehaviour and reference the PartnerRectTransform property.

• PartnerRectTransform provides access to the partner screen's transform.
• If no partner screen is involved in the transition, PartnerRectTransform will be null.

When animations involve one screen overlapping another (e.g., a new page covering an old one), use the Rendering Order property to control which is drawn first.

• Screens are drawn in ascending order of this value (smaller values are drawn first).
• Note: Modal components do not have a Rendering Order property because new modals are always displayed on top of existing ones.