claude-bot
894a86a117
- README.md 를 개발 명세에서 프로젝트 개요/구성/빠른 시작 형식으로 재작성 - docs/installer.md (음악퀴즈 간편설치기 단계별 사용 가이드) 신설 - docs/admin-site.md (관리 사이트 운영자 가이드) 신설 - docs/resourcepack-installer.md (리소스팩 간편설치기 동작 명세) 신설 - 중복된 docs/add.md 제거 (resourcepack-installer.md 로 이전)
106 lines
6.4 KiB
Markdown
106 lines
6.4 KiB
Markdown
# 음악퀴즈 간편설치기 사용 가이드
|
|
|
|
`%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` 에 남은 프로필은 마인크래프트 런처에서 직접 지우거나, 다른 음악퀴즈를 재설치하면 같은 이름이 갱신됩니다.
|