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

{
  "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 출력 + 복사 버튼 제공.

  • 출력 포맷(임시, 실제 포맷은 추후 확정 예정):

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