nebula-project/Nebula-OS

Fork 0

Files

T

andrew 3a2c3f9ff1 Update README.md

2026-02-15 22:53:15 +13:00

10 KiB

Raw Blame History

Nebula OS v0 – Windows-first Development Plan

Nebula OS Prototype (Current)

This repository now includes a working v0 Nebula OS prototype in the Tauri frontend (src/) with:

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

Dashboard refresh (Xbox-inspired Nebula)

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

Animation and component architecture notes are in src/styles/shell-guidelines.md.

Install

npm install

Run (Windows dev)

npm run dev

Build

npm run build

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.

Nebula Core integration status

@nebulaproject/core is installed and used through runtime adapters in:

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

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.

Local Nebula Core development (Windows-safe)

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.

Clone Nebula Core monorepo next to this repo.
Build Nebula Core packages.
Link from the core repo and consume in this repo:

# In Nebula-Core repo
npm link

# In Nebula-OS repo
npm link @nebulaproject/core

Alternative (more deterministic): use file: dependency in package.json:

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

Then run:

npm install

Linux VM build (high-level)

Install Rust, Node.js, and Tauri Linux prerequisites in the VM.
Clone this repo in 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:

A custom controller-first way to navigate the OS (like a console shell)
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

Controller-first, not controller-compatible
Replace proprietary frontends with an open interface
Separate system layer from UI layer
Build modular infrastructure for long-term independence
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 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)

Used for:

Building Nebula OS 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 OS (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 OS 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.