docs: README/docs 재정리 — 프로젝트 개요·사용방법 정리

- README.md 를 개발 명세에서 프로젝트 개요/구성/빠른 시작 형식으로 재작성 - docs/installer.md (음악퀴즈 간편설치기 단계별 사용 가이드) 신설 - docs/admin-site.md (관리 사이트 운영자 가이드) 신설 - docs/resourcepack-installer.md (리소스팩 간편설치기 동작 명세) 신설 - 중복된 docs/add.md 제거 (resourcepack-installer.md 로 이전)
2026-05-13 02:44:39 +09:00
parent 475bf924a0
commit 894a86a117
5 changed files with 440 additions and 458 deletions
--- a/docs/add.md
+++ b/docs/add.md
@@ -1,144 +0,0 @@
-# 추가사항: 음악퀴즈 리소스팩 간편설치기(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. ...
-    ```
--- a/docs/admin-site.md
+++ b/docs/admin-site.md
@@ -0,0 +1,119 @@
+# 관리 사이트 운영 가이드
+
+음악퀴즈 정의(`/manifest/*.json`), 음악·사진 목록(`/file/list/*.json`), 데이터팩 출력을 한 곳에서 관리하는 Express + EJS 사이트입니다.
+
+## 실행
+
+```bash
+npm install
+npm start         # 기본 포트 3000. 환경변수로 PORT 조정 가능.
+```
+
+배포 시에는 시스템 서비스(systemd 등) 로 등록해 두면 됩니다.
+
+## 도메인 / 경로 구성
+
+| 경로 | 내용 |
+| --- | --- |
+| `/` | 음악퀴즈 카드 한 줄 목록(공개). 카드 클릭 시 해당 음악퀴즈 페이지. |
+| `/manifest.json` | 사이트 루트 매니페스트(공개). 설치기가 첫 화면에서 로드. |
+| `/file/...` | 정적 파일 호스팅. `servers/`, `maps/`, `mods/<폴더>/`, `resourcepacks/`, `platforms/`, `list/`. |
+| `/op` | 관리자 로그인. 미들웨어로 `/op/*` 전체를 보호. |
+| `/op/dashboard` | 음악퀴즈 카드 목록 + 추가/삭제 + 편집 진입. |
+| `/op/dashboard/:packKey` | 음악퀴즈 정의(JSON) 편집기. |
+| `/op/list` | 카드 목록(음악·사진 편집 진입). |
+| `/op/list/:packKey` | 음악퀴즈의 음악·사진 목록 편집(드래그/우클릭). |
+| `/op/datapack` | 데이터팩 mcfunction 출력. |
+| `/op/datapack/:packKey/generate` | 텍스트 한 덩어리로 mcfunction 반환. |
+
+## 계정
+
+`account.json` 에 정의합니다(루트 디렉터리). **외부 HTTP 로 절대 노출되지 않도록 라우팅에서 제외돼 있습니다.**
+
+```json
+[
+  { "id": "admin", "password": "비번" }
+]
+```
+
+> 운영 환경에서는 평문 비밀번호 대신 해시를 쓰도록 추후 보강할 여지가 있습니다.
+
+## 대시보드 (`/op/dashboard`)
+
+- 상단 메뉴: 좌측 로고 = 대시보드로 이동, 우측 아이디 드롭다운에 **로그아웃**.
+- 상단 버튼: `[음악목록 수정]` → `/op/list`, `[데이터팩 수정]` → `/op/datapack`.
+- 카드 목록: `manifest.json` 의 음악퀴즈를 가로 한 줄 카드로 표시.
+- **음악퀴즈 추가** — `/manifest/new.json` 생성. 이미 있으면 `new2.json`, `new3.json` … 으로 증가. 동시에 `manifest.json` 갱신.
+- **음악퀴즈 삭제** — 카드에 체크박스가 뜨고, 확인 시 선택한 JSON 과 매니페스트 항목을 삭제.
+
+## 음악퀴즈 정의 편집 (`/op/dashboard/:packKey`)
+
+폼 필드:
+
+| 필드 | 설명 |
+| --- | --- |
+| 음악퀴즈 이름 | 사용자에게 보이는 표시명. |
+| JSON 파일 이름 | URL 키. 영문/숫자/`_`/`-` 만 허용. 변경 시 파일명 + 매니페스트가 동시에 갱신되며 URL 도 새 키로 리다이렉트. |
+| 마인크래프트 버전 | Mojang 공식 API 에서 정식 릴리즈만 드롭다운으로 표시. |
+| 모드 플랫폼 | `vanilla` / `forge` / `fabric` / `neoforge`. |
+| 플랫폼 설치파일 URL | `forge` / `neoforge` 용. 도메인 없이 입력하면 `/file/platforms/<파일명>` 으로 해석. |
+| Fabric Loader 버전 | `fabric` 선택 시 자동 표시. Fabric Meta API 에서 선택한 mcVersion 의 로더 목록을 가져옴. 설치기는 최신 fabric-installer 로 CLI 자동 설치. |
+| 서버 최소/최대 램 (MB) | 설치기 RAM 검사 및 `run.bat` 의 `-Xms/-Xmx`. |
+| 클라이언트 최소/권장 램 (MB) | 사용자 PC 요구치 + 마인크래프트 런처 JVM 인수에 사용. |
+| 맵 파일 (.zip) | `/file/maps/` 아래 zip 파일명. `.mc_custom/saves/` 로 압축 해제. |
+| 서버 파일 (.zip) | `/file/servers/` 아래 zip. 멀티 전용. |
+| 모드 폴더 이름 | `/file/mods/<폴더>/` 아래 모든 `.jar` 자동 다운로드. 빈 값이면 받지 않음. |
+| 리소스팩 (.zip) | `/file/resourcepacks/` 아래 zip 파일명. |
+
+저장 시 `clientMinRam ≤ clientRecommendedRam` 검증이 들어갑니다.
+
+## 음악·사진 목록 편집 (`/op/list/:packKey`)
+
+상단 탭: **음악목록** / **사진목록**.
+
+### 음악목록 탭
+
+- `[목록 저장]`, `[목록 초기화]`.
+- 플레이리스트 주소 + `[플레이리스트 불러오기]`. 확인 팝업에서 동의해야 기존 순서를 덮어씀.
+- 항목 표시: 좌측 번호 배지, 썸네일, 제목 / 가수 / 길이.
+- 드래그로 순서 변경. 우클릭: **수정** / **삭제**.
+- **수정** → 새 유튜브 주소를 입력하면 yt-dlp 가 메타데이터를 가져와 자동 채움.
+
+### 사진목록 탭
+
+- `[목록 저장]`, `[목록 초기화]`, 플레이리스트 불러오기는 동일.
+- 카드 그리드(반응형) 로 표시. 우클릭에서 수정/삭제. 수정 팝업은 [유튜브 주소] / [이미지 주소] 토글.
+
+저장 포맷은 `/file/list/<packKey>.json` (README 데이터 포맷 참고).
+
+> yt-dlp 메타데이터/플레이리스트 조회를 위해 서버에 yt-dlp 가 설치되어 있어야 합니다. ([`yt-dlp-setup.md`](yt-dlp-setup.md))
+
+## 데이터팩 (`/op/datapack`)
+
+- `[음악퀴즈 선택]` → 팝업에서 음악퀴즈 선택.
+- "총 N개의 음악을 찾았습니다." 와 `[데이터팩 출력]` 버튼.
+- 출력 클릭 시 코드 영역에 mcfunction(임시 포맷) + 복사 버튼. 실제 포맷은 추후 확정.
+
+```
+# === musicquiz: <pack name> ===
+# 총 N곡 / 사진 M장
+say [musicquiz] 데이터팩 초기화
+# 곡별 placeholder. 실제 포맷 확정되면 교체 예정.
+# 1. <title> - <artist> (<duration>s)
+```
+
+## 파일 업로드 / 정리 운영
+
+| 카테고리 | 위치 | 비고 |
+| --- | --- | --- |
+| 서버 zip | `file/servers/<이름>.zip` | EULA / `run.bat` 포함 권장. 설치기가 `run.bat` 에 UPnP/JVM 후처리 자동 주입. |
+| 맵 zip | `file/maps/<이름>.zip` | 압축 해제 시 `.mc_custom/saves/` 아래에 풀림. |
+| 모드 jar | `file/mods/<폴더>/...jar` | 해당 폴더의 `index.json` 이 자동 생성됩니다. 신규 jar 를 넣은 뒤에는 사이트가 인덱스를 다시 만들도록 한 번 호출. |
+| 리소스팩 zip | `file/resourcepacks/<이름>.zip` | — |
+| 플랫폼 설치 jar | `file/platforms/<이름>.jar` | forge/neoforge 용. fabric 은 사이트에 둘 필요 없음(자동 다운로드). |
+
+## 보안 주의
+
+- `account.json` 은 라우팅에서 차단되어 있으나, 디스크 권한도 운영자만 접근 가능하게 두는 것이 안전합니다.
+- 관리자 비밀번호는 충분히 강하게 설정.
+- 모든 `/op/*` 라우트는 세션 기반 인증 미들웨어를 거칩니다. 세션 만료 시 자동으로 로그인 페이지로 리다이렉트.
--- a/docs/installer.md
+++ b/docs/installer.md
@@ -0,0 +1,105 @@
+# 음악퀴즈 간편설치기 사용 가이드
+
+`%APPDATA%\.mc_custom\` 을 게임 디렉터리로 쓰는 별도 인스턴스를 자동으로 구축합니다. 평소 쓰던 `.minecraft` 는 그대로 유지되며, 음악퀴즈 모드/리소스팩/맵/서버만 분리된 폴더에 자동 설치됩니다.
+
+설치기는 단계별 화면으로 진행됩니다. 단계 사이에는 "이전 / 다음" 버튼이 있고, 일부 단계는 페이지 진입 시 자동으로 작업을 시작합니다.
+
+---
+
+## 1단계 — 음악퀴즈 선택
+
+`manifest.json` 을 읽어 등록된 음악퀴즈를 카드 한 줄로 표시합니다. 하나를 선택하면 다음 단계로 진행됩니다.
+
+> manifest URL 은 기본값이 박혀 있지만, 다른 호스트의 음악퀴즈를 받고 싶다면 첫 화면 상단의 URL 입력란에 붙여 넣고 새로고침 버튼을 누르면 됩니다.
+
+## 2단계 — 싱글 / 멀티 선택
+
+| 선택 | 흐름 |
+| --- | --- |
+| **싱글** | 3단계(서버 설치)를 건너뛰고 곧장 4단계로 진행. |
+| **멀티** | 3단계의 5개 소항목을 거친 뒤 4단계로 진행. |
+
+## 3단계 — 서버 관련 설정 (멀티 전용)
+
+### 3-1. 서버 설치 경로
+
+- 폴더 선택 또는 직접 입력.
+- **경로에 한글이 있으면 안 됩니다.** (마인크래프트 서버가 비정상 동작)
+
+### 3-2. JDK 확인
+
+- 환경변수(`JAVA_HOME`, `JDK_HOME`) → 자동 설치 위치(`%APPDATA%\jdk\temurin-21`) → `C:\Program Files\Java` 순으로 자동 탐색.
+- **자동 설치** 버튼을 누르면 Adoptium Temurin 21 LTS Windows x64 zip 을 받아 `%APPDATA%\jdk\temurin-21\` 에 풀어 사용합니다.
+- 설치 중 같은 버튼이 "설치 취소" 로 바뀌고, 누르면 다운로드를 즉시 중단하고 부분 파일을 정리합니다.
+
+### 3-3. 서버 다운로드 및 설치
+
+페이지 진입 즉시 음악퀴즈의 `serverPath` 에 지정된 서버 zip 을 다운로드해 압축을 풉니다. 압축 해제 직후 `run.bat` 에 다음 처리를 자동 주입합니다:
+
+- **UPnP 자동 등록/해제**: 서버 시작 직전 `server-port` 를 읽어 PowerShell COM (`HNetCfg.NATUPnP.1`) 으로 TCP 매핑 추가, 종료 후 해제.
+- 설치 끝나면 EULA 동의 화면이 표시되고, 동의해야 다음으로 넘어갑니다. 이어서 시스템 RAM 검사가 자동 실행됩니다.
+
+램 검사 규칙:
+
+```
+시스템 RAM ≥ serverMaxRam   → 서버 RAM = serverMaxRam
+시스템 RAM ≥ serverMinRam   → 서버 RAM = serverMinRam (경고 표시)
+시스템 RAM <  serverMinRam  → "플레이 불가" 후 설치 중단
+```
+
+### 3-4. 서버 설정 (편집기)
+
+내장 로컬 웹서버를 띄워 브라우저에서 `server.properties`, `bukkit.yml`, `paper-global.yml` 등 주요 설정 파일을 GUI 로 편집합니다. 저장 누르면 실제 파일에 반영됩니다.
+
+### 3-5. 서버 포트포워딩 점검
+
+페이지 진입 시 자동으로 검사합니다. 흐름:
+
+1. 이전 실행에서 만든 UPnP 매핑이 남아 있으면 먼저 제거.
+2. 외부 포트체크 서비스(`ifconfig.co`) 로 1차 점검. 임시 TCP 리스너를 띄워 외부에서 닿는지 확인.
+3. 이미 사용자가 라우터 규칙으로 포워딩 해 두었으면 → "포워딩 됨" 으로 통과.
+4. 아니면 UPnP 로 자동 개방 시도 후 재점검. 성공 시 테스트용 매핑은 즉시 제거(실제 개방은 `run.bat` 이 서버 기동 때마다 처리).
+5. UPnP 도 실패하면 안내 메시지 (사용자가 라우터에서 수동 포워딩) 표시.
+
+> 동일 페이지에 **재점검** 버튼이 있어, 라우터 설정을 바꾼 뒤 다시 누르면 1차부터 다시 검사합니다.
+
+## 4단계 — 유저 클라이언트 설정 (자동 진행)
+
+페이지 진입 즉시 시작합니다.
+
+1. `.mc_custom` 폴더 생성 + `mods/`, `resourcepacks/` 생성.
+2. `.minecraft` 최상위 설정 파일(`options.txt`, `optionsof.txt`, `servers.dat`, `usercache.json`, …) 을 `.mc_custom` 으로 복사. 이미 같은 이름이 있으면 보존.
+3. 플랫폼 설치:
+   - `vanilla` → 건너뜀.
+   - `fabric` → Adoptium 자동 설치 → 최신 fabric-installer.jar 다운로드 → `java -jar fabric-installer.jar client -mcversion X -loader Y -dir .mc_custom -noprofile` 자동 실행.
+   - `forge` / `neoforge` → `platform.downloadUrl` 의 설치 jar 다운로드(사용자가 직접 실행하거나 마인크래프트 런처가 인식).
+4. `modsFolder` 의 모든 `.jar` 와 `resourcepackPath` zip, `mapPath` zip 을 자동 다운로드.
+5. `.minecraft\{assets,libraries,versions}` 를 `.mc_custom\{assets,libraries,versions}` 로 junction 링크. (없으면 "Unable to prepare assets for download" 오류로 마인크래프트가 실패하기 때문)
+6. `.minecraft\launcher_profiles.json` 에 해당 음악퀴즈 이름의 프로필을 추가/갱신:
+   - `gameDir` = `%APPDATA%\.mc_custom`
+   - `lastVersionId` = `vanilla` → `mcVersion`, `fabric` → `fabric-loader-<loaderVer>-<mcVer>` (forge/neoforge 는 `versions/` 폴더에서 휴리스틱 매칭)
+   - `javaArgs` = `-Xmx<serverMaxRam>M` + Aikar 권장 G1 GC 플래그 6종 (`-XX:+UnlockExperimentalVMOptions -XX:+UseG1GC -XX:G1NewSizePercent=20 -XX:G1ReservePercent=20 -XX:MaxGCPauseMillis=50 -XX:G1HeapRegionSize=32M`). 기존에 사용자가 지정한 키는 덮어쓰지 않음.
+
+## 5단계 — 완료
+
+- 멀티 설치까지 거친 경우:
+  - **서버 폴더 열기**
+  - **바탕화면에 서버 실행 바로가기 만들기**
+  - **서버 바로 실행**
+- **마인크래프트 런처 실행** — 실행 우선순위:
+  1. Win32 설치판 (`Program Files\Minecraft Launcher\MinecraftLauncher.exe` 등)
+  2. App Execution Alias (`%LOCALAPPDATA%\Microsoft\WindowsApps\Minecraft.exe` 등, `cmd /c start` 경유)
+  3. `explorer.exe shell:AppsFolder\Microsoft.4297127D64EC6_8wekyb3d8bbwe!Minecraft` (MS Store MSIX)
+  4. 마지막 수단: `minecraft://` URL 스킴
+
+런처가 떴다면 음악퀴즈 이름의 프로필을 선택해 플레이하면 됩니다.
+
+---
+
+## 로그
+
+설치기 화면 하단에 실시간 로그가 표시됩니다. 모든 다운로드/링크/JVM 인수 갱신/UPnP 시도 내역이 기록됩니다. 문제가 생기면 이 로그 내용을 캡처해 함께 전달해 주세요.
+
+## 음악퀴즈 제거
+
+`%APPDATA%\.mc_custom\` 폴더를 통째로 삭제하면 인스턴스가 사라집니다. `.minecraft\launcher_profiles.json` 에 남은 프로필은 마인크래프트 런처에서 직접 지우거나, 다른 음악퀴즈를 재설치하면 같은 이름이 갱신됩니다.
--- a/docs/resourcepack-installer.md
+++ b/docs/resourcepack-installer.md
@@ -0,0 +1,69 @@
+# 리소스팩 간편설치기
+
+음악퀴즈에 등록된 음악·사진 목록을 yt-dlp 로 받아 마인크래프트 1.21+ painting variant 텍스처 리소스팩으로 패키징하는 별도 설치기입니다.
+
+기본 골격은 음악퀴즈 간편설치기(`src/installer/`)와 동일하므로 UI/스토어 코드를 공유합니다. 진입점은 `src/installer-rp/main.ts` + `installer-rp/` 렌더러.
+
+## 실행
+
+```bash
+npm run installer:rp        # 개발 실행
+```
+
+윈도우 `.exe` 패키징은 `tsconfig.installer-rp.json` 으로 컴파일한 뒤 `electron-builder` 로 수동 패키징합니다.
+
+## 단계
+
+번호가 붙은 단계는 "이전 / 다음" 으로 이동 가능합니다.
+
+### 1) 음악퀴즈 선택
+
+- 도메인의 `manifest.json` 에서 음악퀴즈 카드 목록을 표시.
+- 선택한 음악퀴즈의 `file/list/<key>.json` 에서 다음을 로드:
+  - 음악 목록(유튜브 영상 주소).
+  - 사진 목록(유튜브 주소 또는 일반 이미지 주소).
+
+### 2) 리소스팩 설치 (자동 시작)
+
+- "다음" 누르면 즉시 시작.
+- 설치 로그를 실시간으로 표시(곡 제목 노출 없이 `n번 노래 다운로드 중…` 형식).
+- 취소 버튼 / 창 닫기 / 강제 종료 시: 진행 중 다운로드를 안전하게 중단하고 임시 파일을 정리한 뒤 정상 종료.
+
+#### 2-1. yt-dlp 준비
+
+- 자동 설치 위치: `%APPDATA%/.mc_custom/` (Linux `~/.config/.mc_custom/`, macOS `~/Library/Application Support/.mc_custom/`).
+- 이미 있으면 업데이트 확인 후 그대로 사용.
+- 시스템 `PATH` 에 `yt-dlp` 가 있으면 그것을 우선 사용 후 업데이트 확인.
+- 자동 설치가 실패하는 환경은 [`yt-dlp-setup.md`](yt-dlp-setup.md) 참고.
+
+#### 2-2. 음악 다운로드 (순차)
+
+- 임시 경로: `%APPDATA%/.mc_custom/.temp/`.
+- 각 곡을 `ogg` 로 변환(Minecraft 사운드 호환 포맷). ffmpeg 필요.
+- 중단되거나 모두 끝나면 `.temp` 내용 삭제.
+
+#### 2-3. 사진 다운로드 → painting variant 텍스처
+
+이미지는 두 형태로 들어옵니다.
+
+- **유튜브 주소** — yt-dlp 가 알려준 영상 ID 로 `https://i.ytimg.com/vi/<id>/maxresdefault.jpg` 1차 시도, 실패하면 `hqdefault.jpg` 폴백.
+- **일반 이미지 주소** — HTTP GET 으로 그대로.
+
+정규화 규칙:
+
+- **슬롯 규격(고정, 데이터팩 측)**: `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 으로 배치.
+
+painting variant 의 슬롯·태그 구조와 게임 내 호출 예시는 [`painting-variant.md`](painting-variant.md) 참고.
+
+### 3) 설치 완료
+
+- "확인" 누르면 프로그램 종료.