BABA_YAGA/Assets/UI/Game UI_UX Architecture & Routing Specification.md

Game UI/UX Architecture & Routing Specification (Unity UI Toolkit Edition)

This document outlines the complete structural layout, visual design, animations, and routing logic for the game's user interface, specifically optimized for Unity UI Toolkit. It serves as a direct guide for the associated .uxml, .uss, and .cs controller files.

1. Global Design System & Technical Approach

To maintain consistency and reduce development overhead, the UI is built using UXML templates, styled with USS, and driven by specific C# controllers mapped to your project structure.

Core UI Toolkit Architecture & File Mapping

• Controllers: UI logic is managed by dedicated scripts (UIManager.cs, MainMenuController.cs, LobbyController.cs, ProfileController.cs, SettingsController.cs, HUDController.cs).
• Views (UXML): Layouts are defined in modular files (MainMenu.uxml, Lobby.uxml, Profile.uxml, Settings.uxml, MainGameHUD.uxml).
• Styles (USS): Global styling is handled in Global.uss.

Reusable UI Components & Visual Styles

• Cursorless Navigation (Focus-Based Selection): The game does not display a standard OS cursor (Cursor.visible = false). Instead, the UI interprets mouse movement natively to determine focus. As the hidden cursor moves, the nearest interactive element highlights and scales up. This provides a smart, "snapping" feel to UI selection without needing a visible pointer.
• The "Osu-Style" Slanted Button: A custom VisualElement utilizing USS transform: skew(...) properties to create angled edges. Contains an inner text element counter-skewed to remain horizontal.
• Diagonal Split-Screen Container: Used in Lobby and Profile screens. Instead of a boring vertical line, the split is a sharp diagonal line (like a lightning slash).
  • Implementation: Achieved by applying a negative skew to the Right Pane's parent container, and a positive skew to its inner content to keep text readable.
  • Left Pane (approx. 60% width): Transparent background, showing the Unity 3D Camera rendering the character model and procedural map.
  • Right Pane (approx. 40% width): Frosted glass effect.
• Right-Pane Navigation Bar (Top): Unlike standard top bars, the navigation is contained entirely within the Right Pane.
  • [ < Back ] button is pinned to the Top-Left of the right panel.
  • [ Settings ] button is pinned to the Top-Right of the right panel.
• Modal Overlay Backdrop: A full-screen VisualElement with a semi-transparent black USS background. Used to dim the screen and block inputs behind the Settings panel, Password Prompts, and Confirmation Dialogs.

2. Screen-by-Screen Implementation Details

2.1. Main Menu (MainMenu.uxml & MainMenuController.cs)

Inspired by osu!lazer, this screen is highly dynamic and relies on smooth, physics-based transitions.

• State 1: Initial Load (Idle)
  • Visuals: The background is a heavily blurred, atmospheric map preview. The OS cursor is hidden. Dead center is the Beat Logo.
  • Animation: The Beat Logo dynamically pulses (scales up and down) precisely in sync with the audio source's beat/BPM. There are no other UI elements visible.
• State 2: Active Menu (Transition & Active State)
  • Interaction: The user moves the mouse toward the center, the logo snaps into focus (glows), and they click.
  • Smooth Transition: 1. The Beat Logo shrinks slightly and smoothly translates from the dead center to its designated position in the horizontal menu row.
    2. A horizontal VisualElement container (the ribbon) unfolds from behind the logo using an elastic/spring animation.
    3. The slanted buttons slide out from the logo's position horizontally: [Settings] to the left, and [Create Room], [Join Room], [Profile], [Exit] to the right. They fade in (opacity: 1) with a staggered C# coroutine delay to create a cascading reveal effect.

2.2. Lobby (Lobby.uxml & LobbyController.cs)

• View Setup: Utilizes the Diagonal Split-Screen Container. The view is dynamic; the Right Pane content switches based on whether the user selected "Join Room" or "Create Room" from the Main Menu.
• Left Pane (Transparent): Shows the player model and live procedural background map generation.
• Right Pane (Static UI Area) - Divided into Two Stages:
  • Navigation (Shared): [ < Back ] (Top-Left) and [ Settings ] (Top-Right) are always visible.
  • Stage 1: Join Room (Room Browser)
    • Triggered when entering via the [Join Room] button.
    • Filters & Search: The top of this view includes a TextField for Searching by Room Name, and a DropdownField (or sort icons) for Sorting the list (e.g., by Ping, Name, or Open Slots).
    • Room List: A ScrollView dynamically populated with active rooms via C#. Each list item displays the Room Name, Host Name, Ping, and a clear "Lock" icon if the room requires a password.
    • Interaction Logic:
      • Clicking an unlocked room immediately joins it and transitions the player to the Lounge.
      • Clicking a locked room triggers a Modal Overlay popup asking for the password (contains a TextField and [Submit] / [Cancel] buttons) before joining.
  • Stage 2: Create Room (Configuration Setup)
    • Triggered when entering via the [Create Room] button.
    • Content: Dedicated input fields for setting up a new session. Uses TextField for Room Name and an optional Password. Note: Max players is strictly locked to 2, so no dropdown field is necessary.
    • Toggles: A "Require password to join" checkbox/toggle is present to enable or disable the password field.
    • Action: A large "CREATE ROOM" button sits at the bottom. Clicking this instantiates the room on the server and transitions the player to the Lounge as the Host.

