View Navigation and History

What the system is for

Every game with more than one screen eventually builds the same thing: a stack that remembers where the player came from so pressing back takes them to the right place. Whether that means returning from settings to the pause menu, or closing a modal back to the map, the logic is identical. Without a shared service it gets re-implemented per scene, per menu, and per developer.

The View Browser in Serenity makes that stack a first-class aggregate. It exposes a typed service for pushing views, navigating back, inspecting history and reading the current view — all through a clean interface that works above any UI provider or router implementation.

The Unity problem

Unity projects that grow organically accumulate navigation logic in MonoBehaviours, static managers, and scene-load callbacks. A back button in the pause menu is handled differently from a back button in settings, which is handled differently again in character customization. When the team adds a new screen or changes the flow, every call site needs updating and history state breaks in subtle ways.

The real cost is not writing the stack — it is owning it. Clearing history on game-mode change, guarding GoBack when the stack is empty, knowing which view is current without polling the scene — each of those is a bug waiting to happen when the logic is scattered across the project.

How Serenity approaches it

Serenity provides IViewBrowserService with five operations: Push accepts a ViewBrowserPushInput carrying any IViewBase and appends it to the history stack, GoBack pops the top entry and returns the view navigated back to, ClearHistory resets the stack entirely, GetHistory returns the full ordered list of views, and GetCurrentView reads the top of the stack without mutating it. IViewBrowserServiceFactory allows the Unity implementation to be created and replaced through the standard Serenity factory pattern.

The Unity infrastructure layer provides UnityViewBrowserService, a MonoBehaviour that implements IViewBrowserService and manages the internal list. The use-case classes ViewBrowserPush, ViewBrowserGoBack and ViewBrowserClearHistory wrap each operation cleanly, and ViewBrowserUseCases aggregates them so the service can be injected as a single dependency wherever navigation is needed.

How it fits into Serenity

View Browser lives in the Serenity.ViewBrowser namespace and follows the foundation's layered structure. The Application layer holds IViewBrowserService, IViewBrowserServiceFactory, the use-case classes, and ViewBrowserPushInput as a DTO. The Infrastructure layer provides the Unity-specific UnityViewBrowserService MonoBehaviour and its factory. The Installation layer registers the service through the standard Serenity initialization pipeline without touching consumers.

View Browser sits above IViewRouter from the Global aggregate, so it cooperates cleanly with the Menu System for back navigation in menus, with the Modal System to track views opened as modals, with UI Themes to restore the correct visual state on back, and with Game Mode so navigation history can be cleared when the active mode changes.

Practical workflow

1. Add the View Browser installer to your project's initialization pipeline to register IViewBrowserService.
2. Inject IViewBrowserService or ViewBrowserUseCases into any menu, controller, or presenter that needs to navigate.
3. Call Push with a ViewBrowserPushInput wrapping the target IViewBase whenever the player opens a new screen.
4. Call GoBack from back buttons, escape handlers or any gesture that returns to the previous view.
5. Call GetCurrentView to read which view is active without searching the scene hierarchy.
6. Call ClearHistory on game-mode transitions or whenever the navigation context resets completely.

What you get

• IViewBrowserService with Push, GoBack, ClearHistory, GetHistory and GetCurrentView
• ViewBrowserPushInput DTO carrying any IViewBase onto the navigation stack
• Use-case classes ViewBrowserPush, ViewBrowserGoBack and ViewBrowserClearHistory for clean separation
• ViewBrowserUseCases aggregate for single-dependency injection
• IViewBrowserServiceFactory keeping the Unity implementation replaceable
• UnityViewBrowserService MonoBehaviour as the ready-to-use Unity infrastructure
• Safe GoBack that throws a descriptive exception when the stack is empty rather than silently failing
• Integration with Menu System, Modal System, UI Themes and Game Mode through shared Serenity contracts

When to use this

• Projects where multiple screens need a consistent back-navigation flow without duplicating stack logic per scene.
• Games that have menus, modals, or overlay views and need to restore the previous context reliably.
• Codebases that want to clear navigation history on game-mode transitions without coupling that logic to each individual menu.
• Teams that want back-button and escape-key support to work the same way everywhere in the project.

Related systems

• Menu System Declarative menus, shared UI themes and predictable navigation, configured as assets instead of hand-wired GameObjects.
• Modal System Reusable confirmation, alert and prompt modals driven by typed signals and shared parameters.
• UI Themes ScriptableObject-based UI themes that share visuals and sound feedback across menus, modals and screens.
• Game Mode System Typed game state transitions with signals, pause strategies and a readiness gate that other systems can subscribe to.