# NebulaOS Bigscreen Mode Bigscreen Mode is the controller-first console interface for NebulaOS. It is designed for gaming PCs, handhelds, TVs, and couch-based setups where the primary input is a controller rather than a mouse and keyboard. Bigscreen Mode should feel like the main dashboard of a console, but with the freedom of a Linux PC underneath. --- ## Purpose Bigscreen Mode exists to make NebulaOS feel native on gaming hardware. It provides: * A controller-first home screen * A game and app library * System settings * Power controls * Profile status and quick user actions (not OS login) * Store and launcher integrations * A fullscreen interface for TV and handheld use Account selection, sign-in, and first-time setup live on the **OS login screen** (see [Plan](#plan)), not inside Bigscreen. The goal is not to copy Steam Big Picture or Xbox exactly. The goal is to create an open, polished, flexible OS shell that feels good to use with a controller. --- ## Current Features The current v0 **Tauri prototype** includes: * Lock screen with PIN keypad (prototype only; not part of the target Qt shell) * Controller and keyboard input support * Home dashboard * Library stub * Settings stub * Power overlay * Controller focus management * Keyboard mirror controls for development * Xbox-inspired horizontal tile layout * Dynamic nebula background stack * Smooth focus transitions * Shared top bar with profile and time display --- ## Input Model Bigscreen Mode uses unified input actions instead of raw button handling. Core actions: ```text up down left right accept back menu ``` These actions can come from: * Controller D-pad * Controller left stick * Controller face buttons * Keyboard arrow keys * Enter * Escape * Backspace This keeps the UI consistent across controllers, keyboards, and future input devices. --- ## Controller Mapping ```text D-pad / left stick: Navigate A: Accept B: Back Start: Menu ``` Future mappings may include: ```text LB / RB: Switch tabs or rails LT / RT: Page navigation Guide button: Nebula overlay Y: Search X: Context action ``` --- ## Design Goals Bigscreen Mode should be: * Fast * Clear * Controller-first * Readable from a distance * Comfortable on TVs * Comfortable on handheld screens * Smooth and polished * Visually distinct from desktop Linux * Easy to navigate without a mouse --- ## UI Structure Bigscreen Mode is planned around the following major areas: ```text Bigscreen Mode (after OS login) ├── Home ├── Library ├── Store ├── Apps ├── Settings ├── Downloads ├── Notifications ├── Power Menu └── Profile Menu ``` OS-level (Desktop Mode / KDE work, not inside Bigscreen): ```text NebulaOS login (SDDM) ├── Controller-friendly account picker ├── Sign in ├── Session choice (Bigscreen vs Desktop) └── First-run / account setup when needed ``` --- ## Home The Home screen is the main landing area. It should include: * Recent games * Installed games * Featured apps * Continue playing section * Quick settings * Profile status * Time and network status * Download status * Power menu access The current prototype uses a horizontal app tile rail with Library, Settings, and Power tiles. --- ## Library The Library is the game and app management area. Initial v0 scope: * Display mock entries * Display locally added games * Launch local executables * Store metadata locally * Support controller navigation * Separate games from apps Future scope: * Steam integration * GOG integration * Epic Games integration * Proton and Wine configuration * Per-game settings * Save sync support * Mod manager integration * Metadata and artwork scraping --- ## Settings Settings should expose system controls in a controller-friendly way. Planned categories: * Network * Bluetooth * Audio * Display * Controller * Storage * Signed-in user (read-only; account changes via OS login / Desktop) * Appearance * Updates * System * Desktop Mode The settings UI should avoid feeling like a desktop control panel. It should feel like a native console settings app. --- ## Login and sessions Bigscreen Mode does **not** own account creation, authentication, or session selection. Those belong to a **controller-friendly NebulaOS login experience** built as part of [Desktop Mode](../Desktop/README-Desktop.md): KDE Plasma customization, SDDM theming, and session entries for Nebula Bigscreen and Nebula Desktop. Users pick an account and session at boot; Bigscreen starts already signed in. The Tauri v0 **lock screen with PIN keypad** (`1234` in the prototype) was only for early UI testing. It will not ship in the Qt shell. If the OS needs a lock or suspend screen later, that should stay at the session/login layer or use the desktop stack—not a second login flow inside Bigscreen. Bigscreen may still show **who is signed in** (avatar, name) and offer **Log out** / **Switch user** via the power menu, which returns to the OS login screen. --- ## Plan NebulaOS is no longer “Bigscreen first, desktop later.” **Desktop Mode is being built in parallel** on KDE Plasma, and that work unlocks a proper OS login so Bigscreen can stay a game shell. ### Phase 1 — Desktop Mode foundation (in progress) Handled in `Desktop/`, not in Bigscreen: * KDE Plasma theme and look-and-feel * Nebula visual identity on panels, widgets, and dialogs * Repo-based apply/reload workflow for Plasma assets ### Phase 2 — OS login and sessions Also primarily Desktop / system integration: * Controller-friendly **SDDM** login theme * Account picker and sign-in usable with a gamepad * Session entries: **Nebula Bigscreen** and **Nebula Desktop** * First-run or account setup on the login/desktop side when needed * Log out / switch user returns here Bigscreen does not implement PIN keypads, local account linking, or onboarding wizards for new users. ### Phase 3 — Bigscreen Qt shell * Native Qt/QML shell (see [Technology](#technology)) * Home, Library, Settings, Power menu * Controller-first navigation and focus model * Launch games and apps into the signed-in user session * Switch to Desktop Mode; restart shell; no embedded login ### Phase 4 — Library and integrations * Local library database and scanners * Store and launcher integrations * Proton/Wine and per-game settings (later) ### Prototype note The Tauri/HTML v0 under `Bigscreen/` remains useful for layout and input experiments until the Qt shell replaces it. Treat its lock screen and onboarding flows as **throwaway**, not roadmap deliverables. --- ## Power Menu The power overlay should support: * Sleep * Restart * Shut down * Log out * Switch to Desktop Mode * Return to login * Restart Bigscreen shell Current v0 scope includes a power overlay that traps focus and closes with Back. --- ## Technology Bigscreen Mode is a **native Qt application**, not a web shell. Target stack: * Qt 6 * Qt Quick (QML) for the controller-first UI * C++ for system integration, library scanning, and Nebula Core adapters * Qt input APIs for keyboard and gamepad navigation * CMake for builds The repo still contains an early **Tauri/HTML v0 prototype** under `Bigscreen/` (HTML, CSS, JavaScript, and a Rust backend). That prototype validated layout, focus flow, and input actions. New Bigscreen work targets the Qt shell; the Tauri stack is legacy and will be removed as the Qt app reaches parity. --- ## Run ### Qt shell From `Bigscreen/` (Qt 6.5+ with Quick modules installed): ```bash cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug cmake --build build --config Debug ``` On Windows, the build runs `windeployqt` automatically so Qt DLLs sit next to the executable. If you see missing `Qt6*.dll` errors, rebuild once from `Bigscreen/`: ```powershell cmake --build build --config Debug ``` From the repo root instead: ```bash cmake -S Bigscreen -B Bigscreen/build -DCMAKE_BUILD_TYPE=Debug cmake --build Bigscreen/build --config Debug ``` Run the binary: ```bash # Linux (from Bigscreen/) ./build/nebula-bigscreen # Windows (from Bigscreen/) build\Debug\nebula-bigscreen.exe ``` To run without redeploying, you can instead put Qt on `PATH` for that session (adjust the kit path if needed): ```powershell $env:PATH = "C:\Qt\6.10.2\msvc2022_64\bin;" + $env:PATH .\build\Debug\nebula-bigscreen.exe ``` **Controls (v0):** arrow keys to navigate, Enter to accept, Escape/Backspace for back, Menu key (or Start when mapped later) for the power overlay. Gamepad mapping is planned next. ### Legacy Tauri prototype To run the existing v0 web prototype while migration is in progress, from `Bigscreen/`: ```bash npm install npm run dev ``` --- ## Build ### Qt shell Same CMake workflow as above with `-DCMAKE_BUILD_TYPE=Release`. ### Legacy Tauri prototype ```bash npm run build ``` Run from `Bigscreen/`. --- ## Development Notes Bigscreen Mode is moving to Qt for a native fullscreen shell, lower overhead, and tighter OS integration (sessions, launching, power controls). Login, SDDM, and Plasma session work happen under **Desktop Mode**; Bigscreen assumes the user already chose the Bigscreen session at the OS login screen. The Tauri prototype was developed primarily on Windows for fast UI iteration. Qt development should be validated on both Windows and Linux early. Linux testing is still required for: * Fullscreen behavior * Session integration * Controller detection * System commands * App launching * Proton and Wine workflows * Power controls --- ## Success Criteria Bigscreen Mode is successful when: * The entire interface works with a controller * Users arrive signed in via the OS login screen (Bigscreen does not gate access) * Users can navigate Home * Users can open Library * Users can open Settings * Users can launch games or apps * Users can access power controls * Users can switch to Desktop Mode * The UI feels like a native OS shell, not a web app