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

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

- **관리 사이트** — 음악퀴즈 정보(JSON)와 음악·사진 목록, 데이터팩 출력을 한 곳에서 운영.
- **음악퀴즈 간편설치기 (`.exe`)** — `manifest.json` 기반으로 사용자가 마인크래프트 본체·서버·모드를 자동 설치.
- **리소스팩 간편설치기 (`.exe`)** — 음악퀴즈 음악·표지를 yt-dlp 로 받아 painting variant 텍스처 리소스팩으로 패키징.

---

## 무엇이 들어 있나

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

---

## 핵심 컨셉

설치기는 사용자의 `%APPDATA%\.minecraft` 를 더럽히지 않기 위해 **`.mc_custom`** 을 별도 게임 디렉터리로 사용합니다.

```
%APPDATA%\
├─ .minecraft\           ← 원래 마인크래프트 폴더(공용 자원: assets, libraries, versions, runtime)
└─ .mc_custom\           ← 음악퀴즈 전용 게임 폴더(설치기가 자동 생성)
   ├─ mods\              ← 음악퀴즈가 지정한 모드(.jar)
   ├─ resourcepacks\     ← 리소스팩(.zip)
   ├─ saves\             ← 단일 맵 .zip 압축 해제 결과
   ├─ assets\  (junction → .minecraft\assets)
   ├─ libraries\ (junction → .minecraft\libraries)
   ├─ versions\ (junction → .minecraft\versions)
   ├─ options.txt 등     ← `.minecraft` 의 최상위 설정 파일을 복사해 사용
   └─ launcher_profiles  ← 실제 파일은 `.minecraft\launcher_profiles.json` 을 수정해 gameDir=.mc_custom 으로 지정
```

이렇게 분리해 두면 사용자가 평소 쓰던 마인크래프트와 음악퀴즈 설정이 섞이지 않고, 음악퀴즈만 삭제해도 본체에는 영향이 없습니다.

---

## 빠른 시작

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

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

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

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

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

# 4) 음악퀴즈 간편설치기 윈도우 .exe 빌드
npm run dist:win
```

리소스팩 설치기는 `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.zip",
  "mapPath": "mq-v1-map.zip",
  "serverPath": "mq-v1-server.zip",
  "serverMinRam": 4096,
  "serverMaxRam": 8192,
  "clientMinRam": 4096,
  "clientRecommendedRam": 8192
}
```

- `platform.type` = `vanilla` / `forge` / `fabric` / `neoforge`.
- `fabric` 은 `loaderVersion` 만 지정하면 설치기가 최신 fabric-installer 로 자동 CLI 설치합니다.
- 나머지(forge/neoforge) 는 `platform.downloadUrl` 에 설치 jar URL.
- `modsFolder` → `/file/mods/<폴더>/` 의 모든 `.jar` 를 자동으로 받습니다.
- `serverPath` / `mapPath` / `resourcepackPath` → `/file/servers/`, `/file/maps/`, `/file/resourcepacks/` 아래 zip 파일명.

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

---

## 빌드 산출물 / 배포

| 산출물 | 빌드 명령 | 비고 |
| --- | --- | --- |
| 관리 사이트 (Node 실행) | `npm start` | systemd 등으로 띄우기. 외부 도메인이 manifest 의 base URL 이 됩니다. |
| 음악퀴즈 간편설치기 `.exe` | `npm run dist:win` | `electron-builder.yml` 설정 사용. |
| 리소스팩 간편설치기 `.exe` | `tsconfig.installer-rp.json` 빌드 후 `electron-builder` 수동 패키징 |  |

---

## 라이선스

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