BuzzBuild-Framework — 설정

Paper는 plugins/BuzzBuild-Framework/config.yml, Velocity는 Framework 데이터 디렉터리의 gate.json, Fabric은 config/buzzbuild-image-gui.json을 사용합니다. TOML 설정 파일은 없습니다.

Paper 기본 설정

점으로 구분한 키는 YAML의 중첩 경로입니다. 아래 기본값은 배포 리소스 기준이며 코드 전용 호환 키는 별도 표시했습니다. 연결 주소·계정은 공개 문서에 원문을 싣지 않습니다.

키	타입	기본값	설명
`brand.display-name`	문자열	`BuzzBuild`	제품 표시명. 공백만 입력하면 기존 기본 표시명 유지
`brand.prefix`	문자열	`BB`	로그 접두 본체. 앞뒤 공백 제거
`database.enabled`	불리언	`false`	MariaDB 연결 풀 사용
`database.jdbc-url`	문자열	연결 정보 원문 비공개	MariaDB JDBC URL. 아래 가상 예시로 구조 확인
`database.username`	문자열	계정 기본값 원문 비공개	DB 인증 계정
`database.password`	문자열	빈 문자열	DB 인증 비밀번호. 파일에 평문 저장
`database.pool-name`	문자열	`BuzzBuild-Hikari`	풀 식별 이름
`database.maximum-pool-size`	정수	`8`	최대 풀 크기. 코드에서 최소 1로 보정
`database.minimum-idle`	정수	`2`	최소 유휴 연결. 코드에서 0~입력 최대 풀 크기로 제한
`database.connection-timeout-ms`	정수(long)	`10000`	연결 획득 대기 시간, 밀리초
`database.idle-timeout-ms`	정수(long)	`600000`	유휴 연결 시간 설정, 밀리초
`database.max-lifetime-ms`	정수(long)	`1800000`	연결 수명 설정, 밀리초
`database.driver-class-name`	문자열	`org.mariadb.jdbc.Driver`	명시적으로 로드하는 JDBC 드라이버 클래스
`database.cache-prep-stmts`	불리언	`true`	드라이버의 `cachePrepStmts` 속성
`database.prep-stmt-cache-size`	정수	`250`	드라이버의 `prepStmtCacheSize` 속성
`database.prep-stmt-cache-sql-limit`	정수	`2048`	드라이버의 `prepStmtCacheSqlLimit` 속성
`database.migration.log-existing-tables`	불리언	`false`	기존 테이블을 건너뛸 때 상세 로그 출력
`messaging.debug`	불리언	`false`	수신 플레이어와 `feature/op` 상세 로그 출력
`proxy.control-bridge-enabled`	불리언	`true`	Paper 게이트 전달 브릿지와 명령 실행기 활성화
`proxy.transfer-enabled`	불리언	`true`	DB 준비 시 이동 서비스·핸드오프 테이블·명령 실행기 활성화
`proxy.server-id`	문자열	빈 문자열	출발 서버 기록용 ID. 빈 값이면 `from_server=null`
`proxy.handoff-ttl-seconds`	정수	`120`	핸드오프 유효 기간. 저장 시 최소 30초로 보정
`integrations.show-on-banner`	불리언	`true`	배너의 연동 감지 표시
`integrations.plugins`	문자열 목록	아래 기본 목록	Bukkit 플러그인 이름으로 설치·활성 상태 확인
`logging.startup-details`	불리언	`true`	기동 상세 로그 출력

integrations.plugins 기본 목록은 Vault, LuckPerms, PlaceholderAPI, Nexo, Citizens, MythicMobs, MythicLib, ModelEngine입니다. 빈 목록이면 기본 목록으로 되돌아가므로 표시를 없애려면 integrations.show-on-banner: false를 사용합니다.

호환 키 database.pool-size는 정수이며 코드의 최종 대체값은 8입니다. 기본 리소스에는 없고 database.maximum-pool-size가 읽히지 않을 때만 대체값으로 사용됩니다. 새 설정은 database.maximum-pool-size를 사용합니다. minimum-idle의 코드 대체값은 min(2, maxPool)입니다. Hikari가 잘못된 설정을 추가로 거부할 수 있으며 모든 설정 오류가 DB 비활성 처리로 복구되는 것은 아닙니다.

