https://github.com/qtremors/cosmos
A high-performance, procedural virtual cosmos simulation built with React and Three.js. Features realistic orbital physics, volumetric shaders, and an active radar navigation system.
https://github.com/qtremors/cosmos
react-typescript simulation space-exploration three-js visualization
Last synced: 5 months ago
JSON representation
A high-performance, procedural virtual cosmos simulation built with React and Three.js. Features realistic orbital physics, volumetric shaders, and an active radar navigation system.
- Host: GitHub
- URL: https://github.com/qtremors/cosmos
- Owner: qtremors
- License: other
- Created: 2025-12-11T09:41:05.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-10T09:35:35.000Z (6 months ago)
- Last Synced: 2026-01-11T02:51:30.358Z (6 months ago)
- Topics: react-typescript, simulation, space-exploration, three-js, visualization
- Language: TypeScript
- Homepage: https://cosmox.vercel.app/
- Size: 64.3 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Cosmos
> **Experience the infinite.** A modular, high-performance 3D solar system simulation running directly in your browser.
Explore the solar system with **2K NASA textures**, realistic orbital mechanics, and a cinematic camera system with gamepad support.
---
## ✨ Features
### 🌍 Complete Solar System
- **9 Planets** with 2K NASA texture maps
- **Earth:** Day/night cycle with cloud layer
- **Saturn:** Procedural ring system
- **Uranus & Neptune:** Subtle ring systems
- **4 Moons:** Moon, Europa, Titan, Charon
- **Asteroid Belt:** 2000 instanced asteroids
### 🏔️ Quantumania System (NEW in v1.6.0)
- **Floating mountains** - 11 unique mountains with distinct themes
- **The Nexus** - Central hub of Quantumania
- **Local lighting** - Volcanic glow, crystal lights, city lights
- **Distant beacon** - Purple pulsing light visible from Solar System
- **Teleportation** - Click radar tabs to travel between systems
### 🎨 Custom Shaders
- **Sun:** Granulation + animated noise + corona
- **Rocky Planets:** Surface textures with lighting
- **Gas/Ice Giants:** Atmospheric effects and rings
### 🥚 Easter Eggs
- **Explorer-1:** Smart touring spaceship with collision avoidance
- **The Kyln:** Massive Nova Corps prison from Guardians of the Galaxy
- **Alien X:** Cosmic entity outside the solar system
- **Sagittarius A\*:** Supermassive black hole at the galactic center with raymarched accretion disk
### 🎮 Controls
| Action | Keyboard | Gamepad |
|--------|----------|---------|
| Move | WASD + R/F | Left Stick |
| Look | Arrows / Mouse Drag | Right Stick |
| Roll | Q/E | L1/R1 |
| Boost | Shift (hold) | RT |
| Zoom | Scroll | D-Pad |
| Labels | L | - |
| HUD | H | - |
| Top View | T | - |
| Unlock | Escape | - |
---
## 🚀 Getting Started
```bash
git clone https://github.com/qtremors/cosmos.git
cd cosmos/cosmos-app
npm install
npm run dev
```
Open `http://localhost:5173`
### Production Build
```bash
npm run build
npm run preview
```
---
## 🛠️ Tech Stack
| Component | Technology |
|-----------|------------|
| Framework | React 19 |
| 3D Engine | Three.js |
| Language | TypeScript |
| Build | Vite 7 |
---
## 📁 Project Structure
```
cosmos/
├── README.md # This file (source of truth)
├── TASKS.md # Development tasks
├── CHANGELOG.md # Version history
└── cosmos-app/
├── src/
│ ├── App.tsx # Main scene, input, radar
│ ├── core/
│ │ ├── SDK.ts # Physics constants & utilities
│ │ └── InputHandler.ts
│ ├── objects/ # All celestial bodies
│ └── materials/
│ └── Noise.ts # Shared GLSL
└── public/
└── textures/ # 2K NASA textures
```
---
## ⚙️ Configuration
All parameters in `src/core/SDK.ts`:
| Config | Purpose |
|--------|---------|
| `UNITS` | Solar radius, AU scale |
| `PLANETS` | Radius, distance, speed, eccentricity |
| `CONTROLS` | Fly speed, boost, FOV |
| `RADAR` | Range, entity colors |
| `LIGHTING` | Sun intensity, ambient |
---
## 👷 Contributing
See [TASKS.md](TASKS.md) for open issues.
**Branch Policy:**
- Work on `ag-dev` branch
- Only maintainer merges to `main`
**Adding a Celestial Body:**
1. Add config to `SDK.ts` → `PLANETS`
2. Create class in `src/objects/`
3. Add to scene in `App.tsx`
4. Add to radar entities
5. Update docs
---
## 📝 Changelog
See [CHANGELOG.md](CHANGELOG.md) for full history.
**Recent:**
- **v2.0.0** - Naming consistency overhaul, custom license, comment cleanup
- **v1.9.5** - System-aware HUD, lazy model loading, camera transitions
- **v1.9.0** - Test suite (Vitest), shader extraction
---
## 📄 License
Tremors Source License v1.1. See [LICENSE](LICENSE).
- ✅ Fork & build with **permanent attribution**
- ❌ Commercial use requires written permission
---
Made with 💖 by Tremors