Nebula-OS/README.md

Nebula OS v0 – Windows-first Development Plan

Vision

Nebula OS is a controller-first, open source operating system experience built on Linux.

It has two equally important jobs:

1. A custom controller-first way to navigate the OS (like a console shell)
2. An open source library and launcher layer for games and apps

Nebula OS is not a skin that launches Steam. It is an independent UI layer that:

• Acts as the primary controller-first shell for the OS
• Provides a unified Home experience for games, apps, and media
• Ships with core Nebula apps such as Nebula Browser
• Exposes system settings through controller-friendly panels
• Manages game libraries directly (Steam, GOG, Epic, and others)

Nebula OS v0 focuses on building the foundation for this console-grade OS shell.

---

Core Principles

1. Controller-first, not controller-compatible
2. Replace proprietary frontends with an open interface
3. Separate system layer from UI layer
4. Build modular infrastructure for long-term independence
5. Develop iteratively, but architect for autonomy

---

What Nebula OS v0 Actually Is

Nebula OS v0 consists of:

• Base OS: Ubuntu LTS (or Ubuntu-based)

• Desktop Environment: KDE Plasma (recommended)

• Display Manager: SDDM

• Two login sessions:

  • Nebula Desktop
  • Nebula Game UI

• Nebula Shell (Tauri + HTML/CSS/JS)

• Nebula Library (core application responsible for:

  • Game discovery
  • Installation
  • Updates
  • Launching
  • Compatibility management)

Unlike SteamOS, Nebula OS does not rely on launching Steam Big Picture. Nebula Library is the primary game management layer.

---

High-Level Architecture

Desktop Mode

A standard KDE session for:

• Productivity workflows
• File browsing and system tools
• Development and troubleshooting
• Advanced configuration

Desktop Mode remains a normal Linux desktop.

Game UI Mode

A dedicated login session that launches Nebula Shell fullscreen.

Game UI Mode contains:

• Lock screen with controller PIN entry
• Nebula Home dashboard
• Nebula Browser
• Nebula Library
• Controller-friendly Settings
• Power and session controls

Game UI Mode is the console experience for the entire OS.

System Integration Layer (behind the UI)

Nebula OS needs a clean boundary between UI and system operations.

Recommended approach:

• A small privileged backend service (later) that exposes safe operations:

  • Wi-Fi and networking
  • Audio and output device selection
  • Display resolution and scaling
  • Bluetooth pairing
  • Storage overview
  • Power controls

• The UI talks to that layer through a stable API

v0 scope can start with non-privileged read-only data and a few safe commands.

---

Technology Stack

UI Layer

• Tauri
• HTML
• CSS
• JavaScript

Why Tauri:

• Lightweight
• Native system integration via Rust backend
• Cross-platform development
• Efficient resource usage

Controller Input

• Web Gamepad API
• Custom focus/navigation system

Controller mappings:

• D-pad / left stick: navigation
• A: activate
• B: back
• Start: menu
• Shoulder buttons: future navigation layers

Keyboard mirrors controller during development.

---

Nebula Shell – The OS UI Layer

Nebula Shell is the controller-first OS shell.

It is the primary interface in Game UI Mode and should feel like a console dashboard, not a desktop.

Nebula Shell responsibilities:

• Home dashboard (games, apps, recent activity)
• App launcher for Nebula apps (Nebula Browser, Nebula Library, Settings)
• System navigation (network, audio, display, storage, accounts)
• Power menu and session switching (Game UI ↔ Desktop)
• Notifications and downloads (later)
• Controller-first focus navigation everywhere

Nebula Shell is built with Tauri + HTML/CSS/JS.

---

Nebula Library – The Game and App Management Layer

Nebula Library is the content manager inside Nebula OS.

It is not a bridge to proprietary UIs. It should eventually handle:

• Steam installs via SteamCMD and/or open APIs
• GOG installs via open or community tooling
• Epic installs via open tooling (for example Legendary)
• Proton/Wine configuration and per-title settings
• Game launch parameters and runtime selection
• Updates, integrity checks, and metadata

Initial v0 scope:

• Library UI skeleton and data model
• Local entries (manual add)
• Launch local executables
• Foundation for compatibility and store backends

Long-term direction:

Nebula Library becomes a unified open source platform for managing games and apps.

---

Development Strategy

Nebula OS is developed in two environments:

Windows (Primary UI Development)

Used for:

• Building Nebula Shell UI
• Implementing controller navigation
• Designing lock screen
• Designing Library UI
• Building system state architecture

UI and logic are platform-agnostic.

Linux VM (Integration & Replacement Layer)

Used for:

• Building Linux binaries
• Session integration
• SteamCMD integration testing
• Proton/Wine configuration
• System-level testing

Rule:

Develop UI on Windows. Build and test Linux features inside the VM.

---

Phase Roadmap

Phase 1 – Nebula Shell (Controller Console Layer)

Objective: Build a polished, console-grade Game UI independent of store integration.

Deliverables:

• Lock screen with PIN keypad
• Home dashboard
• Library screen (mock data)
• Settings screen
• Power menu
• Controller navigation grid system
• Fullscreen window behavior

No external integrations yet.

---

Phase 2 – Session Integration

Objective: Make Nebula Shell a selectable login session.

Milestones:

• Nebula Game UI appears at login
• Launches fullscreen
• Exiting returns to login
• Controller works reliably

---

Phase 3 – Nebula Library Foundations

Objective: Begin true replacement behavior.

Milestones:

• Launch local Linux games
• Integrate Proton/Wine execution layer
• Add SteamCMD support for installing Steam titles
• Track installed game metadata
• Unified library view

This is where Nebula begins diverging from SteamOS.

---

Phase 4 – Store Integrations

Objective: Add real backend integration without proprietary UI.

Potential directions:

• SteamCMD for Steam installs
• Legendary (Epic CLI) integration
• Heroic backend reuse (without UI dependency)
• OpenGOG community tools

Nebula Library becomes the single UI.

---

Security Strategy

Game UI lock screen:

• Local PIN authentication
• Optional profile system (future)

Linux account authentication remains system-level.

---

What Nebula OS Is Not

• Not a Steam skin
• Not Big Picture mode
• Not a launcher aggregator
• Not dependent on proprietary UIs

It is an open system layer that manages games directly.

---

Immediate Action Plan

1. Build Nebula Shell UI on Windows
2. Implement controller navigation framework
3. Build lock screen system
4. Build Library UI skeleton
5. Set up Linux VM
6. Create Nebula Game UI login session
7. Begin local executable launching support
8. Research SteamCMD integration

---

Success Criteria for v0

Nebula OS v0 is successful when:

• You can log into Nebula Game UI
• The entire UI is controller navigable
• Lock screen works
• You can launch locally managed games
• You can return to Desktop Mode

From there, Nebula Library evolves into a true open source game management platform.