minecraft_launcher/README.md

# 마인크래프트 음악퀴즈 통합 패키지

마인크래프트 음악퀴즈를 한 번에 배포·관리할 수 있도록 만든 통합 프로젝트입니다.

- **관리 사이트** — 음악퀴즈 정보(JSON)와 음악·사진 목록, 데이터팩 출력을 한 곳에서 운영.
- **음악퀴즈 간편설치기 (`.exe`)** — `manifest.json` 기반으로 마인크래프트 본체·모드·(멀티 호스트면)서버를 자동 설치. 서버용 JDK 자동 탐색·설치와 `run.bat` 자바 경로 보정, 완료 단계에서 최종 리소스팩 선택 설치까지 처리.
- **리소스팩 간편설치기 (`.exe`)** — 음악퀴즈 음악·표지를 yt-dlp 로 받아 painting variant 텍스처 리소스팩으로 패키징(429/403 재시도·동시 다운로드).
- **간편포트포워딩 (`.exe`)** — 원하는 포트를 입력해 UPnP 로 개방. 프로그램을 켜 두는 동안만 열려 있고 창을 닫으면 자동으로 닫힙니다.
- **음악퀴즈 파일제거 (`.exe`)** — 설치기들이 만든 게임 폴더·캐시와 런처 프로필을 휴지통 이동 또는 완전 삭제로 한 번에 정리.

---

## 무엇이 들어 있나

| 디렉터리 | 역할 | 진입점 |
| --- | --- | --- |
| `src/server/` | 음악퀴즈 관리 웹사이트 (Express + EJS) | `bun start` 또는 `npm start` |
| `src/installer/` | 음악퀴즈 간편설치기 (Electron) | `npm run installer` |
| `src/installer-rp/` | 리소스팩 간편설치기 (Electron) | `npm run installer:rp` |
| `src/installer-pf/` | 간편포트포워딩 도구 (Electron) | `npm run installer:pf` |
| `src/installer-uninstall/` | 음악퀴즈 파일제거 도구 (Electron) | `npm run installer:uninstall` |
| `src/shared/` | 설치기들과 서버가 공유하는 타입·스토어 | — |
| `views/` | EJS 템플릿 (관리 사이트) | — |
| `manifest/` | 음악퀴즈별 정의 JSON | — |
| `file/list/` | 음악퀴즈별 음악·사진 목록 JSON | — |
| `file/` | 정적 파일(서버 zip / 맵 zip / 모드 jar 등) 호스팅 | — |

---

## 핵심 컨셉

설치기는 사용자의 평소 마인크래프트와 음악퀴즈 설정이 섞이지 않도록 **`.mc_custom`** 을 별도 게임 디렉터리(gameDir)로 씁니다. 단, 마인크래프트 **런처는 게임 실행에 필요한 공용 데이터(`versions` / `libraries` / `assets` / `runtime`)를 런처 폴더(`.minecraft`)에서 찾으므로**, 이 데이터(바닐라 + fabric)는 `.minecraft` 에 두고 `.mc_custom` 에는 그 폴더들을 링크(junction)합니다. 게임 데이터(모드/세이브/리소스팩)만 `.mc_custom` 에 별도로 둡니다.

```
%APPDATA%\
├─ .minecraft\           ← 런처 폴더. 게임 실행에 필요한 공용 데이터는 반드시 여기에 있어야 함
│  ├─ assets\            ← 에셋(사운드/번역/스킨 등)
│  ├─ libraries\         ← 자바 라이브러리(바닐라 + fabric)  ※ assets 밖의 형제 폴더
│  ├─ versions\          ← 버전 JSON(바닐라 + fabric-loader-*)  ※ fabric 은 여기에 설치
│  ├─ runtime\           ← 런처 번들 JRE(런처가 직접 사용)
│  └─ launcher_profiles.json  ← 음악퀴즈 프로필(gameDir=.mc_custom)을 추가/갱신
└─ .mc_custom\           ← 음악퀴즈 전용 게임 폴더(gameDir). 설치기가 자동 생성
   ├─ mods\              ← 음악퀴즈가 지정한 모드(.jar)
   ├─ resourcepacks\     ← 리소스팩(.zip). 최종 리소스팩도 여기에 저장
   ├─ saves\             ← 단일 맵 .zip 압축 해제 결과
   ├─ jdk\               ← 설치기가 자동 설치한 JDK(temurin-<버전>)
   ├─ assets\ · libraries\ · versions\  ← `.minecraft` 로의 junction 링크(공용 데이터)
   └─ options.txt 등     ← `.minecraft` 최상위 설정 파일을 복사해 사용
```

