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

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

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

---

핵심 컨셉

설치기는 사용자의 %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 으로 지정

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

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

---

빠른 시작

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

{
  "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
│  ├─ platforms/           Forge / NeoForge 설치 jar
│  └─ list/<key>.json      음악·사진 목록
├─ docs/                   사용·운영 문서
├─ manifest.json           사이트 루트 매니페스트 (자동 관리)
├─ 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).

---

라이선스

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