SOLBIT

한국어 보기 (README_KR.md)

https://sol.d9ng.co.kr SOLBIT is a WebGPU-first solar system simulation project built with Three.js, with a synchronized server clock, cinematic rendering controls, and interactive camera modes for exploration.

What This Project Is

SOLBIT combines:

• physically-inspired orbital simulation (shared astronomy layer)
• a real-time rendering client (WebGPU + node materials)
• a sync server (REST + Socket.IO)

It is designed for both visual quality and developer extensibility.

Key Features

• Real-time Sun/planet/satellite simulation
• Cinematic and Galactic frame modes
• Planet focus workflow with auto-slow pacing
• Idle focus viewing mode (slow reverse-spin camera orbit)
• WebGPU-based post-processing (bloom + exposure control)
• Planet shading pipeline with day/night lighting inputs
• Optional first-person landing mode (experimental)

Current Feature Status

• Primary interaction path: planet focus and free viewing
• Landing mode: Experimental
  • accessible via keyboard shortcuts only (no dedicated UI entry)
  • keys: 1,2,3,4,0 for Mercury/Venus/Earth/Mars/Moon
  • disabled in Galactic mode

Monorepo Layout

solbit/
├─ packages/
│  ├─ client/    # Vite + Three.js (WebGPU), camera/input/UI/simulation
│  └─ server/    # Fastify + Socket.IO (time pulse + planet API)
├─ shared/       # Orbital constants and astronomy math
├─ docs/         # Internal technical docs for developers/AI agents
├─ tests/        # Root tests
└─ scripts/      # Asset/texture helper scripts

Tech Stack

• TypeScript
• pnpm workspaces
• Three.js (three/webgpu, three/tsl)
• Fastify + Socket.IO
• Redis (optional server state persistence)

Quick Start

1) Install

pnpm install

2) Fetch textures (required for full visuals)

Textures are intentionally excluded from Git history to keep the repository lightweight and GitHub-friendly.

Run:

./scripts/fetch_planet_textures.sh
node ./scripts/fetch_usgs_landing_assets.mjs

Notes:

• fetch_planet_textures.sh expects curl; for 4K resize steps it also needs ImageMagick (magick or convert).
• If you skip this step, the app still runs but many planets will render with missing/limited texture detail.

3) Run server and client

pnpm dev:server
pnpm dev:client

Default URLs:

• Server: http://localhost:3001
• Client: http://localhost:5173

Build and Validation

pnpm build
pnpm typecheck
pnpm test

Notes:

• Client-only typecheck: pnpm --filter @solbit/client typecheck
• If a root test fails, verify whether it is an existing baseline issue vs. your change scope.

Runtime Architecture

Client Boot Flow

1. packages/client/src/main.ts loads App.ts
2. Engine initializes renderer, controls, post-processing
3. Sun and scene systems are created
4. Planets/satellites are loaded from /api/planets (with shared fallback)
5. SolarSync starts clock synchronization
6. Main simulation tick (registerSimulationTick) is attached
7. Focus/landing/helper tickers and input handlers are registered

Server Responsibilities

• GET /api/planets: orbital payload
• GET /api/system-start: system start timestamp
• Socket events:
  • solar-pulse (server time pulse)
  • client-ping / client-pong (latency estimation)

Shared Responsibilities

• orbital data and units (AU, epoch)
• orbital position solver (getOrbitPosition)

Camera, Focus, and Modes

• Focus entry uses animated camera framing around the selected body
• Active focus maintenance and viewing behavior is handled by auxiliary focus ticker logic
• Mode constraints:
  • Cinematic speed presets: UL/L/M/H
  • Galactic speed presets: M/H/UH

Controls (Current)

• Mouse click: focus target body
• HUD Speed button: cycle speed preset
• HUD Mode button: toggle Cinematic/Galactic
• Keyboard shortcuts:
  • 1..4: experimental landing entry (Mercury/Venus/Earth/Mars)
  • 5..9: focus outer planets (Jupiter/Saturn/Uranus/Neptune/Pluto)
  • 0: experimental landing entry (Moon)
  • Esc: exit landing mode

Environment Variables

Server

• HOST (default 0.0.0.0)
• PORT (default 3001)
• REDIS_URL (default redis://127.0.0.1:6379)
• USE_REDIS (false disables Redis)

Client

• VITE_SOLAR_SERVER
  • default dev target: http://localhost:3001

Debug Flags

Use in browser console:

• window.__DEBUG_FOCUS__
• window.__DEBUG_PLANET_LIGHT__
• window.__DEBUG_PLANET_NDOTL__
• window.__DEBUG_SPACE_BG__
• window.__DEBUG_BINARY_BARYCENTER__
• window.__SOLBIT_RENDER_BACKEND__

Documentation

• docs/DOCS_INDEX.md
• docs/BASIC.md
• docs/PROJECT_TECHNICAL_HANDOFF.md
• docs/AI_REFACTOR_GUIDE.md
• docs/GALACTIC_MODE_MODEL.md

Contribution Notes

When making non-trivial simulation/camera changes:

1. run client typecheck
2. verify focus mode behavior
3. verify cinematic/galactic transitions
4. verify trail continuity during mode/speed changes