nebula-project/Nebula-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add mode READMEs and move Bigscreen app

Browse Source 
Add comprehensive READMEs for Bigscreen and Desktop modes, and relocate the Tauri frontend prototype into a new Bigscreen/ subdirectory. This moves package.json/package-lock, src, src-tauri, assets, views, styles and related files into Bigscreen/ to separate the controller-first shell from top-level docs. Update the root README.md to reframe the project as "NebulaOS", describe Bigscreen/Desktop modes, the vision, tech stack and development notes. This reorganizes the repo layout for clearer mode separation and documentation.
This commit is contained in:
Andrew Zambazos
2026-05-21 20:11:18 +12:00
parent b141c0a058
commit f0d2926872
87 changed files with 974 additions and 322 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+398 -322
View File
@@ -1,51 +1,290 @@
# Nebula OS v0 – Windows-first Development Plan
# NebulaOS
## Nebula OS Prototype (Current)
NebulaOS is an open source Linux-based operating system experience built around two modes:
This repository now includes a working v0 Nebula OS prototype in the Tauri frontend (`src/`) with:
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.
- Lock Screen with controller/keyboard PIN keypad (`1234` for v0)
- Home dashboard tile grid (Library, Settings, Power)
- Settings split-pane stub (category list + content panel)
- Library stub view with controller back behavior
- Start/Menu power overlay that traps focus and closes with Back
- Unified input actions (`up/down/left/right/accept/back/menu`) from keyboard + gamepad
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.
### Dashboard refresh (Xbox-inspired Nebula)
The goal is to combine the best parts of console UX, desktop Linux, and modern operating system design into one flexible system.
The shell now uses a premium horizontal dashboard language inspired by console UI patterns:
---
- Left-aligned horizontal app tile rail (Library, Settings, Power)
- Dynamic nebula background stack (gradient, starfield, fog, vignette)
- Shared top bar with reactive accent line and profile/time status
- Layered tile focus states (scale, cyan glow, ripple, elevation)
- Smooth page/focus transitions with cubic-bezier motion curves
- Immersive lock screen with large clock/date and input-revealed PIN panel
- Settings redesign with top category rail + card-based content panel
## Vision
Animation and component architecture notes are in [src/styles/shell-guidelines.md](src/styles/shell-guidelines.md).
NebulaOS is designed around a simple idea:
### Install
> 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 (dev)
---
## Run in Development
```bash
npm run dev
```
### Build
---
## Build
```bash
npm run build
```
### Linux prerequisites (Ubuntu/Debian)
---
Install system dependencies required by Tauri/WebKit:
## Linux Prerequisites
For Ubuntu, Debian, and related distributions, install the system dependencies required by Tauri and WebKit:
```bash
sudo apt update
@@ -62,48 +301,75 @@ sudo apt install -y \
libgtk-3-dev
```
Install Node.js LTS and Rust (if not already installed), then run:
You will also need:
* Node.js LTS
* Rust
* npm
Then run:
```bash
npm install
npm run dev
```
### Controller testing notes (Windows)
---
- Connect an Xbox-compatible controller before launching dev mode.
- Navigation: D-pad or left stick.
- Actions: `A` = Accept, `B` = Back, `Start` = Menu.
- Keyboard mirror for development: arrow keys, Enter, Escape/Backspace.
## Controller Testing
### Nebula Core integration status
For development, connect an Xbox-compatible controller before launching the app.
`@nebulaproject/core` is installed and used through runtime adapters in:
### Controller Mapping
- `src/core/input.js`
- `src/core/nav.js`
- `src/core/state.js`
```text
D-pad / left stick: Navigate
A: Accept
B: Back
Start: Menu
```
If Nebula Core exports are available, the shell uses them for input/navigation/glyphs/theme.
If not, local fallback adapters keep the shell fully functional.
### Keyboard Mirror
### Local Nebula Core development (Windows-safe)
```text
Arrow keys: Navigate
Enter: Accept
Escape / Backspace: Back
```
Current npm package `@nebulaproject/core@0.1.3` re-exports internal `@nebula/*` packages that are not published, so local linking is recommended for active core development.
---
1. Clone Nebula Core monorepo next to this repo.
2. Build Nebula Core packages.
3. Link from the core repo and consume in this repo:
## 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 Nebula-OS repo
# In NebulaOS repo
npm link @nebulaproject/core
```
Alternative (more deterministic): use `file:` dependency in `package.json`:
Alternative deterministic setup using `file:` dependency:
```json
{
@@ -119,341 +385,151 @@ Then run:
npm install
```
### Linux VM build (high-level)
- Install Rust, Node.js, and the Linux prerequisites above.
- Clone this repo in the Linux VM.
- Run `npm install`.
- Run `npm run dev` for integration checks in Linux session.
- Run `npm run build` to produce Linux artifacts.
## 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**
* Integrates first-install Nebula apps such as **Nebula Browser** and **Nebula Launcher**
* 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
## Development Strategy
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
NebulaOS is currently developed across two environments.
---
# 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 OS (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 OS** fullscreen.
Game UI Mode contains:
* Lock screen with controller PIN entry
* Nebula Home dashboard
* 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 OS – The OS UI Layer
Nebula OS 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 OS responsibilities:
* Home dashboard (games, apps, recent activity)
* App launcher for integrated Nebula apps (Nebula Browser, Nebula Launcher, 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 OS 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)
### Windows
Used for:
* Building Nebula OS UI
* Implementing controller navigation
* Designing lock screen
* Designing Library UI
* Building system state architecture
* UI development
* Controller navigation
* Lock screen work
* Library UI
* Settings UI
* Frontend architecture
UI and logic are platform-agnostic.
## Linux VM (Integration & Replacement Layer)
### Linux VM
Used for:
* Building Linux binaries
* Session integration
* SteamCMD integration testing
* Proton/Wine configuration
* System-level testing
* Linux builds
* Session testing
* KDE integration
* Fullscreen shell testing
* Proton and Wine experiments
* System service experiments
Rule:
The current workflow is:
Develop UI on Windows.
Build and test Linux features inside the VM.
```text
Design and build the UI on Windows.
Test OS-level behavior in Linux.
```
---
# Phase Roadmap
## Roadmap
## Phase 1 – Nebula OS (Controller Console Layer)
### Phase 1: Bigscreen Shell
Objective:
Build a polished, console-grade Game UI independent of store integration.
Goal: Build a polished controller-first shell.
Deliverables:
* Lock screen with PIN keypad
* Lock screen
* Home dashboard
* Library screen (mock data)
* Library screen
* Settings screen
* Power menu
* Controller navigation grid system
* Fullscreen window behavior
No external integrations yet.
* Controller navigation
* Fullscreen mode
* Basic app launching
---
## Phase 2 – Session Integration
### Phase 2: Desktop Mode Foundation
Objective:
Make Nebula OS a selectable login session.
Goal: Create the NebulaOS desktop environment experience.
Milestones:
Deliverables:
* Nebula Game UI appears at login
* Launches fullscreen
* Exiting returns to login
* Controller works reliably
* KDE Plasma setup
* Nebula theme
* SDDM login configuration
* Bigscreen and Desktop session entries
* Desktop-to-Bigscreen switching
* Basic Nebula desktop tools
---
## Phase 3 – Nebula Library Foundations
### Phase 3: Session Integration
Objective:
Begin true replacement behavior.
Goal: Make NebulaOS feel like a real OS experience.
Milestones:
Deliverables:
* 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.
* 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 – Store Integrations
### Phase 4: Nebula Library Foundation
Objective:
Add real backend integration without proprietary UI.
Goal: Begin true game and app management.
Potential directions:
Deliverables:
* SteamCMD for Steam installs
* Legendary (Epic CLI) integration
* Heroic backend reuse (without UI dependency)
* OpenGOG community tools
Nebula Library becomes the single UI.
* Local app database
* Installed games database
* Manual game adding
* Local executable launching
* Metadata structure
* Cover art and banner support
* Store backend abstraction
---
# Security Strategy
### Phase 5: Store and Compatibility Integrations
Game UI lock screen:
Goal: Turn Nebula Library into a real open game manager.
* Local PIN authentication
* Optional profile system (future)
Potential integrations:
Linux account authentication remains system-level.
* SteamCMD
* Proton
* Wine
* Legendary for Epic Games
* GOG tooling
* Heroic backend concepts
* Per-game compatibility settings
---
# What Nebula OS Is Not
## Success Criteria for v0
* Not a Steam skin
* Not Big Picture mode
* Not a launcher aggregator
* Not dependent on proprietary UIs
NebulaOS v0 is successful when:
It is an open system layer that manages games directly.
* 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
---
# Immediate Action Plan
## Long-Term Goal
1. Build Nebula OS 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
NebulaOS should become a gaming OS that feels native, polished, and open.
---
A user should be able to:
# Success Criteria for v0
* 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
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.
NebulaOS is the bridge between a console experience and a real computer.