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 확인

- 각 음악퀴즈(pack)는 사이트 편집기에서 **권장 JDK 버전**(예: Java 25)을 지정합니다. 편집기 목록은 Adoptium(Temurin)에서 실제 배포되는 버전을 불러오며, "자세히 보기"로 비-LTS·스냅샷까지 확인할 수 있습니다. 설치기는 이 권장 버전을 기준으로 동작합니다.
- 탐색 순서:
  1. **설치기 자동 설치 위치 `%APPDATA%\.mc_custom\jdk`**(구버전 `%APPDATA%\jdk` 호환)에 JDK 가 있으면 **가장 먼저 사용**합니다(권장 버전이면 그대로, 혹시 다른 버전이면 경고).
  2. 없으면 **환경변수(`JAVA_HOME` / `JDK_HOME`)** 의 JDK 가 **권장 버전이면** 사용합니다.
  3. 그래도 없으면 **기본 폴더 `C:\Program Files\Java`** 에서 **권장 버전**을 찾아 사용합니다.
  4. 권장 버전을 어디서도 못 찾으면 **환경변수 자바(없으면 Program Files 자바)로 폴백**하고, "권장 버전과 달라 서버가 정상 실행되지 않을 수 있다"는 **경고**를 띄웁니다.
- 직접 선택/입력한 경로도 "다음" 에서 검증해, 권장과 다르면 경고 후 동의(확인) 시에만 진행합니다(무조건 차단이 아니라 경고+동의). 아무 JDK 도 없으면 자동 설치로 유도합니다.
- **자동 설치** 버튼을 누르면 Adoptium Temurin(권장 버전) Windows x64 zip 을 받아 **`%APPDATA%\.mc_custom\jdk\temurin-<권장>\`** 에 풀어 사용합니다. (`.mc_custom` 안에 두므로 "음악퀴즈 파일제거" 도구로 한 번에 정리됩니다. `MC_CUSTOM_DIR` 로 폴더명을 바꾼 경우 그 폴더 아래 `jdk`.)
- 설치 중 같은 버튼이 "설치 취소" 로 바뀌고, 누르면 다운로드를 즉시 중단하고 부분 파일을 정리합니다.
- 서버 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` → fabric-installer(자바 필요) 를 돌리지 않고, fabric meta 에서 버전 프로필 JSON 을 직접 받아 `.minecraft\versions\fabric-loader-Y-X\fabric-loader-Y-X.json` 으로 저장한다(`https://meta.fabricmc.net/v2/versions/loader/<mc>/<loader>/profile/json`). 자바가 없어도 되므로 "spawn java ENOENT" 나 바닐라 선행 실행이 필요 없다. 라이브러리는 프로필 JSON 에 적힌 maven url 을 보고 런처가 실행 시 자동으로 받는다. (fabric 버전/라이브러리는 런처 폴더 `.minecraft` 에 있어야 런처가 찾으며, `.mc_custom` 에 두면 "Unable to prepare assets for download" 로 실패한다.)
   - `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` 에 남은 프로필은 마인크래프트 런처에서 직접 지우거나, 다른 음악퀴즈를 재설치하면 같은 이름이 갱신됩니다.