STELLAR

A retro-futuristic, gamified 3D star map for your browser.

---

There are roughly 120,000 catalogued stars within a few hundred parsecs of our Sun. Each one is a real place — a furnace of hydrogen plasma with a measurable position, color, temperature, and luminosity. Most of us will never visit any of them. But we can look.

STELLARIS exists because staring at the night sky should feel like something. Not like scrolling a spreadsheet of coordinates, but like piloting a ship through an old Soviet star atlas that somehow ended up on a glowing CRT monitor. It is an astronomy toy dressed in phosphor green and amber warning lights, built for the kind of person who opens Wikipedia's "List of nearest stars" and loses an hour.

The entire project is an excuse to render real astronomical data with an unreasonable amount of care — Bézier camera arcs, bloom shaders, typewriter narration, and achievement badges for visiting Betelgeuse. It is not scientifically rigorous software. It is a joyful thing.

---

The Dataset

STELLARIS renders stars from the HYG Database v3, a compilation of three major stellar catalogues:

• Hipparcos — The ESA astrometry satellite catalogue (~120,000 stars with precise parallax-derived distances)
• Yale Bright Star Catalogue — The classic naked-eye star reference (~9,000 bright stars with detailed metadata)
• Gliese Catalogue of Nearby Stars — A focused catalogue of stars within 25 parsecs (~3,800 nearby stellar systems)

The HYG database merges these into a single CSV with 3D Cartesian coordinates (in parsecs), B-V color indices, proper names, spectral classifications, and absolute/apparent magnitudes. Every star you see in the map is a real object with real coordinates — not procedurally generated.

Star colors are derived from the B-V color index using a physically-motivated mapping: hot blue-white O/B stars, yellow G-type stars like our Sun, and cool red M-type giants all render in their approximate true color.

Source: HYG Database by David Nash (astronexus). The dataset is freely available under a Creative Commons license.

---

What It Does

3D Star Map

Navigate through 119,000+ real stars rendered with custom GLSL shaders and bloom post-processing. WASD + mouse controls with pointer lock for free-roam flight. Double-click any named star to fly to it on a dramatic Bézier camera arc.

Star Information

Click any named star to open its info panel — see its proper name, catalogue designations, spectral class, distance from Sol, absolute magnitude, and luminosity. Every data point comes from the HYG catalogue.

Guided Trails

Follow curated narrative journeys between stars. Three trails ship with the app:

• Sun's Neighborhood — Visit the nearest stellar neighbors within a few parsecs
• Giants of the Galaxy — Tour the most massive and luminous stars in the catalogue
• Summer Triangle — Navigate the famous asterism of Vega, Deneb, and Altair

Each trail stop includes narration text displayed in a typewriter animation.

Gamification

• Score — Earn 10 points per new star visited
• Badges — 14 achievements across 4 tiers (common, uncommon, rare, legendary), auto-awarded as you explore
• Captain's Log — Personal journal entries saved per star visit
• Progress Persistence — Everything syncs to a PostgreSQL database and restores on login

CRT Aesthetic

Scanline overlay, vignette, phosphor glow on every UI element, Orbitron display font, Share Tech Mono data readouts, VT323 typewriter narration. The whole thing looks like a 1972 Soviet mission control terminal that somehow got a WebGL upgrade.

Search

Fuzzy star search by name with keyboard shortcut (/). Results show distance and spectral class.

Settings

Adjustable bloom intensity, toggleable scanlines, narration speed control — all persisted to localStorage.

---

Tech Stack

Layer	Technology
Framework	Next.js 14 (App Router)
3D Rendering	Three.js + custom GLSL shaders
Post-Processing	UnrealBloomPass
Camera Animation	GSAP
Database	PostgreSQL + Prisma 5
Auth	NextAuth.js v5 (credentials provider)
Client State	Zustand
Styling	Tailwind CSS + CSS custom properties
CSV Parsing	PapaParse (streaming)
CI	GitHub Actions

---

Building Locally

Prerequisites

• Node.js 18+ (LTS recommended)
• PostgreSQL 14+ (or Docker)
• npm 9+

1. Clone and install

git clone https://github.com/humzakhan/stellar.git
cd stellar
npm install

2. Set up the database

Option A: Docker (recommended)

docker compose up -d

This starts a PostgreSQL instance on port 5432 with a stellaris database.

Option B: Local PostgreSQL

Create a database named stellaris and note your connection string.

3. Configure environment

cp .env.example .env.local

Edit .env.local:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/stellaris"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="any-random-string-at-least-32-characters-long"

4. Push the database schema

npm run db:push

5. Start the dev server

npm run dev

Open http://localhost:3000. Register a username and password, and you'll be dropped into the star map.

Keyboard Controls

Key	Action
W/A/S/D	Move forward/left/backward/right
Mouse	Look around (after clicking to enter navigation)
ESC	Exit navigation / close panels
Click	Select a star
Double-click	Fly to a star
/	Open search
L	Open captain's log
T	Open trail selector
S	Open settings

---