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

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

• 관리 사이트 — 음악퀴즈 정보(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 에 둡니다. 그중 assets / libraries / versions 세 폴더만 .mc_custom 에 junction 링크하고(게임이 gameDir 기준으로 찾아도 되도록), runtime(JRE)은 링크하지 않고 런처가 .minecraft\runtime 에서 직접 씁니다. 게임 데이터(모드/세이브/리소스팩)만 .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).

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

---

간편설치기 동작 요약

• JDK(서버용) — 탐색 순서: ① .mc_custom\jdk(설치기 자동 설치분)에 JDK 가 있으면 먼저 사용 → ② 없으면 환경변수(JAVA_HOME/JDK_HOME)의 JDK 가 권장 버전(recommendedJdk) 이면 사용 → ③ 그래도 없으면 C:\Program Files\Java 에서 권장 버전을 찾아 사용. 권장 버전을 어디서도 못 찾으면 환경변수 자바(없으면 Program Files 자바)로 폴백하고 "권장과 다름" 경고를 띄웁니다. 아무 JDK 도 없으면 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 서명·아이콘 도구가 필요합니다.

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

---

데이터 포맷 (요약)

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

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

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

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

/manifest/<key>.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 — 음악·사진 목록 (리소스팩 설치기용)

{
  "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            관리자 계정 시드/레거시(추적됨). 실제 운영 계정은 아래 우선
├─ account.local.json      실제 운영 계정(해시 비밀번호, .gitignore, 0600). 없으면 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).

---

라이선스

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