실제 채널 buzz:payload, buzz:proxyctl, buzz:proxy와 테이블 접두 bb_는 코드 상수이며 변경용 설정 키가 없습니다. buzz:<feature>:<op>는 로그용 논리 경로이고 별도 네트워크 채널이 아닙니다.

DB·프록시 없이 사용하는 최소 예시

생성된 기본 파일에서 다음 부분을 설정합니다. 생략한 키는 기본 리소스 또는 코드 대체값을 사용합니다.

database:
  enabled: false
proxy:
  control-bridge-enabled: false
  transfer-enabled: false

DB와 프록시를 사용하는 예시

아래 주소·계정·비밀번호·서버 이름은 모두 가상값입니다. 이대로 접속할 수 없으며 실제 접속 정보는 공개 문서나 저장소에 기록하지 않습니다.

database:
  enabled: true
  jdbc-url: "jdbc:mariadb://example.invalid:3306/example_framework"
  username: "example_user"
  password: "EXAMPLE_NOT_A_REAL_PASSWORD"
proxy:
  control-bridge-enabled: true
  transfer-enabled: true
  server-id: "example-lobby"
  handoff-ttl-seconds: 120

Paper 설정은 활성화 시 읽습니다. 전용 reload 명령은 없으며 다음 운영자 재시작 때 적용합니다.

Velocity: gate.json

키	타입	기본값	설명
`whitelistEnabled`	불리언	`false`	화이트리스트 검사 사용
`maintenanceEnabled`	불리언	`false`	점검 허용 검사 사용
`whitelistKickMessage`	문자열	`화이트리스트에 등록되지 않은 계정입니다.`	화이트리스트 거부 메시지
`maintenanceKickMessage`	문자열	`서버 점검 중입니다. 잠시 후 다시 접속해 주세요.`	점검 거부 메시지
`whitelist`	문자열 배열	`[]`	허용 UUID 또는 소문자 계정 이름
`maintenanceAllowed`	문자열 배열	`[]`	점검 중 허용 UUID 또는 소문자 계정 이름

{
  "whitelistEnabled": false,
  "maintenanceEnabled": false,
  "whitelistKickMessage": "화이트리스트에 등록되지 않은 계정입니다.",
  "maintenanceKickMessage": "서버 점검 중입니다. 잠시 후 다시 접속해 주세요.",
  "whitelist": [],
  "maintenanceAllowed": []
}

명령으로 변경한 값은 즉시 저장을 시도합니다. 수동 파일 편집 내용은 다음 프록시 초기화 때 읽으며 자동 재읽기는 없습니다. 직접 입력하는 이름은 소문자, UUID는 하이픈이 있는 표준 문자열로 작성합니다. 파일 로드 시 목록 전체를 정규화하는 처리는 없습니다. null이나 잘못된 타입을 넣지 않습니다.

Fabric: buzzbuild-image-gui.json

키	타입	기본값	범위·설명
`playerInventoryYOffset`	정수	`-10`	`-80`~`80`. 인벤토리 배경 세로 보정. 렌더러가 추가로 `+10`을 적용해 기본값은 슬롯 정렬 기준에서 0 보정
`playerInventorySourceY`	정수	`131`	`0`~`255`. 텍스처를 잘라 읽을 시작 Y
`playerInventoryHeight`	정수	`85`	`1`~`256 - playerInventorySourceY`. 잘라 읽을 높이
`backdropAlpha`	정수	`170`	`0`~`255`. 화면 검은 배경 불투명도

{
  "playerInventoryYOffset": -10,
  "playerInventorySourceY": 131,
  "playerInventoryHeight": 85,
  "backdropAlpha": 170
}

범위 밖 숫자는 위 범위로 보정합니다. 해당 이미지 GUI 렌더링 중 약 0.5초마다 수정 시각을 비교해 다시 읽습니다. 읽기에 실패하면 경고를 남기고 마지막 정상값을 유지합니다. 실패한 파일의 수정 시각도 기록하므로 수정 후 다시 저장해야 재시도됩니다.

확인 범위

2026-10-05 기본 리소스와 실제 설정 읽기 코드를 대조했습니다. 게임 내 동작은 미검증입니다.