Unity Modal System

What the system is for

Modals are one of those UI parts that everyone reinvents. Quit confirmations, reset to defaults, end-of-session prompts, restart confirmations and generic OK dialogs each end up implemented separately with their own prefabs, their own callbacks and their own way of returning the result. The code that opens a modal often references the modal prefab directly, which makes it impossible to swap visuals without breaking the gameplay layer.

The Modal System in Serenity describes modals as a small set of signals and parameters. Any system can request a modal by dispatching a signal. The modal service handles presentation, the user response and any submitted option. Gameplay code reads back a typed result without knowing which prefab is on screen.

The Unity problem

Unity does not ship with an opinionated modal system. Most projects end up with one of two patterns: scattered UnityEvents on a confirmation prefab, or a custom static manager that everyone calls into. Both make it hard to add a new dialog without duplicating boilerplate, and both leak presentation details into gameplay code.

Modals also need to coordinate with the rest of the UI. They block input on the screen behind them, they should not collide with menus, they need localization for their labels, and the visual style must match the active UI theme. When that coordination is ad hoc, modals are where small UX bugs accumulate.

How Serenity approaches it

Serenity exposes the modal flow as data and signals. Modal parameters describe the buttons, labels and target option that the modal should present. A modal view receives those parameters, renders them through the active UI theme and reports back through use cases such as ModalSelectOption, ModalSubmitOption or ModalCancel. Common modal intents are first-class signals: OnShowModalSignal, OnCloseModalSignal, ShowEndGameSessionModalSignal, ShowExitApplicationModalSignal, ShowRestartGameModalSignal and ShowSetSettingsToDefaultModalSignal.

This keeps the calling code free from prefab references. Asking for a confirmation is dispatching a signal with the right parameters. Reading the result is subscribing to OnModalSubmitOptionSignal. The modal prefab and its presentation can be replaced without touching anything else.

How it fits into Serenity

The Modal System lives in the Serenity.Modal namespace and mirrors the layered structure of the rest of the foundation: Domain interfaces for the modal contract, Application use cases and signals, and Infrastructure for the Unity-specific service, factories and views. An installer registers the service and view factories with the rest of the project.

Modals connect with several other systems by design. UI Themes drive the visual style and sound feedback. Localization handles the labels and button text. The Event Dispatcher carries the show and close signals. The Menu System uses modals for confirmations triggered from settings or pause screens. Game Mode signals can request modals when transitions need user acknowledgement, such as ending a session or returning to the main menu.

Practical workflow

1. Decide which modal you need: a generic confirmation, a built-in intent such as exit application, or a custom modal with your own parameters.
2. Build or reuse a modal parameter object that describes labels, buttons and the option payload.
3. Dispatch the appropriate signal, for example OnShowModalSignal with your parameters or ShowRestartGameModalSignal for the built-in intent.
4. Let the modal service pick the view through its factory and render through the active UI theme.
5. Subscribe to OnModalSubmitOptionSignal or OnCloseModalSignal to react to the player choice.
6. Restyle the modal by editing the view prefab or the theme, with no changes required in the calling code.

What you get

• Configurable modal parameters with labels, buttons and option payloads
• Use cases for select option, submit option, change option value and cancel
• Built-in intent signals such as ShowExitApplicationModalSignal and ShowRestartGameModalSignal
• Outbound signals OnShowModalSignal, OnCloseModalSignal and OnModalSubmitOptionSignal
• View, presenter and service factories that keep the visual layer replaceable
• Shared UI theme integration so modals match the rest of the UI
• Localization integration for labels and button text
• Installer that registers the service once for the whole project

When to use this

• Projects that need consistent confirmation, alert and prompt dialogs across screens.
• Games where end-of-session, restart, quit and reset-to-default flows must look and behave the same way.
• Teams that want to drive UX dialogs from gameplay code without referencing UI prefabs.
• Codebases moving away from per-screen confirmation prefabs toward a shared modal pipeline.

Related systems

• Unity Menu System Declarative menus, shared UI themes and predictable navigation, configured as assets instead of hand-wired GameObjects.
• Unity UI Themes ScriptableObject-based UI themes that share visuals and sound feedback across menus, modals and screens.
• Unity Event Dispatcher Typed signals dispatched through a service, with auto-registration support and no static singletons.
• Unity Localization System Runtime language switching, separate game and voice language tracks, and localized menus and modals out of the box.