Nebula-OS/README.md

# NebulaOS

NebulaOS is an open source Linux-based operating system experience built around two modes:

1. **Bigscreen Mode**: a controller-first console-style interface for games, apps, media, settings, and system navigation.
2. **Desktop Mode**: a clean KDE-based desktop experience for productivity, development, file management, and advanced system control.

NebulaOS is not just a launcher, Steam skin, or Big Picture replacement.
It is a full OS experience designed to make Linux feel native on gaming PCs, handhelds, TV setups, and eventually dedicated console-like hardware.

The goal is to combine the best parts of console UX, desktop Linux, and modern operating system design into one flexible system.

---

## Vision

NebulaOS is designed around a simple idea:

> A gaming OS should feel like a console when you are gaming, and like a real desktop when you need one.

Most gaming-focused Linux setups are either:

* Too desktop-oriented for controller use
* Too launcher-dependent
* Too tied to Steam
* Too limited when the user needs full desktop control

NebulaOS aims to solve that by providing both:

* A polished controller-first Bigscreen interface
* A proper Linux desktop mode

The long-term goal is to create an OS that can work as:

* A Steam Deck-style handheld interface
* A living room gaming console UI
* A gaming PC frontend
* A full Linux desktop
* A foundation for future Nebula hardware

---

## Modes

### Bigscreen Mode

Bigscreen Mode is the main console-style experience.

It is designed for:

* Controllers
* TVs
* Handhelds
* Game launching
* App launching
* System settings
* Power controls
* Profiles
* Media-focused workflows

Bigscreen Mode is becoming a native Qt shell; the repo still contains a Tauri/HTML v0 prototype for early UI work. Sign-in and session choice happen at the OS login screen, not inside Bigscreen.

Current v0 features include:

* Lock screen with PIN keypad in the Tauri prototype only (OS login replaces this in the target design)
* Home dashboard tile grid
* Library screen
* Settings screen
* Power overlay
* Unified input actions from keyboard and gamepad
* Xbox-inspired horizontal dashboard layout
* Dynamic nebula background visuals
* Controller focus states and smooth transitions

Read more in:

```text
bigscreen/README.md
```

---

### Desktop Mode

Desktop Mode is the full Linux desktop experience.

It is intended for:

* File browsing
* Productivity
* Web browsing
* Development
* System configuration
* Troubleshooting
* Advanced settings
* Desktop gaming workflows

The recommended Desktop Mode foundation is KDE Plasma because it is flexible, themeable, controller-adaptable, and already well-suited to Linux gaming environments.

Desktop Mode should feel clean, modern, and polished, with a design direction inspired by the clarity and smoothness of macOS while keeping the flexibility of Linux.

Read more in:

```text
Desktop/README-Desktop.md
```

---

## What NebulaOS Is

NebulaOS is:

* A Linux-based gaming operating system experience
* A controller-first shell for Bigscreen use
* A KDE-based desktop experience for normal computer use
* A unified game and app launcher
* A modular platform for Nebula apps
* An open alternative to proprietary gaming frontends
* A foundation for future console-like hardware

---

## What NebulaOS Is Not

NebulaOS is not:

* A Steam skin
* A Steam Big Picture clone
* A launcher-only project
* A proprietary console OS
* A replacement for Linux itself
* A locked-down gaming environment

NebulaOS should work with Steam, GOG, Epic Games, local apps, native Linux games, Proton, Wine, and other tools without depending on one company’s frontend.

---

## Core Principles

1. **Controller-first, not controller-compatible**
   Bigscreen Mode should be designed from the ground up for controller navigation.

2. **Desktop when needed**
   Users should always be able to access a proper desktop environment.

3. **Open and modular**
   NebulaOS should be built from replaceable, understandable components.

4. **Independent from proprietary launchers**
   Store integrations should exist, but NebulaOS should have its own interface.

5. **Console feel, PC freedom**
   NebulaOS should feel simple and polished without removing user control.

6. **Built for iteration**
   v0 should be simple, but the architecture should leave room for long-term growth.

---

## High-Level Architecture

NebulaOS is split into several layers:

```text
NebulaOS
├── Bigscreen Mode
│   ├── Nebula Home
│   ├── Nebula Library
│   ├── Controller Settings
│   ├── Power Menu
│   └── Profile status (signed-in user; no OS login)
│
├── Desktop Mode
│   ├── KDE Plasma
│   ├── Nebula desktop theme
│   ├── Controller-friendly SDDM login
│   ├── Session entries (Bigscreen / Desktop)
│   ├── Desktop apps
│   └── Advanced system tools
│
├── Nebula Core
│   ├── Input
│   ├── Navigation
│   ├── Theme
│   ├── Glyphs
│   └── Shared UI logic
│
└── System Integration Layer
    ├── Game discovery
    ├── App launching
    ├── Store integrations
    ├── Proton / Wine handling
    ├── Network settings
    ├── Audio settings
    ├── Display settings
    └── Power controls
```

---

## Technology Stack

### Bigscreen Mode

* Tauri
* HTML
* CSS
* JavaScript
* Rust backend through Tauri
* Web Gamepad API
* Nebula Core

### Desktop Mode

* Linux
* KDE Plasma
* SDDM
* Custom Nebula theme
* Custom session configuration
* Optional Nebula desktop tools

### Game and App Layer

Planned integrations include:

* Native Linux apps
* Local executables
* Steam
* SteamCMD
* Proton
* Wine
* GOG
* Epic Games
* Legendary
* Heroic backend concepts
* Local metadata databases

---

## Current Repository Status

