BuzzBuild-Framework — 설치

서버 운영자와 클라이언트 배포 담당자를 위한 안내입니다. 아래 경로는 각각 서버·프록시·게임 인스턴스 루트 기준 상대 경로입니다.

배포물 선택

배포물	설치 위치	용도
`BuzzBuild-Framework-Paper-0.1.0.jar`	Paper의 `plugins/`	DB·서비스·메시징·프록시 요청
`BuzzBuild-Framework-Velocity-0.1.0.jar`	Velocity의 `plugins/`	게이트와 서버 연결 처리
`BuzzBuild-Framework-Fabric-0.1.0.jar`	클라이언트의 `mods/`	Fabric 메시징과 이미지 GUI 보조

파일명은 현재 Gradle 아카이브 설정 기준입니다. -api.jar, 소스 JAR, 개발용 JAR를 런타임 JAR 대신 설치하지 않습니다. shared는 별도 설치 대상이 아닙니다. Fabric 모드는 전용 서버용 모드가 아닙니다.

의존성 준비

지원 환경에 맞는 Java·Paper·Fabric·Velocity를 준비합니다.
Fabric 클라이언트에는 Minecraft 26.1.2용 Fabric API를 함께 설치합니다.
DB 기능이 필요하면 MariaDB 데이터베이스와 전용 접속 정보를 준비합니다. Framework가 만드는 것은 등록된 테이블이며 데이터베이스 자체를 생성하는 코드는 없습니다.
서버 이동을 사용할 경우 목적지를 Velocity에 등록하고 출발·도착 Paper의 기능 플러그인이 필요한 공유 DB와 서버 식별자를 설정합니다.
선택 플러그인은 사용할 기능의 요구사항에 맞춰 설치합니다. 배너에 표시되는 선택 플러그인을 전부 설치할 필요는 없습니다.

최초 실행과 생성 파일

운영자가 정한 설치·실행 일정에 맞춰 JAR를 배치하고 실행한 뒤 다음을 확인합니다. 이 문서 작성 과정에서 서버를 실행하거나 재시작하지는 않았습니다.

환경	파일	생성 시점
Paper	`plugins/BuzzBuild-Framework/config.yml`	`onEnable()`의 `saveDefaultConfig()`; 기존 파일은 덮어쓰지 않음
Velocity	Framework 데이터 디렉터리의 `gate.json`	프록시 초기화 때 파일이 없으면 생성; 플러그인 ID는 `buzzbuild-framework`
Fabric	`config/buzzbuild-image-gui.json`	대상 이미지 GUI 렌더링에서 설정을 처음 읽을 때 생성

Fabric 설정이 없고 config/raon-gui.json이 있으면 기존 파일을 새 이름으로 복사합니다. 원본을 삭제하는 코드는 없습니다.

Paper 기본값은 database.enabled: false입니다. proxy.transfer-enabled: true여도 DB가 준비되지 않으면 이동 서비스·명령 실행기가 활성화되지 않습니다. 게이트 제어는 DB와 독립적이지만 Paper에서 전달하려면 접속 중인 플레이어가 필요합니다.

설정 적용 절차

생성된 파일을 백업한 다음 설정의 필요한 항목을 편집합니다.
Paper 설정은 활성화 시 읽으므로 운영자가 다음 재시작 때 적용합니다. 별도 Framework reload 명령은 없습니다.
Velocity 게이트 상태·목록은 명령으로 변경하면 메모리에 반영하고 gate.json에 저장을 시도합니다. 파일을 직접 수정한 경우 다음 프록시 초기화 때 읽습니다. 실행 중 파일 편집은 이후 명령 저장으로 덮어써질 수 있습니다.
Fabric 이미지 GUI 설정은 대상 화면 렌더링 중 약 0.5초 간격으로 파일 변경 여부를 확인합니다.
Paper에서 메시징 준비 로그, DB 사용 시 풀 준비와 테이블 생성 오류 여부, Velocity에서 게이트·이동 준비 로그를 확인합니다. 실제 검증은 사용법의 시나리오별로 진행합니다.

서버 전체 /reload로 적용하는 절차는 제공하지 않습니다.

확인 범위

2026-10-05 소스 확인 기준입니다. 배포 JAR 실물과 실행 환경은 검증하지 않았으며, 게임 내 동작은 미검증입니다.