[English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | **한국어**

# Galaxy Explorer 🌌
데모 페이지
https://zjoooooo.github.io/galaxy-explorer/
<img width="1920" height="945" alt="Image_2026-07-04_141404_478" src="https://github.com/user-attachments/assets/ce6388f3-5854-4c13-9d6c-daccac89bf24" />

WebGL(three.js)만으로 브라우저에서 완전히 동작하는, 절차적으로 생성되는 인터랙티브 **우리은하(Milky Way)** 시각화입니다 — 완전한 3D **태양계**, 떠도는 **혜성**, 그리고 실제 **전파 은하 제트**까지 담았습니다. 백엔드도, 빌드 과정도, 설치할 의존성도, API 키도 필요 없습니다 — 페이지를 열기만 하면 바로 탐험할 수 있습니다.

은하 자체는 로드 시점에 코드로 생성됩니다: **이미지 에셋은 단 하나도 없습니다** — 나선팔, 성운 가스, 성단, 먼 은하들과 초신성까지 전부 수학으로 그려집니다. 태양계는 그 위에 행성, 위성, 태양을 위한 실제 NASA 기반 표면 텍스처를 입힙니다.

**모든 비상업적 용도로 무료입니다** — 개인 학습, 수업, 학술 연구 모두 [PolyForm Noncommercial License 1.0.0](LICENSE) 하에 자유롭게 사용할 수 있습니다. 상업적 이용에는 별도의 라이선스가 필요합니다 — [이슈](https://github.com/zjoooooo/galaxy-explorer/issues)로 문의해 주세요.


## ✨ 주요 기능

- **나선 원반** — 4개의 밀도파 나선팔 위에 뿌려진 약 85,000개의 먼지 입자. 따뜻한 중심부에서 차가운 푸른 나선팔로 이어지는 색 변화, 밝은 별 매듭, HII 영역, 푸른 성단까지 담았습니다.
- **볼류메트릭 느낌의 성운** — 연속적인 fBm + Worley 노이즈 셰이더 필드(도메인 워핑된 나선, 먼지 띠, 빛나는 중심핵)가 나선팔을 가스로 감쌉니다.
- **은하 팽대부** — 천천히 "숨 쉬는" 부드러운 멀티스케일 발광 코어.
- **딥필드 하늘** — 반짝이는 별 필드에 약 170개의 작은 먼 은하들(타원은하, 나선은하, 측면 원반은하, 불규칙은하), 풍성한 은하단, 그리고 안드로메다풍의 커다란 이웃 은하 하나까지 — 이 모든 것을 단 두 번의 draw call로 그립니다.
- **물리 기반 배경 이벤트** — 이따금 나타나는 별똥별과 유성우, 그리고 실제 광도 곡선(t².³ 상승 → 둥근 정점 → 이중 기울기 감쇠)을 따르는 초신성이 4갈래 회절 스파이크 섬광과 함께 터집니다.
- **인터랙티브 비컨** — 클릭 가능한 마커 약 30개(태양계, 궁수자리 A*, 유명 성운, 성단, 별, 블랙홀)를 클릭하면 선택된 천체에 빛나는 3D 링과 함께 5개 언어 상세 정보 카드가 열립니다. 외부 은하 가까이 날아가면 그 은하만의 **은하 내부 천체**가 나타납니다 — 별 형성 영역, 구상성단, 초신성 잔해, 전파 제트까지 각각 자체 카드를 지닙니다.
- **전파 은하 제트** — **센타우루스자리 A**는 바늘처럼 가느다란 두 줄기 플라스마 빔(북쪽은 파란색, 남쪽은 보라색)을 뿜어내며, 살아 있는 물줄기처럼 흐르고 일렁이고 솟구칩니다. 각 빔은 거대하게 소용돌이치는 **전파 로브**로 끝나는데, 이는 전파 망원경이 실제로 관측하는 구조입니다. **M87**은 그 유명한 *한쪽만 보이는* 제트를 유지하는데, 반대편 제트가 도플러 효과로 어두워져 보이지 않기 때문입니다.
- **태양계 가이드** — **태양계** 비컨을 따라 6초짜리 **웜홀**을 타고 완전한 3D 태양계로 들어갑니다: 태양, 여덟 행성 전부, 달, 세레스, 명왕성, 그리고 유명한 위성 7개가 실제 NASA 기반 이미지(주요 천체는 4K)로 감싸이고, 태양 위치의 단일 햇빛 광원으로 조명됩니다. 아무 천체나 클릭하면 삽화가 있는 5개 언어 카드가 열리고, **이 천체로 날아가기**를 누르면 공전하는 행성 위로 휩쓸려 가 그 위성들이 나타나는 동안 *함께 따라 돕니다*. **살아 있는 태양**은 흘러가는 쌀알 무늬, 이동하는 흑점, 그리고 쏟아져 나와 흩어지는 홍염을 보여 줍니다. 커크우드 간극이 있는 실제 폭의 **소행성대**, **카이퍼대**, 거대 행성의 희미한 고리, 반투명한 **대기 가장자리 빛**이 장면을 완성합니다. **혜성** 두 개가 이심률 큰 궤도를 떠돌며 태양 근처에서 고전적인 쌍둥이 꼬리 — 곧게 뻗은 파란 **이온 꼬리**와 굽은 하얀 **먼지 꼬리** — 를 펼칩니다. 하나를 클릭하면 원리를 읽거나 **이 혜성을 쫓아가기**로 뒤쫓을 수 있습니다. 관찰하기 쉽도록 공전과 자전은 의도적으로 느리게 했으며, 표시 축척과 초기 위치는 읽기 쉽게 구성한 것이지 실제 축척 모형이나 실시간 천문력은 아닙니다.
- **별자리 하늘 보기** — 지구 카드에서 대기처럼 하얀 섬광을 지나 지구 중심의 회전 가능한 별 돔으로 들어갑니다. 실제 J2000 별 위치로 그린 **25개 별자리**(황도 12궁 + 유명한 13개)와, 진짜 소속 별자리 안에 자리한 **7개의 외부 은하**가 각각 자체 5개 언어 사진 카드와 함께 표시됩니다.
- **5개 언어** — 라벨, 카드, 탐색은 영어, 중국어 간체·번체, 일본어, 한국어로 전환할 수 있습니다(우측 상단 선택기, 선택은 기억됩니다).
- **시네마틱한 화면** — 선택적 bloom + ACES 톤 매핑.
- **성능 자동 대응** — FPS 워치독이 저사양 GPU에서 먼지 밀도를 자동으로 낮춰, 노트북·TV·키오스크에서도 부드럽게 동작합니다.

## 🎯 이런 곳에 쓸 수 있습니다

- **학습과 교육** — WebGL, three.js, GLSL 셰이더, 절차적 생성, 파티클 시스템, 노이즈(fBm/Worley)를 담은 간결하고 읽기 좋은 단일 파일 예제. 천문학, 컴퓨터 그래픽스, 크리에이티브 코딩 수업에 안성맞춤입니다. 모든 서브시스템이 독립적이고 주석이 달려 있습니다.
- **배경 화면과 스크린세이버** — 랜딩 페이지 히어로 배경, 데스크톱/보조 모니터 배경, 대기 화면용 앰비언트 은하.
- **디지털 사이니지와 설치 전시** — 로비 스크린, 박물관/천체투영관 디스플레이, 행사 배경. 전체 화면으로 실행할 수 있습니다(`F` 키로 시네마 모드).
- **출발점으로** — 포크해서 나만의 우주 시각화, 은하 캔버스 위의 데이터 시각화, 게임 배경, 아트 프로젝트를 만들어 보세요.

## 🚀 설치 및 실행

**설치가 필요 없습니다.** 파일을 받아 HTTP로 서빙하기만 하면 됩니다(브라우저는 `file://` 프로토콜에서 오디오나 텍스처 같은 일부 기능을 차단합니다).

```sh
# 1. 코드 받기
git clone https://github.com/zjoooooo/galaxy-explorer.git
cd galaxy-explorer

# 2. 아무 정적 서버로 서빙하기, 예:
python -m http.server 8000
#   또는:  npx serve .
#   또는:  php -S localhost:8000

# 3. http://localhost:8000/ 열기
```

**정적 호스팅이면 어디든 배포 가능:** GitHub Pages, Netlify, Vercel, Cloudflare Pages, S3, nginx 등 어떤 웹 호스트든 됩니다. 폴더를 업로드하기만 하면 끝 — 빌드할 것이 없습니다.

## 🎮 조작법

| 조작 | 효과 |
|---|---|
| **드래그** | 카메라 궤도 회전 |
| **스크롤 / 핀치** | 확대 / 축소 |
| **비컨, 천체 또는 혜성 클릭** | 해당 카드를 열며, 천체를 선택해도 카메라와 운동은 바뀌지 않음 |
| **이 천체로 날아가기 / 이 혜성을 쫓아가기** | (카드에서) 움직이는 천체 위로 휩쓸려 가 함께 따라 돔 |
| **뒤로** | 한 단계씩 돌아감: 하늘 → 지구 → 태양계 개요 → 은하 |
| **`Esc`** | 단계적으로 돌아감: 카드를 닫고, 현재 태양계 단계를 나간 뒤, 마지막으로 태양계를 나감 |
| **`F`** | 시네마 모드 — 모든 UI 숨기기 |
| **`M`** | 배경 음악 켜기 / 음소거 (선택 사항, 아래 참고) |

**URL 파라미터**

- `?fx=1` — 데모 모드: 4초마다 별똥별/유성우/초신성을 강제로 발생시켜 배경 효과를 바로 확인할 수 있습니다.
- `?tune=1` — 성운 발광 셰이더용 실시간 슬라이더. 화면을 실시간으로 조정하다가 마음에 드는 값을 tunables에 복사하면 됩니다.

## 🎛️ 커스터마이즈

`index.html`을 열고 `<script>` 상단 부근의 **tunables** 블록을 수정하세요:

```js
var BLOOM = { strength: 0.08, radius: 0.32, threshold: 0.42 }; // 발광
var DUST  = { count: 85000, radius: 360, arms: 4, tight: 0.85, brightness: 0.5, ... };
var GALAXY_SPIN = 0.013; // 회전 속도 (라디안/초)
```

- `DUST.count` — 별/먼지 총량 (사양이 낮은 하드웨어에서는 값을 낮추세요).
- `DUST.arms` / `DUST.tight` — 나선팔 개수와 감기는 정도.
- `BLOOM.strength` — 전체 발광 강도 (0 = 끔).
- `GALAXY_SPIN` — 은하 전체가 회전하는 속도.

## 🎵 배경 음악

`audio/`에 앰비언트 트랙 3곡이 들어 있으며 **로드 시 자동 재생**됩니다(자동 재생을 차단하는 브라우저에서는 첫 상호작용 시 재생되는 폴백 포함). 우측 하단의 스피커 버튼이나 `M` 키로 음소거를 전환할 수 있고, 버튼에 마우스를 올리면 트랙을 이름으로 고를 수 있습니다. 트랙은 반복 재생됩니다.

음악을 바꾸려면 `.mp3` 파일을 `audio/`에 넣고 `index.html`의 `MUSIC_TRACKS`에 파일 이름을 나열하세요:

```js
var MUSIC_TRACKS = ['ambient 1.mp3', 'ambient 2.mp3'];
```

`MUSIC_TRACKS`를 비워 두면 스피커 버튼이 아예 숨겨집니다.
**공유 권한이 없는 저작권 보호 오디오는 커밋하지 말아 주세요.**

## 🛠️ 동작 원리 (간단히)

바닐라 JavaScript + three.js r128(`vendor/` 아래에 번들). 자체 완결적인 `index.html` 파일 하나로 구성됩니다. 은하는 로드 시 한 번 만들어집니다:

1. 밀도파 나선팔 위에 먼지 입자를 뿌립니다(`Points` 클라우드).
2. 원반 평면에 깔린 평면 메시가 프래그먼트 셰이더로 나선을 따라 변조된 fBm + Worley 구름 노이즈를 계산해 성운 가스를 만듭니다.
3. 스프라이트 발광이 팽대부를 이루고, 반짝이는 원거리 구가 배경 하늘이 됩니다.
4. 절차적 텍스처 아틀라스 + 빌보드 쿼드 배치가 먼 은하들을 그립니다.
5. 후처리: `UnrealBloomPass`로 발광 효과를 준 뒤 ACES 톤 매핑 패스를 적용합니다.

배경 효과(유성, 초신성)는 스케줄에 따라 생성되었다가 스스로 정리되는 수명이 짧은 객체입니다 — 대기 상태에서는 프레임당 비용이 전혀 없습니다.

태양계는 웜홀 전환을 통해 진입하는 두 번째 장면입니다. 그 행성들은 태양 위치의 단일 점 광원으로 조명되며, 번들로 포함된 NASA / Solar System Scope 맵으로 텍스처가 입혀집니다(첫 진입 시 로드). 혜성, 제트, 홍염, 꼬리는 매 프레임 미리 할당된 버퍼에 기록되는 파티클 시스템입니다.

## 🤝 기여하기

기여, 포크, 아이디어 모두 대환영입니다! 배우고 발전시켜 나가라고 만든 친근한 프로젝트입니다.

- **버그를 찾았거나 아이디어가 있나요?** [issue](https://github.com/zjoooooo/galaxy-explorer/issues)를 열어 주세요.
- **무언가 추가하고 싶나요?** 리포지토리를 포크해서 수정한 뒤 pull request를 열어 주세요. 아이디어 몇 가지: 새로운 배경 효과, 더 다양한 은하 형태, 설정 패널, VR/모바일 지원, 색상 테마, 성능 개선.
- 가능한 한 **의존성 없는 단일 파일 구조를 유지**해 주세요 — 그 덕분에 배우기 쉽고 어떤 프로젝트에든 바로 가져다 쓸 수 있습니다.
- 변경 사항은 폴더를 서빙해서 브라우저로 열어 테스트하세요. 실행할 빌드나 테스트 스위트는 없습니다.

기여해 주시면 해당 기여물이 PolyForm Noncommercial License 1.0.0 하에 라이선스되는 것에 동의하는 것으로 간주됩니다.

## 📄 라이선스

[PolyForm Noncommercial 1.0.0](LICENSE) — 개인 학습, 취미 프로젝트, 수업, 학술 연구,
그리고 학교·박물관·천문관 등 비영리 기관에서의 사용을 포함한 **모든 비상업적 용도**로
무료입니다. 출처 표기는 해 주시면 감사하지만 필수는 아닙니다.

**상업적 이용에는 별도의 라이선스가 필요합니다.** [이슈](https://github.com/zjoooooo/galaxy-explorer/issues)로 문의해 주세요.

`v2.2.0` 이하의 릴리스는 MIT License로 배포되었으며, 해당 조건으로 계속 사용할 수 있습니다.

three.js와 그 예제 모듈(`vendor/` 아래에 번들)의 저작권은 three.js 저자들에게 있으며 MIT License를 따르고, 함께 포함된 천체 사진은 각각 고유한 라이선스를 따릅니다 — [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) 참조. 이 프로젝트의 라이선스는 해당 조건에 영향을 주지 않습니다.