이렇게 분리해 두면 음악퀴즈만 삭제해도(파일제거 도구) 본체 마인크래프트에는 영향이 없습니다. fabric 을 `.mc_custom` 이 아닌 `.minecraft` 에 설치하는 이유는, 게임 폴더에 설치하면 바닐라 버전/라이브러리가 빠져 런처가 "Unable to prepare assets for download" 로 실패하기 때문입니다(자세한 흐름은 [`docs/installer.md`](docs/installer.md)).

> **폴더 이름 바꾸기.** 기본값은 `.mc_custom` 이지만 `.env` / `.env.build` 의 `MC_CUSTOM_DIR` 로 다른 이름을 지정할 수 있습니다. 설치기·리소스팩설치기·파일제거기가 모두 이 값을 공유하므로, 값을 바꾸면 세 exe 를 같은 값으로 다시 빌드해야 서로 같은 폴더를 가리킵니다. (경로 구분자 `/ \` 와 `..` 는 무시되어 항상 `%APPDATA%` 바로 아래 단일 폴더가 됩니다.)

---

## 간편설치기 동작 요약

- **JDK(서버용)** — 자바를 ① `.mc_custom\jdk`(자동 설치분) → ② 환경변수(`JAVA_HOME`/`JDK_HOME`) → ③ `C:\Program Files\Java` 순으로 찾아 **권장 버전(`recommendedJdk`)** 을 우선 선택합니다. 없으면 Adoptium Temurin(권장 버전)을 `.mc_custom\jdk` 에 자동 설치합니다. 권장과 다른 버전을 쓰게 되면 경고가 뜹니다.
- **서버 `run.bat`** — 서버 zip 의 `run.bat` 이 시스템 PATH 의 낡은 자바를 쓰지 않도록, 준비/선택한 JDK 의 `java` 를 쓰도록 자동 수정합니다(자동 설치 JDK 는 `%APPDATA%` 전개형 경로라 한글 사용자명에도 안전).
- **최종 리소스팩** — 완료 단계에서 "리소스팩을 설치하시겠습니까?"(예/아니요). 예 → 최종 리소스팩 약관 동의 → `/file/resourcepacks/outputs/` 에서 진행률과 함께 다운로드. `finalResourcepackPath` 가 `"."` 이면 이 질문을 건너뜁니다.
- **약관 표시 대상** — 사이트 약관마다 표시 위치(설치기 / 리소스팩 설치기 / 최종 리소스팩)를 개별 토글합니다.

---

## 빠른 시작

전제: Node.js 18+, npm. 윈도우 빌드를 만들 때만 추가로 Electron 의 PE 서명·아이콘 도구가 필요합니다.

```bash
# 의존성 설치
npm install

# 환경변수 템플릿 복사 (처음 한 번만)
cp .env.example .env

# 1) 관리 사이트 개발 실행 (http://localhost:3000)
npm start

# 2) 음악퀴즈 간편설치기를 Electron 으로 실행해 보기
npm run installer

# 3) 리소스팩 간편설치기를 Electron 으로 실행해 보기
npm run installer:rp

# 4) 간편포트포워딩 / 파일제거 도구 실행해 보기
npm run installer:pf
npm run installer:uninstall

# 5) 윈도우 .exe 빌드 (개별)
npm run dist:win            # 음악퀴즈 간편설치기
npm run dist:win:rp         # 음악퀴즈 리소스팩설치기
npm run dist:win:pf         # 간편포트포워딩
npm run dist:win:uninstall  # 음악퀴즈 파일제거
npm run dist:win:dev        # (개발자용) 음악퀴즈 간편설치기
npm run dist:win:rp:dev     # (개발자용) 음악퀴즈 리소스팩설치기
```

리소스팩 설치기는 `yt-dlp` 가 필요합니다. 자동 다운로드되지만, 막혀 있는 환경이라면 [`docs/yt-dlp-setup.md`](docs/yt-dlp-setup.md) 참고.

---

## 자주 쓰는 문서

| 문서 | 내용 |
| --- | --- |
| [`docs/installer.md`](docs/installer.md) | 음악퀴즈 간편설치기 사용자 흐름(단계별 화면·동작). |
| [`docs/admin-site.md`](docs/admin-site.md) | 관리 사이트 운영자 가이드(음악퀴즈 추가·편집, 음악 목록, 데이터팩 출력). |
| [`docs/resourcepack-installer.md`](docs/resourcepack-installer.md) | 리소스팩 간편설치기 동작 명세(yt-dlp 흐름, 이미지 정규화 규칙). |
| [`docs/painting-variant.md`](docs/painting-variant.md) | 1.21+ painting variant 슬롯/리소스팩 텍스처 규격. |
| [`docs/yt-dlp-setup.md`](docs/yt-dlp-setup.md) | yt-dlp 자동/수동 설치, 트러블슈팅. |

---

## 데이터 포맷 (요약)

자세한 필드 설명은 `docs/admin-site.md` 의 "음악퀴즈 JSON" 절을 참고하세요.

### `manifest.json` — 사이트 루트, 음악퀴즈 목록

```json
{
  "packs": [
    { "name": "음악퀴즈 v1", "file": "mq-v1" }
  ]
}
```

- `file` 은 `/manifest/<file>.json` 의 파일명(확장자 제외).
- 관리 사이트에서 음악퀴즈를 추가/삭제하면 자동으로 갱신됩니다.

### `/manifest/<key>.json` — 음악퀴즈 정의

```json
{
  "name": "음악퀴즈 v1",
  "mcVersion": "1.21.4",
  "platform": {
    "type": "fabric",
    "loaderVersion": "0.16.10"
  },
  "modsFolder": "mq-v1",
  "resourcepackPath": "mq-v1-base.zip",
  "finalResourcepackPath": "mq-v1.zip",
  "outputPackName": "음악퀴즈 v1 리소스팩",
  "mapPath": "mq-v1-map.zip",
  "serverPath": "mq-v1-server.zip",
  "serverMinRam": 4096,
  "serverMaxRam": 8192,
  "clientMinRam": 4096,
  "clientRecommendedRam": 8192,
  "recommendedJdk": 25
}
```

- `platform.type` = `vanilla` / `forge` / `fabric` / `neoforge`.
- `fabric` 은 `loaderVersion` 만 지정하면 설치기가 최신 fabric-installer 로 `.minecraft` 에 자동 CLI 설치합니다.
- 나머지(forge/neoforge) 는 `platform.downloadUrl` 에 설치 jar URL.
- `modsFolder` → `/file/mods/<폴더>/` 의 모든 `.jar` 를 자동으로 받습니다.
- `serverPath` / `mapPath` / `resourcepackPath` → `/file/servers/`, `/file/maps/`, `/file/resourcepacks/` 아래 zip 파일명. `resourcepackPath` 는 리소스팩 설치기의 **베이스** 팩입니다.
- `finalResourcepackPath` → `/file/resourcepacks/outputs/` 의 **최종 리소스팩** zip. 간편설치기 완료 단계에서 사용자가 선택 설치합니다. `"."` 이면 없음(질문 자체를 건너뜀). 최종 리소스팩이 지정되면 간편설치기는 중복인 베이스 리소스팩을 받지 않습니다.
- `outputPackName` → 리소스팩 설치기가 만들 zip 이름/마인크래프트 목록 제목.
- `recommendedJdk` → 서버 실행 권장 JDK 메이저(사이트 편집기의 Adoptium 목록에서 선택). 설치기가 이 버전을 우선 탐색하고 없으면 자동 설치합니다.

### `/file/list/<key>.json` — 음악·사진 목록 (리소스팩 설치기용)

```json
{
  "musicPlaylistUrl": "https://www.youtube.com/playlist?list=...",
  "imagePlaylistUrl": "https://www.youtube.com/playlist?list=...",
  "music": [
    { "url": "https://www.youtube.com/watch?v=...", "title": "...", "artist": "...", "durationSec": 213 }
  ],
  "images": [
    { "url": "https://www.youtube.com/watch?v=..." },
    { "url": "https://example.com/cover.png" }
  ]
}
```

---

## 디렉터리 구조 (전체)

```
minecraft_launcher/
├─ src/
│  ├─ server/              Express + EJS 관리 사이트
│  ├─ installer/           음악퀴즈 간편설치기 (Electron 메인 + preload)
│  ├─ installer-rp/        리소스팩 간편설치기 (Electron 메인 + 음악/이미지 파이프라인)
│  ├─ installer-pf/        간편포트포워딩 도구 (Electron 메인 + preload)
│  ├─ installer-uninstall/ 음악퀴즈 파일제거 도구 (Electron 메인 + preload)
│  └─ shared/              공용 타입, 매니페스트 스토어, mojang/upnp 유틸
├─ installer/              음악퀴즈 설치기 렌더러(HTML/CSS/JS)
├─ installer-rp/           리소스팩 설치기 렌더러(HTML/CSS/JS)
├─ installer-pf/           간편포트포워딩 렌더러(HTML/JS)
├─ installer-uninstall/    파일제거 렌더러(HTML/JS)
├─ views/                  관리 사이트 EJS 템플릿
├─ public/                 관리 사이트 정적 파일(styles.css 등)
├─ manifest/               음악퀴즈 JSON 정의 (운영자가 편집)
├─ file/
│  ├─ servers/             서버 zip
│  ├─ maps/                맵 zip
│  ├─ mods/<폴더>/         모드 jar 묶음 (index.json 자동 생성)
│  ├─ resourcepacks/       베이스 리소스팩 zip
│  │  └─ outputs/          최종 리소스팩 zip (간편설치기 완료 단계용)
│  ├─ platforms/           Forge / NeoForge 설치 jar
│  └─ list/<key>.json      음악·사진 목록
├─ docs/                   사용·운영 문서
├─ manifest.json           사이트 루트 매니페스트 (자동 관리)
├─ account.json            관리자 계정 (절대 외부 노출 금지)
├─ package.json
└─ tsconfig.{,server,installer,installer-rp,installer-pf,installer-uninstall}.json
```

---

## 빌드 산출물 / 배포

| 산출물(파일명) | 빌드 명령 | 비고 |
| --- | --- | --- |
| 관리 사이트 (Node 실행) | `npm start` | systemd 등으로 띄우기. 외부 도메인이 manifest 의 base URL 이 됩니다. |
| `음악퀴즈 간편설치기-<버전>.exe` | `npm run dist:win` | `electron-builder.yml`. |
| `음악퀴즈 리소스팩설치기-<버전>.exe` | `npm run dist:win:rp` | `electron-builder-rp.yml`. |
| `간편포트포워딩-<버전>.exe` | `npm run dist:win:pf` | `electron-builder-pf.yml`. |
| `음악퀴즈 파일제거-<버전>.exe` | `npm run dist:win:uninstall` | `electron-builder-uninstall.yml`. |
| `(개발자용) 음악퀴즈 간편설치기-<버전>.exe` | `npm run dist:win:dev` | 비공개(public=false) 팩만 노출. 제목 앞에 `(개발자용)` 표시. |
| `(개발자용) 음악퀴즈 리소스팩설치기-<버전>.exe` | `npm run dist:win:rp:dev` | 상동. |

빌드 결과물은 `release/` 폴더에 생성됩니다(포터블 exe).

---

## 라이선스

내부 프로젝트. 외부 공개 시 별도 명시.