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 built as a fullscreen Nebula shell using Tauri, HTML, CSS, JavaScript, and a controller-first navigation system.

Current v0 features include:

* Lock screen with controller and keyboard PIN keypad
* 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.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 / Lock Screen
│
├── Desktop Mode
│   ├── KDE Plasma
│   ├── Nebula desktop theme
│   ├── 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
* Lock screen
* 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 currently focused on building the Bigscreen shell first, while planning Desktop Mode as the second major pillar of the OS.

---

## 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
* Lock screen work
* 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: Bigscreen Shell

Goal: Build a polished controller-first shell.

Deliverables:

* Lock screen
* Home dashboard
* Library screen
* Settings screen
* Power menu
* Controller navigation
* Fullscreen mode
* Basic app launching

---

### Phase 2: Desktop Mode Foundation

Goal: Create the NebulaOS desktop environment experience.

Deliverables:

* KDE Plasma setup
* Nebula theme
* SDDM login configuration
* Bigscreen and Desktop session entries
* Desktop-to-Bigscreen switching
* Basic Nebula desktop tools

---

### Phase 3: Session Integration

Goal: Make NebulaOS feel like a real OS experience.

Deliverables:

* Bigscreen session selectable from login
* Desktop session selectable from login
* Bigscreen launches fullscreen
* Exit to desktop or login
* Controller works reliably in Bigscreen Mode

---

### 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
* The lock screen works
* 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.