2.3. Profile (Profile.uxml & ProfileController.cs)

• Layout: Reuses the Diagonal Split-Screen structure. The 3D camera shifts to a "Profile Studio" lighting setup for the Left Pane.
• Right Pane Content:
  • Navigation: [ < Back ] (Top-Left) and [ Settings ] (Top-Right).
  • Header: Player Avatar (circular mask), Username, and Rank/Level badge.
  • Statistics: Text labels and progress bars for Win Rate, Matches Played, and current Elo/Rating.
  • Customization: A scrollable grid view at the bottom for equipping character skins or banners.

2.4. Lounge / Pre-Match (Lobby.uxml extensions or new UXML)

Since the game is strictly 2-player, the Lounge is an intimate VS screen.

• Layout: The screen is split directly down the middle via a diagonal slash. Player 1 (Host) is on the left, Player 2 (Guest) is on the right.
• Visuals: Each half has a distinctly tinted background color (e.g., Blue for Host, Red/Orange for Guest) behind the transparent 3D character models.
• Navigation: [ < Back ] (Top-Left) and [ Settings ] (Top-Right) overlay the entire screen.
• Confirmation Logic: Clicking [ < Back ] triggers a Modal Overlay popup: "Are you sure you want to leave the room? [Yes] [No]".
• Ready System:
  • Bottom of each player's panel has a Ready toggle.
  • The Host has a large [ START GAME ] button in the bottom center.
  • Logic: The [ START GAME ] button is greyed out (SetEnabled(false)) until both players have toggled their status to "Ready".

2.5. In-Game HUD (MainGameHUD.uxml & HUDController.cs)

The HUD strictly follows a "Zero Obstruction" philosophy with specific interactive zones.

• Area 1: The 3D World (Background)
  • The root UI element is fully transparent and set to picking-mode: ignore so all mouse inputs register for aiming/gameplay.
• Area 2: Player Stats (Top Left)
  • Visuals: Liquid progress bars for Health and Stamina. Instead of standard flat bars, these utilize a UI Toolkit custom shader or animated sprite mask to look like fluid filling/draining from a container.
• Area 3: Minimap (Top Right)
  • Visuals: The minimap continuously updates based on player position. It features a soft fade effect at its borders (achieved via an alpha gradient mask/texture applied to the VisualElement), seamlessly blending it into the gameplay view without harsh square borders.
• Area 4: Inventory (Bottom Left)
  • Structure: 4 distinct slots: [ Current Holding ] (larger, highlighted), and three quick-slots [ I ], [ II ], [ III ].
  • Logic: Pressing 1, 2, or 3 on the keyboard fires an event in HUDController.cs. The selected item's icon swaps into the [ Current Holding ] slot, and the index updates visually to show what is equipped.
• Area 5: Game Info (Bottom Center)
  • Visuals: Minimalist text displaying current Ping (ms) and FPS.
• Auto-Hide Logic:
  • To maximize visibility, Area 2 (Stats), Area 4 (Inventory), and Area 5 (Game Info) dynamically fade out.
  • In HUDController.cs, track input activity (mouse movement, ability use, damage taken). If Time.time - lastActivityTime > 5f (5 seconds), tween the opacity of these areas to 0 or 0.2. Any new interaction instantly fades them back to 1.

2.6. Settings Menu (Settings.uxml & SettingsController.cs)

• Structure: A floating, centered panel (e.g., occupies roughly 60% width and 70% height) rather than a full-screen view. It sits on top of a full-screen semi-transparent backdrop that blocks interactions with the underlying UI.
• Global Shortcut: The Settings menu can be toggled open or closed from anywhere in the game by pressing Ctrl + O.
• Visuals: The panel has rounded corners and distinct styling to elevate it from the background.
• Layout: Standard settings configuration (Audio sliders, Graphics toggles) using UI Toolkit elements, with a prominent [ X Close ] button in the top right corner of the panel.

3. C# State Machine & Routing Logic (UIManager.cs)

To manage UXML templates, UIManager.cs controls the flow using a stack-based approach.
[Game Launch]
|
[Main Menu (Idle -> Active Logo Bar)]
|
+-------------------+-------------------+-------------------+
| | | |
v v v v
[Lobby: Create] [Lobby: Join] [Profile] [Settings (Overlay)]
| | | |
v v | |
[Lounge (Host)] [Lounge (Guest)] +---(Back)----------+
| |
+--- [All Ready] ---+
|
(Host Clicks Start)
|
v
[IN-GAME HUD]

UI Toolkit State Management Implementation

1. Screen Controller Pattern: Each controller (MainMenuController, LobbyController, etc.) holds a reference to its root VisualElement defined in its corresponding .uxml file.
2. Navigation Stack (Stack<VisualElement>): UIManager.cs pushes screens to this stack. Pressing the Top-Left [ < Back ] button calls a method to pop the current state, hiding it (display: none) and showing the previous one (display: flex).
3. Global Action Listeners (Ctrl + O): UIManager.cs actively listens to the input system for Ctrl + O to instantly trigger SettingsController.ToggleSettings() without affecting the current navigation stack path.
4. Cursorless Input Routing: UIManager.cs constantly monitors Input.mousePosition. It calculates the nearest interactive element within the active screen and applies a .hover USS class to it, overriding default Unity pointer events.