minecraft_launcher/docs/launcher-catalog.md

Launcher Catalog

프로필은 관리자 측에서 미리 등록합니다.

• 기본 로컬 파일: app/assets/launcher/catalog.json
• 또는 운영용 원격 JSON

클라이언트는 설치 페이지에서 이 카탈로그를 읽기 전용으로 확인하고, 원하는 항목만 자기 라이브러리에 추가합니다.

형식

{
  "version": 1,
  "profiles": [
    {
      "id": "my-modpack",
      "name": "My Modpack",
      "kind": "modpack",
      "description": "설명",
      "details": "설치 페이지 상세 패널에 표시할 긴 설명",
      "distributionUrl": "https://example.com/launcher/distribution.json",
      "defaultServerAddress": "example.com:25565",
      "allowCustomServerAddress": true
    },
    {
      "id": "my-map",
      "name": "My Map",
      "kind": "map",
      "description": "싱글플레이 월드",
      "details": "월드와 플레이 방식에 대한 상세 설명",
      "distributionUrl": "https://example.com/launcher/vanilla-map-distribution.json",
      "worldArchiveUrl": "https://example.com/worlds/my-map.zip",
      "worldDirectoryName": "My Map",
      "allowCustomServerAddress": false
    },
    {
      "id": "my-server-pack",
      "name": "My Server Pack",
      "kind": "server-pack",
      "description": "클라이언트 + 로컬 서버 번들",
      "details": "서버 실행 방법, 권장 인원, 접속 방식 등 상세 설명",
      "distributionUrl": "https://example.com/launcher/server-pack-client-distribution.json",
      "serverBundleUrl": "https://example.com/serverpacks/my-server-pack.zip",
      "serverDirectoryName": "my-server-pack",
      "serverLaunchCommand": "java -jar server.jar nogui",
      "serverPort": 25565,
      "tunnelCommand": "playit-cli --port ${port}",
      "tunnelAddressRegex": "([a-zA-Z0-9.-]+:\\d+)",
      "allowCustomServerAddress": true
    }
  ]
}

필드

• id: 내부 식별자
• name: 라이브러리/설치 페이지 표시 이름
• kind: modpack, map, server-pack
• description: 표시 설명
• details: 설치 페이지 상세 패널에 표시할 긴 설명
• distributionUrl: Helios distribution.json URL 또는 로컬 경로
• defaultServerAddress: 기본 자동 접속 주소
• allowCustomServerAddress: 사용자가 라이브러리에서 주소를 덮어쓸 수 있는지 여부
• worldArchiveUrl: kind: map 일 때 사용할 월드 ZIP 또는 로컬 경로
• worldDirectoryName: 게임 saves/ 아래에 설치될 월드 폴더 이름
• serverBundleUrl: kind: server-pack 일 때 사용할 서버 ZIP 또는 로컬 디렉터리/경로
• serverDirectoryName: 서버 번들이 풀릴 하위 디렉터리 이름
• serverLaunchCommand: 로컬 서버 실행 명령. 비워두면 start.sh, start.bat, server.jar 순으로 추론
• serverWorkingDirectory: 실제 실행할 작업 디렉터리. 서버 루트 기준 상대 경로
• serverPort: 로컬 서버 포트
• tunnelCommand: 선택형 터널 명령. ${port}, ${serverDir} 치환 가능
• tunnelAddressRegex: 터널 stdout 에서 공개 주소를 추출할 정규식

런처가 계산하는 상태

아래 값들은 런처가 내부적으로 계산하는 상태라 파일에 직접 넣지 않아도 됩니다.

• launchReady: 실행에 필요한 필드가 모두 있는지 여부

• hostReady: server-pack 이 로컬 호스팅 가능한지 여부 판정 기준:

• modpack: distributionUrl 필요

• map: distributionUrl, worldArchiveUrl, worldDirectoryName 필요

• server-pack: 클라이언트 실행은 distributionUrl, 로컬 호스팅은 추가로 serverBundleUrl 필요

현재 구현 범위

• modpack: 지원
• map: 월드 ZIP 사전 다운로드, saves/ 설치, --quickPlaySingleplayer 실행 지원
• server-pack: distribution 기반 클라이언트 + 수동 주소 입력 자동 접속 + 로컬 서버 실행 + 선택형 터널 명령 지원

네트워크 참고

포트포워딩 없이 외부 사용자가 접속하려면 런처 단독으로는 부족합니다.

필요한 것 중 하나:

• 별도 중계 서버
• 터널링 도구
• VPN/NAT traversal 백엔드

현재 구현은 그 중 터널 명령 실행기를 연결할 수 있는 자리까지만 제공합니다.