minecraft_launcher/docs/add.md

# 추가사항: 음악퀴즈 리소스팩 간편설치기(exe) & 웹사이트

기본 골격은 현행 음악퀴즈 간편설치기와 동일하므로 그쪽 코드 재활용.

## 작동 방식

`manifest.json` → 음악퀴즈 선택 → `file/list/<음악퀴즈>.json` 에서 음악·사진 목록을 가져온 뒤,
yt-dlp로 음악 다운로드, 별도 경로로 사진 다운로드 → 리소스팩으로 패키징.

---

## 1. 리소스팩 간편설치기 (exe)

번호가 붙은 단계는 "이전 / 다음"으로 이동 가능하게 한다.

### 1) manifest 선택

- `도메인/manifest.json` 에서 음악퀴즈 선택.
- `file/list/<음악퀴즈>.json` 에서 다음을 로드:
  - 음악 목록 (유튜브 영상 주소)
  - 사진 목록 (유튜브 주소 또는 일반 이미지 주소)

### 2) 리소스팩 설치

- "다음"을 누르면 자동 시작.
- 설치 로그 표시 (곡 제목이 아니라 `n번 노래 다운로드 중…` 형식).
- 취소 버튼 / 창 닫기 / 강제 종료 시: 진행 중 다운로드를 안전하게 중단하고 임시 파일을 정리한 뒤 정상 종료.

#### 2-1. yt-dlp 준비

- 설치 경로: `%appdata%/.mc_custom/`
- 이미 있으면 업데이트 확인 후 사용.
- 시스템 PATH 에 이미 yt-dlp 가 등록돼 있으면 그것을 사용하고 업데이트 확인.

#### 2-2. 음악 다운로드 (1번부터 순차)

- 임시 경로: `%appdata%/.mc_custom/.temp/`
- 각 곡을 `ogg` 로 변환 (Minecraft 사운드 호환 포맷).
- 중단되거나 전부 끝나면 `.temp` 내용 삭제.

#### 2-3. 사진 다운로드 (1번부터 순차) → painting variant 텍스처

이미지는 두 형태로 들어올 수 있다.

- **유튜브 주소**: yt-dlp 가 알려준 영상 ID 로
  `https://i.ytimg.com/vi/<id>/maxresdefault.jpg` 를 1차 시도, 실패하면 `hqdefault.jpg` 로 폴백.
- **일반 이미지 주소**: HTTP GET 으로 그대로 다운로드.

다운로드 후 painting variant 슬롯 규격에 맞춰 정규화한다 (자세한 슬롯 구조는
`docs/painting-variant.md` 참고).

- **슬롯 규격(고정, 데이터팩 측)**: `4 × 4` 블록 정사각, `cover_01 … cover_N`.
- **최종 PNG 규격(리소스팩 측)**: 정사각 1:1, 최대 `1024 × 1024` px.
  - `4 × 4` 블록 × 블록당 `256` px (×16 배율) → 1024×1024 가 픽셀 그리드와 정확히 일치.
- **정규화 알고리즘**:
  1. 가운데 정사각 크롭: `s = min(원본 가로, 원본 세로)` → `s × s`.
  2. `s > 1024` 이면 `1024 × 1024` 로 축소 (Lanczos 권장).
  3. `s ≤ 1024` 이면 그대로 `s × s` 유지 (업스케일 없음).
- 파일명: `cover_<NN>.png` (`NN` 은 2자리 0패딩).
- 저장 경로: `resourcepack/assets/musicquiz/textures/painting/`.
- 패키지 완성된 리소스팩을 `%appdata%/.minecraft/resourcepacks/` 에 zip 으로 배치.

### 3) 설치 완료

- "확인" 누르면 프로그램 종료.

---

## 2. 웹사이트 추가사항

### /op/dashboard 상단

- `[음악목록 수정]` 버튼 → `/op/list`
- `[데이터팩 수정]` 버튼 → `/op/datapack`

### /op/list

- 상단 왼쪽에 `[돌아가기]` 버튼 → `/op/dashboard`.
- `manifest.json` 에 등록된 음악퀴즈를 카드 한 줄(가로) 목록으로 표시. 표시 내용은 `/op/dashboard` 와 동일.
- 카드 클릭 → `/op/list/:음악퀴즈`.

### /op/list/:음악퀴즈

상단에 **음악목록 / 사진목록** 두 탭. 기본 탭은 "음악목록".

#### 음악목록 탭

- 상단 버튼: `[목록 저장]`, `[목록 초기화]` (초기화 시 빈 목록).
- 그 아래: 플레이리스트 주소 입력칸 + `[플레이리스트 불러오기]`.
  - 클릭 시 "기존 순서가 전부 사라집니다" 경고 팝업(확인/취소). 확인 시 플레이리스트의 영상들을 아래 목록에 채움.
- 목록 디자인: 유튜브 플레이리스트 스타일 (좌측 번호 배지 + 썸네일 + 제목·가수·길이).
  - 항목 드래그로 순서(번호) 변경.
  - 우클릭 메뉴: 수정, 삭제.
  - "수정" 선택 시 팝업으로 새 유튜브 주소 입력.

#### 사진목록 탭

- 상단 버튼: `[목록 저장]`, `[목록 초기화]`.
- 그 아래: 플레이리스트 주소 입력칸 + `[플레이리스트 불러오기]` (확인 팝업 동일).
  - 불러오기 확정 시 플레이리스트 영상들의 **썸네일만** 추출해 목록에 채움.
- 목록 디자인: 이미지가 크게 보이도록 **반응형 그리드(카드)** 형식.
  - 카드 좌상단에 번호 배지, 본문은 정사각형 또는 4:3 썸네일.
  - 카드 드래그로 위치 변경.
  - 우클릭 메뉴: 수정, 삭제.
  - "수정" 팝업 상단에 `[유튜브 주소] / [이미지 주소]` 토글 버튼, 선택한 종류의 입력칸 하나만 표시.

### 저장 포맷: `/file/list/<음악퀴즈>.json`

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

### /op/datapack

- 상단 왼쪽에 `[돌아가기]` → `/op/dashboard`.
- 상단에 `[음악퀴즈 선택]` 버튼. 클릭 시 팝업에 `manifest.json` 의 음악퀴즈를 카드 목록으로 표시, 하나 선택.
- 선택 후: "총 N개의 음악을 찾았습니다." 텍스트 표시.
- 아래 `[데이터팩 출력]` 버튼.
  - 클릭 시 아래 코드 영역에 mcfunction 출력 + 복사 버튼 제공.
  - **출력 포맷(임시, 실제 포맷은 추후 확정 예정)**:

    ```mcfunction
    # === musicquiz: <pack name> ===
    # 총 N곡
    say [musicquiz] 데이터팩 초기화
    # 곡별 placeholder. 실제 포맷 확정되면 교체 예정.
    # 1. <title> - <artist> (<duration>s)
    # 2. ...
    ```