diff --git a/README.md b/README.md index f17c718..50acda7 100644 --- a/README.md +++ b/README.md @@ -1 +1,356 @@ -# Minecraft Server Pack Easy Installer +# 마인크래프트 음악퀴즈 간편설치기 + 관리 사이트 개발 명세서 + +## 프로젝트 개요 + +마인크래프트 음악퀴즈를 `.exe` 하나로 간편하게 설치할 수 있는 설치기와, 음악퀴즈 정보를 관리하는 웹사이트를 개발한다. + +### 핵심 컨셉 +- 이 프로젝트는 `%appdata%\.mc_custom` 폴더를 생성하여 모드 적용 및 서버 실행을 독립적으로 관리한다. +- 음악퀴즈 정보는 **`manifest.json`** 으로 중앙 관리한다. + +### .mc_custom 폴더 구조 + +``` +%appdata%\.mc_custom\ +├── mods/ ← 모드 (.jar) 저장 및 자동 적용 +├── resourcepacks/ ← 리소스팩 (.zip) 저장 및 자동 적용 +├── saves/ ← 월드 저장 +├── config/ ← 모드 설정 파일 +├── screenshots/ ← 스크린샷 +└── options.txt ← 게임 설정 +``` + +- 마인크래프트 런처 프로필의 `gameDir`을 `%appdata%\.mc_custom`으로 설정하면, 마인크래프트가 이 폴더를 기준으로 모든 파일을 읽고 저장한다. +- 버전 파일과 assets는 기존 `%appdata%\.minecraft`를 그대로 사용한다. + +--- + +## 파트 1. 간편설치기 (`.exe`) + +> 설치기는 아래 단계를 순서대로 페이지 단위로 진행한다. 각 번호 = 1페이지. + +### 1단계: 음악퀴즈 선택 + +- 음악퀴즈사이트(아래 파트 2 참고)에서 `manifest.json`을 가져와 등록된 음악퀴즈 목록을 표시한다. +- 사용자가 설치할 음악퀴즈를 선택한다. + +--- + +### 2단계: 싱글 / 멀티 선택 + +- 싱글 또는 멀티 중 하나를 선택하는 화면을 표시한다. +- **멀티 선택 시**: 3단계(서버 설치)를 거친 후 4단계로 진행한다. +- **싱글 선택 시**: 3단계를 건너뛰고 4단계로 바로 진행한다. + +--- + +### 3단계: 서버 관련 설정 + +- 2단계에서 **멀티**를 선택한 경우에만 진입한다. 싱글 선택 시 이 단계 전체를 건너뛴다. +- 3단계의 각 소항목(3-1 ~ 3-5)은 완료되어도 자동으로 다음으로 넘어가지 않으며, 사용자가 **확인 버튼**을 눌러야 다음 소항목으로 진행된다. + +#### 3-1. 서버 설치 경로 설정 + +- 서버를 생성할 폴더 경로를 사용자가 직접 지정한다. +- **경로에 한글이 포함되면 안 된다.** 한글 포함 시 경고 메시지를 표시하고 다음 단계로 진행 불가. + +#### 3-2. JDK 확인 / 설치 + +- 폴더 선택 UI로 JDK 경로를 지정할 수 있다. +- JDK 자동 탐색 우선순위: + 1. 시스템 환경변수 (`JAVA_HOME` 등) + 2. 로컬 환경변수 + 3. `C:\Program Files\Java` (JDK 기본 설치 경로) +- 위 경로에서 JDK가 발견되면 해당 경로를 기본값으로 자동 설정한다. +- JDK가 없으면 설치를 안내한다. + +#### 3-3. 서버 다운로드 및 설치 +- 처음 파일 다운로드는 자동으로 시작 + +##### 3-3-1. 파일 다운로드 +- JSON의 `packPath` 필드 값을 `도메인/file/` 뒤에 붙여 서버 파일 다운로드 URL을 구성한다. + - 예: `packPath`가 `music-quiz/files`이면 → `도메인/file/music-quiz/files` + - 해당 경로의 모든 파일을 순서대로 다운로드한다. + +##### 3-3-2. 설치 로그 +- 다른 프로그램 설치 화면처럼 실시간 로그를 표시하는 로그 뷰어를 제공한다. + +##### 3-3-3. EULA 동의 +- 설치 중간에 Minecraft EULA 동의 화면을 표시하고, 사용자가 직접 동의해야 다음 단계로 진행된다. +- 음악퀴즈 내에 `eula.txt`가 포함되어 있으면 **삭제하고** 새로 동의를 받는다. + +##### 3-3-4. 램 검사 로직 + +> 아래 기준은 모두 JSON의 서버 램 필드(`serverMinRam`, `serverMaxRam`)를 사용한다. + +``` +유저 시스템 램 >= serverMaxRam → serverMaxRam으로 설정 +유저 시스템 램 >= serverMinRam → serverMinRam으로 설정 (경고 메시지 표시) +유저 시스템 램 < serverMinRam → "플레이 불가" 메시지 출력 후 설치 중단 +``` + +- 서버 실행 시 `-Xmx`에 `serverMaxRam`, `-Xms`에 `serverMinRam` 값을 JVM 인자로 사용한다. + +#### 3-4. 서버 설정 + +- **로컬 웹서버**를 띄워 브라우저에서 서버 설정 파일을 GUI로 편집할 수 있게 한다. +- 메모장으로 수정해야 했던 파일들을 설명과 함께 편리하게 수정 가능: + - `bukkit.yml` + - `server.properties` + - 기타 설정 파일 +- 수정 후 "적용" 버튼으로 실제 파일에 반영한다. + +#### 3-5. 서버 포트포워딩 설정 + +1. **이미 포트포워딩 되어 있는 경우** (UPnP 포함): 외부 접속 주소를 화면에 표시하고 다음 단계로 진행. +2. **포트포워딩 안 된 경우 → UPnP 시도**: + - UPnP로 포트 개방 가능 여부 확인 + - 가능하면 자동으로 개방 후 외부 접속 테스트 + - 접속 확인되면 다음 단계로 진행 가능 +3. **UPnP 불가 시**: "직접 포트포워딩을 해주세요." 메시지를 안내와 함께 표시. + +--- + +### 4단계: 유저 클라이언트 설정 +- 음악퀴즈 JSON 파일에 명시된 클라이언트 설정을 기반으로 설치한다. + +#### 4-1. 모드 플랫폼 설치 +- JSON 파일의 `platform.type`에 명시된 플랫폼 이름을 화면에 표시하고, **설치** / **건너뛰기** 버튼으로 사용자가 직접 선택한다. + - `vanilla`가 아닌 경우: `platform.downloadUrl`을 기반으로 다운로드 후 설치한다. + - **건너뛰기** 선택 시: 플랫폼 설치 없이 바닐라로 진행한다. + +#### 4-2. 설치설정 설정 +- `%appdata%\.minecraft\launcher_profiles.json`에 프로필을 추가한다. + - 이미 동일한 이름의 프로필이 있으면 새로 만들지 않고 기존 프로필을 수정한다. +- **`gameDir`을 `%appdata%\.mc_custom`으로 설정한다.** + - 이 설정으로 인해 모드, 리소스팩, 세이브 등 모든 파일이 `.mc_custom` 기준으로 읽히고 저장된다. +- 램 설정(`javaArgs`)을 JSON의 서버 램 필드 기준으로 적용한다. + - `-Xmx`에 `serverMaxRam`, `-Xms`에 `serverMinRam` 값을 사용한다. +- 플랫폼(Forge 등) 설치 버전을 `lastVersionId`로 설정한다. + +```json +// launcher_profiles.json 프로필 예시 +{ + "음악퀴즈": { + "name": "음악퀴즈", + "type": "custom", + "gameDir": "%appdata%\\.mc_custom", + "lastVersionId": "1.20.1-forge-47.2.0", + "javaArgs": "-Xmx4G -Xms2G" + } +} +``` + +#### 4-3. 모드 및 리소스팩 설치 +- JSON 파일에 명시된 모드와 리소스팩을 다운로드하여 `.mc_custom` 하위 폴더에 저장한다. +- 다운로드 진행 상황을 실시간 로그 뷰어로 표시한다. (다른 프로그램 설치 화면과 동일한 형태) + +| 파일 종류 | 저장 경로 | +|-----------|-----------| +| 모드 (`.jar`) | `%appdata%\.mc_custom\mods\` | +| 리소스팩 (`.zip`) | `%appdata%\.mc_custom\resourcepacks\` | + +- 이미 동일한 파일명이 존재하면 덮어쓴다. +- 다운로드 완료 후 마인크래프트 실행 시 자동으로 적용된다. (별도 설정 불필요) + +--- + +### 5단계: 완료 페이지 + +- 멀티로 진행해서 서버도 설치했다면: + - **서버 폴더 열기** 버튼 + - **바탕화면에 서버 실행 바로가기 만들기** 토글 (기본값: ON) + - **서버 바로 실행** 토글 (기본값: ON) +- 마인크래프트 런처 실행 토글 (기본값: ON) + +--- + +## 파트 2. 음악퀴즈 관리 웹사이트 + +> **기술 스택: Node.js + TypeScript + Express + EJS** + +### 라우팅 구조 + +| 경로 | 설명 | +|------|------| +| `/` | 메인 페이지 (음악퀴즈 목록) | +| `/manifest.json` | manifest.json 파일 직접 접근 | +| `/file/` | 음악퀴즈 파일 제공 경로 | +| `/op` | 관리자 로그인 페이지 | +| `/op/dashboard` | 관리자 대시보드 | +| `/op/dashboard/:packName` | 음악퀴즈 JSON 편집 페이지 | + +--- + +### 메인 페이지 (`/`) + +- `manifest.json`에 등록된 음악퀴즈를 **가로 한 줄 목록(카드) 형식**으로 표시한다. + +--- + +### 관리자 인증 (`/op`) + +- `/op` 하위 모든 경로는 로그인 없이 접근 불가 (미들웨어로 처리). +- 로그인 화면: 아이디 + 비밀번호 입력. +- 계정 정보는 **`account.json`** 파일에 저장. + - `account.json`은 **서버 내부에서만 접근 가능**, 외부 HTTP 요청으로 절대 노출되지 않아야 함. +- 로그인 성공 시 `/op/dashboard`로 리다이렉트. + +#### account.json 예시 구조 +```json +[ + { + "id": "admin", + "password": "admin" + } +] +``` + +--- + +### 관리자 대시보드 (`/op/dashboard`) + +#### 공통 레이아웃 (메뉴바) +- **왼쪽**: 로고 + "관리자 페이지" 텍스트 → 클릭 시 `/op/dashboard`로 이동 +- **오른쪽**: 로그인한 아이디 표시 → 클릭 시 드롭다운 메뉴 표시 + - 드롭다운 항목: **로그아웃** 버튼 + +#### 음악퀴즈 목록 +- `/manifest` 폴더 안의 JSON 파일들을 가져와 **가로 한 줄 카드 형식**으로 표시. +- 카드 클릭 → `/op/dashboard/:packName` 으로 이동하여 JSON 편집 시작. + +#### 음악퀴즈 추가 버튼 +- `/manifest/` 폴더 안에 새 JSON 파일 생성. + - 기본 이름: `new.json` + - 이미 존재하면: `new2.json`, `new3.json` ... 순으로 증가. +- 생성과 동시에 `manifest.json`에도 자동 등록. + +#### 음악퀴즈 삭제 버튼 +- 버튼 클릭 시: + - 목록 카드에 **체크박스** 표시 + - 버튼 아래 **취소** / **확인** 버튼 표시 +- 확인 클릭 시 체크된 JSON 파일 삭제 + `manifest.json`에서도 자동 제거. + +--- + +### 음악퀴즈 편집 페이지 (`/op/dashboard/:packName`) + +- 해당 JSON 파일의 내용을 GUI 폼으로 편집한다. +- **JSON 파일 이름 변경** 기능 제공. + - 이름 변경 후 적용 클릭 시 현재 브라우저 URL의 `:packName` 부분도 자동 변경 (리다이렉트). + +--- + +## 파트 3. 음악퀴즈 JSON 구조 및 편집 항목 + +> `/manifest/*.json` 파일의 구조. 관리자 편집 페이지에서 아래 항목들을 GUI로 수정 가능. + +### JSON 필드 정의 + +| 필드명 | 타입 | 설명 | +|--------|------|------| +| `name` | `string` | 음악퀴즈 이름 | +| `mcVersion` | `string` | 마인크래프트 버전 (스냅샷 제외한 정식 릴리즈만) | +| `platform` | `object` | 모드 플랫폼 정보 (아래 참고) | +| `platform.type` | `string` | 플랫폼 종류 (`vanilla` / `forge` / `fabric` / `neoforge` 등) | +| `platform.downloadUrl` | `string` | 플랫폼 설치파일 다운로드 URL (바닐라면 생략) | +| `mods` | `array` | 설치할 모드 목록 (아래 참고) | +| `mods[].name` | `string` | 모드 이름 | +| `mods[].downloadUrl` | `string` | 모드 다운로드 URL | +| `resourcepacks` | `array` | 설치할 리소스팩 목록 | +| `resourcepacks[].name` | `string` | 리소스팩 이름 | +| `resourcepacks[].downloadUrl` | `string` | 리소스팩 다운로드 URL | +| `serverMinRam` | `number` | 서버 최소 램 (MB 단위) | +| `serverMaxRam` | `number` | 서버 최대 램 (MB 단위) | +| `clientMinRam` | `number` | 유저(클라이언트) 최소 램 (MB 단위) | +| `clientRecommendedRam` | `number` | 유저(클라이언트) 권장 램 (MB 단위) | +| `packPath` | `string` | 서버 파일 경로 (`/file/` 이후의 경로, 멀티 전용) | + +### JSON 예시 +```json +{ + "name": "음악퀴즈 v1", + "mcVersion": "1.20.1", + "platform": { + "type": "forge", + "downloadUrl": "https://example.com/forge-installer.jar" + }, + "mods": [ + { + "name": "ExampleMod", + "downloadUrl": "https://example.com/examplemod.jar" + } + ], + "resourcepacks": [ + { + "name": "ExampleResourcePack", + "downloadUrl": "https://example.com/resourcepack.zip" + } + ], + "serverMinRam": 2048, + "serverMaxRam": 8192, + "clientMinRam": 4096, + "clientRecommendedRam": 8192, + "packPath": "music-quiz/files" +} +``` + +### 편집 UI 항목별 비고 + +| 항목 | UI 형태 | 비고 | +|------|---------|------| +| `mcVersion` | 드롭다운 | Mojang API에서 정식 릴리즈만 가져와 표시, 스냅샷 제외 | +| `platform.type` | 드롭다운 | `vanilla` 선택 시 `downloadUrl` 입력란 숨김 | +| `mods` | 동적 목록 | 항목 추가 / 삭제 가능 | +| `resourcepacks` | 동적 목록 | 항목 추가 / 삭제 가능 | +| 램 관련 필드 | 숫자 입력 | MB 단위, `clientMinRam` ≤ `clientRecommendedRam` 유효성 검사 | +| `packPath` | 텍스트 입력 | `/file/` 이후 경로만 입력 | + +--- + +## 파트 4. manifest.json 구조 + +> 사이트 루트의 `manifest.json`. 설치기와 메인 페이지가 이 파일을 읽는다. + +```json +{ + "packs": [ + { + "name": "음악퀴즈 이름", + "file": "new" + } + ] +} +``` + +- `file`: `/manifest/` 폴더 안의 JSON 파일 이름 (확장자 제외). +- 음악퀴즈 추가/삭제 시 자동으로 이 파일도 업데이트된다. + +--- + +## 디렉토리 구조 (웹사이트) + +``` +project-root/ +├── manifest.json # 음악퀴즈 목록 (외부 접근 가능) +├── account.json # 관리자 계정 정보 (외부 접근 절대 불가) +├── /manifest/ # 음악퀴즈 JSON 파일 저장 폴더 +│ ├── new.json +│ └── music-quiz.json +├── /file/ # 서버 파일 제공 경로 (멀티 전용) +├── /src/ # TypeScript 소스 +│ ├── app.ts +│ ├── routes/ +│ │ ├── index.ts # 메인 페이지 +│ │ └── op.ts # 관리자 라우트 +│ └── middleware/ +│ └── auth.ts # /op 인증 미들웨어 +└── /views/ # EJS 템플릿 + ├── index.ejs + ├── op/ + │ ├── login.ejs + │ ├── dashboard.ejs + │ └── editor.ejs + └── partials/ + └── navbar.ejs +```