# 마인크래프트 음악퀴즈 간편설치기 + 관리 사이트 개발 명세서 ## 프로젝트 개요 마인크래프트 음악퀴즈를 `.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 ```