claude-bot
894a86a117
- README.md 를 개발 명세에서 프로젝트 개요/구성/빠른 시작 형식으로 재작성 - docs/installer.md (음악퀴즈 간편설치기 단계별 사용 가이드) 신설 - docs/admin-site.md (관리 사이트 운영자 가이드) 신설 - docs/resourcepack-installer.md (리소스팩 간편설치기 동작 명세) 신설 - 중복된 docs/add.md 제거 (resourcepack-installer.md 로 이전)
190 lines
7.5 KiB
Markdown
190 lines
7.5 KiB
Markdown
# 마인크래프트 음악퀴즈 통합 패키지
|
|
|
|
마인크래프트 음악퀴즈를 한 번에 배포·관리할 수 있도록 만든 통합 프로젝트입니다.
|
|
|
|
- **관리 사이트** — 음악퀴즈 정보(JSON)와 음악·사진 목록, 데이터팩 출력을 한 곳에서 운영.
|
|
- **음악퀴즈 간편설치기 (`.exe`)** — `manifest.json` 기반으로 사용자가 마인크래프트 본체·서버·모드를 자동 설치.
|
|
- **리소스팩 간편설치기 (`.exe`)** — 음악퀴즈 음악·표지를 yt-dlp 로 받아 painting variant 텍스처 리소스팩으로 패키징.
|
|
|
|
---
|
|
|
|
## 무엇이 들어 있나
|
|
|
|
| 디렉터리 | 역할 | 진입점 |
|
|
| --- | --- | --- |
|
|
| `src/server/` | 음악퀴즈 관리 웹사이트 (Express + EJS) | `bun start` 또는 `npm start` |
|
|
| `src/installer/` | 음악퀴즈 간편설치기 (Electron) | `npm run installer` |
|
|
| `src/installer-rp/` | 리소스팩 간편설치기 (Electron) | `npm run installer:rp` |
|
|
| `src/shared/` | 두 설치기와 서버가 공유하는 타입·스토어 | — |
|
|
| `views/` | EJS 템플릿 (관리 사이트) | — |
|
|
| `manifest/` | 음악퀴즈별 정의 JSON | — |
|
|
| `file/list/` | 음악퀴즈별 음악·사진 목록 JSON | — |
|
|
| `file/` | 정적 파일(서버 zip / 맵 zip / 모드 jar 등) 호스팅 | — |
|
|
|
|
---
|
|
|
|
## 핵심 컨셉
|
|
|
|
설치기는 사용자의 `%APPDATA%\.minecraft` 를 더럽히지 않기 위해 **`.mc_custom`** 을 별도 게임 디렉터리로 사용합니다.
|
|
|
|
```
|
|
%APPDATA%\
|
|
├─ .minecraft\ ← 원래 마인크래프트 폴더(공용 자원: assets, libraries, versions, runtime)
|
|
└─ .mc_custom\ ← 음악퀴즈 전용 게임 폴더(설치기가 자동 생성)
|
|
├─ mods\ ← 음악퀴즈가 지정한 모드(.jar)
|
|
├─ resourcepacks\ ← 리소스팩(.zip)
|
|
├─ saves\ ← 단일 맵 .zip 압축 해제 결과
|
|
├─ assets\ (junction → .minecraft\assets)
|
|
├─ libraries\ (junction → .minecraft\libraries)
|
|
├─ versions\ (junction → .minecraft\versions)
|
|
├─ options.txt 등 ← `.minecraft` 의 최상위 설정 파일을 복사해 사용
|
|
└─ launcher_profiles ← 실제 파일은 `.minecraft\launcher_profiles.json` 을 수정해 gameDir=.mc_custom 으로 지정
|
|
```
|
|
|
|
이렇게 분리해 두면 사용자가 평소 쓰던 마인크래프트와 음악퀴즈 설정이 섞이지 않고, 음악퀴즈만 삭제해도 본체에는 영향이 없습니다.
|
|
|
|
---
|
|
|
|
## 빠른 시작
|
|
|
|
전제: Node.js 18+, npm. 윈도우 빌드를 만들 때만 추가로 Electron 의 PE 서명·아이콘 도구가 필요합니다.
|
|
|
|
```bash
|
|
# 의존성 설치
|
|
npm install
|
|
|
|
# 1) 관리 사이트 개발 실행 (http://localhost:3000)
|
|
npm start
|
|
|
|
# 2) 음악퀴즈 간편설치기를 Electron 으로 실행해 보기
|
|
npm run installer
|
|
|
|
# 3) 리소스팩 간편설치기를 Electron 으로 실행해 보기
|
|
npm run installer:rp
|
|
|
|
# 4) 음악퀴즈 간편설치기 윈도우 .exe 빌드
|
|
npm run dist:win
|
|
```
|
|
|
|
리소스팩 설치기는 `yt-dlp` 가 필요합니다. 자동 다운로드되지만, 막혀 있는 환경이라면 [`docs/yt-dlp-setup.md`](docs/yt-dlp-setup.md) 참고.
|
|
|
|
---
|
|
|
|
## 자주 쓰는 문서
|
|
|
|
| 문서 | 내용 |
|
|
| --- | --- |
|
|
| [`docs/installer.md`](docs/installer.md) | 음악퀴즈 간편설치기 사용자 흐름(단계별 화면·동작). |
|
|
| [`docs/admin-site.md`](docs/admin-site.md) | 관리 사이트 운영자 가이드(음악퀴즈 추가·편집, 음악 목록, 데이터팩 출력). |
|
|
| [`docs/resourcepack-installer.md`](docs/resourcepack-installer.md) | 리소스팩 간편설치기 동작 명세(yt-dlp 흐름, 이미지 정규화 규칙). |
|
|
| [`docs/painting-variant.md`](docs/painting-variant.md) | 1.21+ painting variant 슬롯/리소스팩 텍스처 규격. |
|
|
| [`docs/yt-dlp-setup.md`](docs/yt-dlp-setup.md) | yt-dlp 자동/수동 설치, 트러블슈팅. |
|
|
|
|
---
|
|
|
|
## 데이터 포맷 (요약)
|
|
|
|
자세한 필드 설명은 `docs/admin-site.md` 의 "음악퀴즈 JSON" 절을 참고하세요.
|
|
|
|
### `manifest.json` — 사이트 루트, 음악퀴즈 목록
|
|
|
|
```json
|
|
{
|
|
"packs": [
|
|
{ "name": "음악퀴즈 v1", "file": "mq-v1" }
|
|
]
|
|
}
|
|
```
|
|
|
|
- `file` 은 `/manifest/<file>.json` 의 파일명(확장자 제외).
|
|
- 관리 사이트에서 음악퀴즈를 추가/삭제하면 자동으로 갱신됩니다.
|
|
|
|
### `/manifest/<key>.json` — 음악퀴즈 정의
|
|
|
|
```json
|
|
{
|
|
"name": "음악퀴즈 v1",
|
|
"mcVersion": "1.21.4",
|
|
"platform": {
|
|
"type": "fabric",
|
|
"loaderVersion": "0.16.10"
|
|
},
|
|
"modsFolder": "mq-v1",
|
|
"resourcepackPath": "mq-v1.zip",
|
|
"mapPath": "mq-v1-map.zip",
|
|
"serverPath": "mq-v1-server.zip",
|
|
"serverMinRam": 4096,
|
|
"serverMaxRam": 8192,
|
|
"clientMinRam": 4096,
|
|
"clientRecommendedRam": 8192
|
|
}
|
|
```
|
|
|
|
- `platform.type` = `vanilla` / `forge` / `fabric` / `neoforge`.
|
|
- `fabric` 은 `loaderVersion` 만 지정하면 설치기가 최신 fabric-installer 로 자동 CLI 설치합니다.
|
|
- 나머지(forge/neoforge) 는 `platform.downloadUrl` 에 설치 jar URL.
|
|
- `modsFolder` → `/file/mods/<폴더>/` 의 모든 `.jar` 를 자동으로 받습니다.
|
|
- `serverPath` / `mapPath` / `resourcepackPath` → `/file/servers/`, `/file/maps/`, `/file/resourcepacks/` 아래 zip 파일명.
|
|
|
|
### `/file/list/<key>.json` — 음악·사진 목록 (리소스팩 설치기용)
|
|
|
|
```json
|
|
{
|
|
"musicPlaylistUrl": "https://www.youtube.com/playlist?list=...",
|
|
"imagePlaylistUrl": "https://www.youtube.com/playlist?list=...",
|
|
"music": [
|
|
{ "url": "https://www.youtube.com/watch?v=...", "title": "...", "artist": "...", "durationSec": 213 }
|
|
],
|
|
"images": [
|
|
{ "url": "https://www.youtube.com/watch?v=..." },
|
|
{ "url": "https://example.com/cover.png" }
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 디렉터리 구조 (전체)
|
|
|
|
```
|
|
minecraft_launcher/
|
|
├─ src/
|
|
│ ├─ server/ Express + EJS 관리 사이트
|
|
│ ├─ installer/ 음악퀴즈 간편설치기 (Electron 메인 + preload)
|
|
│ ├─ installer-rp/ 리소스팩 간편설치기 (Electron 메인 + 음악/이미지 파이프라인)
|
|
│ └─ shared/ 공용 타입, 매니페스트 스토어, mojang/upnp 유틸
|
|
├─ installer/ 음악퀴즈 설치기 렌더러(HTML/CSS/JS)
|
|
├─ installer-rp/ 리소스팩 설치기 렌더러(HTML/CSS/JS)
|
|
├─ views/ 관리 사이트 EJS 템플릿
|
|
├─ public/ 관리 사이트 정적 파일(styles.css 등)
|
|
├─ manifest/ 음악퀴즈 JSON 정의 (운영자가 편집)
|
|
├─ file/
|
|
│ ├─ servers/ 서버 zip
|
|
│ ├─ maps/ 맵 zip
|
|
│ ├─ mods/<폴더>/ 모드 jar 묶음 (index.json 자동 생성)
|
|
│ ├─ resourcepacks/ 리소스팩 zip
|
|
│ ├─ platforms/ Forge / NeoForge 설치 jar
|
|
│ └─ list/<key>.json 음악·사진 목록
|
|
├─ docs/ 사용·운영 문서
|
|
├─ manifest.json 사이트 루트 매니페스트 (자동 관리)
|
|
├─ account.json 관리자 계정 (절대 외부 노출 금지)
|
|
├─ package.json
|
|
└─ tsconfig.{,server,installer,installer-rp}.json
|
|
```
|
|
|
|
---
|
|
|
|
## 빌드 산출물 / 배포
|
|
|
|
| 산출물 | 빌드 명령 | 비고 |
|
|
| --- | --- | --- |
|
|
| 관리 사이트 (Node 실행) | `npm start` | systemd 등으로 띄우기. 외부 도메인이 manifest 의 base URL 이 됩니다. |
|
|
| 음악퀴즈 간편설치기 `.exe` | `npm run dist:win` | `electron-builder.yml` 설정 사용. |
|
|
| 리소스팩 간편설치기 `.exe` | `tsconfig.installer-rp.json` 빌드 후 `electron-builder` 수동 패키징 | |
|
|
|
|
---
|
|
|
|
## 라이선스
|
|
|
|
내부 프로젝트. 외부 공개 시 별도 명시.
|