minecraft_launcher/docs/installer.md

음악퀴즈 간편설치기 사용 가이드

%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-25) → C:\Program Files\Java 순으로 자동 탐색.
• 최신 마인크래프트 서버는 Java 25 이상을 요구합니다(예: 서버 번들러 class file 69.0). 그보다 낮은 자바(17/21 등)는 있어도 UnsupportedClassVersionError 로 서버가 뜨지 않으므로, 자동 탐색은 Java 25 미만을 "없음"으로 처리해 자동 설치로 유도합니다.
• 자동 설치 버튼을 누르면 Adoptium Temurin 25 LTS Windows x64 zip 을 받아 %APPDATA%\jdk\temurin-25\ 에 풀어 사용합니다.
• 설치 중 같은 버튼이 "설치 취소" 로 바뀌고, 누르면 다운로드를 즉시 중단하고 부분 파일을 정리합니다.
• 서버 zip 의 run.bat 이 시스템 PATH 의 java 를 그대로 쓰면 낡은 자바로 실행돼 실패할 수 있어, 설치기가 준비/선택한 JDK 의 java 를 쓰도록 run.bat 을 자동으로 수정합니다(자동 설치 JDK 는 %APPDATA% 전개형 경로라 한글 사용자명에도 안전).

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 에 남은 프로필은 마인크래프트 런처에서 직접 지우거나, 다른 음악퀴즈를 재설치하면 같은 이름이 갱신됩니다.