This repository currently contains the early NebulaOS v0 prototype.

Current features include:

* Tauri frontend shell
* Controller and keyboard input mapping
* Tauri prototype lock screen (superseded by planned OS login)
* Home dashboard
* Library stub
* Settings stub
* Power overlay
* Nebula Core adapter structure
* Xbox-inspired dashboard refresh
* Windows-first development setup
* Linux build pathway

The project is building **Bigscreen Mode** (Qt shell) and **Desktop Mode** (KDE Plasma customization) in parallel. A controller-friendly **OS login** (SDDM + sessions) is part of Desktop/system work so Bigscreen does not handle account creation or sign-in.

---

## Install

```bash
npm install
```

---

## Run in Development

```bash
npm run dev
```

---

## Build

```bash
npm run build
```

---

## Linux Prerequisites

For Ubuntu, Debian, and related distributions, install the system dependencies required by Tauri and WebKit:

```bash
sudo apt update
sudo apt install -y \
  libwebkit2gtk-4.1-dev \
  libappindicator3-dev \
  librsvg2-dev \
  patchelf \
  build-essential \
  curl \
  wget \
  file \
  libssl-dev \
  libgtk-3-dev
```

You will also need:

* Node.js LTS
* Rust
* npm

Then run:

```bash
npm install
npm run dev
```

---

## Controller Testing

For development, connect an Xbox-compatible controller before launching the app.

### Controller Mapping

```text
D-pad / left stick: Navigate
A: Accept
B: Back
Start: Menu
```

### Keyboard Mirror

```text
Arrow keys: Navigate
Enter: Accept
Escape / Backspace: Back
```

---

## Nebula Core Integration

NebulaOS uses `@nebulaproject/core` through runtime adapters.

Current adapter files:

```text
src/core/input.js
src/core/nav.js
src/core/state.js
```

If Nebula Core exports are available, NebulaOS uses them for input, navigation, glyphs, and theme handling.

If they are unavailable, local fallback adapters keep the shell functional during development.

---

## Local Nebula Core Development

For active local development, clone Nebula Core next to this repository.

```bash
# In Nebula-Core repo
npm link

# In NebulaOS repo
npm link @nebulaproject/core
```

Alternative deterministic setup using `file:` dependency:

```json
{
  "dependencies": {
    "@nebulaproject/core": "file:../Nebula-Core/packages/core"
  }
}
```

Then run:

```bash
npm install
```

---

## Development Strategy

NebulaOS is currently developed across two environments.

### Windows

Used for:

* UI development
* Controller navigation
* Bigscreen UI prototyping (legacy Tauri lock screen is not target architecture)
* Library UI
* Settings UI
* Frontend architecture

### Linux VM

Used for:

* Linux builds
* Session testing
* KDE integration
* Fullscreen shell testing
* Proton and Wine experiments
* System service experiments

The current workflow is:

```text
Design and build the UI on Windows.
Test OS-level behavior in Linux.
```

---

## Roadmap

### Phase 1: Desktop Mode and OS login (in progress)

Goal: Build the KDE-based desktop layer and a controller-friendly login experience.

Deliverables:

* KDE Plasma Nebula theme and look-and-feel
* Controller-friendly SDDM login (account picker, sign-in)
* Nebula Bigscreen and Nebula Desktop session entries
* First-run / account setup at the OS layer (not inside Bigscreen)
* Desktop-to-Bigscreen and Bigscreen-to-Desktop switching
* Basic Nebula desktop tools

---

### Phase 2: Bigscreen Qt shell

Goal: Build a polished controller-first game shell that starts after OS login.

Deliverables:

* Native Qt/QML Bigscreen app
* Home dashboard
* Library screen
* Settings screen
* Power menu (including log out to OS login)
* Controller navigation
* Fullscreen mode
* Basic app launching

Bigscreen does **not** deliver in-shell login, PIN lock, or account creation.

---

### Phase 3: Session polish

Goal: Make NebulaOS feel like a real OS from boot to shell.

Deliverables:

* Reliable gamepad support on SDDM and in Bigscreen
* Bigscreen launches fullscreen into the signed-in session
* Exit to desktop or return to login
* Consistent Nebula visual identity across login, Bigscreen, and Desktop

---

### Phase 4: Nebula Library Foundation

Goal: Begin true game and app management.

Deliverables:

* Local app database
* Installed games database
* Manual game adding
* Local executable launching
* Metadata structure
* Cover art and banner support
* Store backend abstraction

---

### Phase 5: Store and Compatibility Integrations

Goal: Turn Nebula Library into a real open game manager.

Potential integrations:

* SteamCMD
* Proton
* Wine
* Legendary for Epic Games
* GOG tooling
* Heroic backend concepts
* Per-game compatibility settings

---

## Success Criteria for v0

NebulaOS v0 is successful when:

* Bigscreen Mode can be launched fullscreen
* The entire shell is controller navigable
* OS login works with controller and keyboard (SDDM; not an in-Bigscreen lock screen)
* The Home dashboard works
* The Library can display and launch local entries
* Settings has a usable controller-first structure
* Power controls exist
* Desktop Mode remains accessible
* Bigscreen and Desktop feel like two parts of the same OS

---

## Long-Term Goal

NebulaOS should become a gaming OS that feels native, polished, and open.

A user should be able to:

* Turn on a machine
* Pick up a controller
* Navigate the whole system
* Launch a game
* Switch to Desktop Mode when needed
* Manage apps, games, settings, and profiles
* Use the system without needing Steam Big Picture or a traditional desktop launcher

NebulaOS is the bridge between a console experience and a real computer.