BuzzBuild-Framework — 문제 해결
먼저 해당 문제가 Paper, Velocity, Fabric 중 어디에서 발생했는지 구분합니다. 공개 문의에 로그를 첨부할 때 DB 접속 정보와 플레이어 개인 정보를 제거합니다.
문제별 확인과 해결
섹션 제목: “문제별 확인과 해결”| 문제 | 확인 방법 | 해결 방법 |
|---|---|---|
| 플러그인·모드가 로드되지 않음 | Java·Minecraft·플랫폼 버전과 설치 JAR 종류 확인 | 설치의 플랫폼별 런타임 JAR 사용. Fabric API·Loader 요구 조건 확인 |
Transfer API 비활성 | database.enabled, DB 풀 준비 로그, proxy.transfer-enabled 확인 | 기본 DB 값은 꺼짐. 필요한 DB 설정을 적용하고 다음 운영자 재시작 후 다시 확인 |
| DB 풀 연결 실패 | 접속 가능 여부, 인증·권한, JDBC 드라이버, 풀 수치 확인 | 연결 정보와 MariaDB 권한 수정. 잘못된 Hikari 설정은 초기화 자체를 실패시킬 수 있음 |
| 테이블 생성 실패 | 실패 framework/bb_framework_handoff 등 DB 로그 확인 | 해당 DB의 DDL 권한·기존 구조 확인. 풀 준비만으로 테이블 생성 성공을 판단하지 않음 |
| Paper 게이트 명령을 실행해도 반영 안 됨 | 온라인 플레이어 유무, 브릿지 설정, Velocity 초기화 로그 확인 | 캐리어가 없으면 Velocity 콘솔에서 명령 실행. Paper 전송 메시지 이후 Velocity 상태를 별도로 조회 |
bbwl list나 bbmaint status에 상태가 안 나옴 | 명령 실행 위치 확인 | Paper에서는 안내만 출력. Velocity에서 실행 |
| 명령 권한 없음 | 실행 환경의 buzzbuild.proxy.admin 확인 | Paper 기본값은 OP. Velocity는 해당 권한 부여 또는 콘솔 사용 |
| 설정을 껐는데 명령 이름이 보임 | plugin.yml 선언과 실행기 활성화 조건 구분 | 선언이 남는 현재 구조의 결과. 실제 활성화 상태는 로그와 설정으로 확인 |
| 관리자인데 로그인 거부·점검 시 연결 해제 | 두 게이트 상태와 각 허용 목록 확인 | 관리자 우회 없음. 활성화된 모든 목록 조건을 만족하도록 등록 |
| 목록에 직접 입력한 이름이 인식 안 됨 | gate.json의 대소문자·UUID 형식 확인 | 소문자 이름·표준 UUID 사용하거나 명령으로 등록. 닉네임 대신 계정 식별자 사용 |
| 게이트 변경이 재기동 후 사라짐 | Velocity의 게이트 설정 저장 실패 확인 | 데이터 디렉터리 쓰기 권한·디스크 상태 수정. 명령 성공 문구만으로 저장 성공을 판단하지 않음 |
| 이동 요청은 나왔지만 이동하지 않음 | Velocity의 등록되지 않은 서버·연결 실패·이동 거부 로그 확인 | 목적지 서버 등록·가용성 확인. Paper에는 완료 응답이 없으므로 도착 여부 직접 확인 |
| 핸드오프가 처리되지 않음 | 공유 DB, feature, TTL, 도착 플러그인의 claim 호출 확인 | 소비 기능을 확인. /bbtransfer만으로 자동 소비되지 않으며 만료 기록 자동 삭제도 없음 |
| 클라이언트 메시지를 못 보냄 | Cannot send 경고, Paper 채널 준비 여부 확인 | Paper·Fabric Framework와 기능 핸들러 설치 상태 확인. 채널명은 설정으로 바꾸지 않음 |
핸들러 없음·메시지 파싱 오류 | 기능 ID·op·JSON·와이어 형식과 모듈 버전 확인 | 기능 플러그인의 등록·전송 코드를 대조. 일반 JSON을 길이 접두 없이 buzz:payload에 보내지 않음 |
| 이미지 GUI 설정 파일이 없음 | 대상 제목의 상자 화면을 열었는지 확인 | 대상 화면 렌더링 때 지연 생성됨. 일반 상자에서는 생성되지 않을 수 있음 |
| 이미지 GUI 배경이 어긋남 | 네 개 설정값, 기존 raon-gui.json 이관 여부 확인 | 기본값으로 비교하고 오프셋 조정. 슬롯 클릭 좌표는 이동시키지 않음 |
| 이미지 GUI 설정 수정이 반영 안 됨 | JSON 문법·값 타입·수정 시각·읽기 실패 로그 확인 | 잘못된 값을 수정한 뒤 다시 저장. 대상 화면에서 변경 감지됨 |
| 연동 배너 ON인데 경제·권한 기능이 없음 | 해당 표시는 설치·활성 탐지인지 확인 | 실제 기능 플러그인의 연동 지원 확인. Framework 배너는 API 브릿지 보장이 아님 |
구현되지 않았거나 보장하지 않는 사항
섹션 제목: “구현되지 않았거나 보장하지 않는 사항”- 별도 설정 reload 명령, 게이트 상태의 Paper 회신, 이동 성공·실패의 Paper 회신은 없습니다.
- Paper 브랜드 설정을 Fabric으로 자동 동기화하지 않습니다. 클라이언트는 기본 브랜드로 초기화합니다.
- Framework 단독의 일반 사용자 메뉴·GUI 클릭 처리·아이템 이동 방지는 없습니다.
- Quake 반사 호출 브릿지 클래스는 있으나 현재 Framework 이미지 GUI 렌더러에서 사용하는 호출은 확인되지 않았습니다. 화면 흔들림 연동을 제공 기능으로 보장하지 않습니다.
- Spigot·Folia, 다른 Minecraft 버전, 구체적인 MariaDB 서버 버전 범위, 모든 선택 플러그인과의 호환성은 미확인입니다.
- 현재 프록시 메시지 수신부의 송신 주체 검증과 이동 대상 검증은 별도 코드 검토가 필요합니다. 명령어 권한 검사만으로 메시지 경로까지 보호된다고 가정하지 않습니다.
추가로 확인할 항목
섹션 제목: “추가로 확인할 항목”실제 플랫폼별 로딩, DB 연결과 DDL, 프록시 경유 명령 선택, 게이트 저장·접속 차단, 서버 이동·도착 소비, Fabric 메시징·이미지 GUI 표시를 테스트 환경에서 확인해야 합니다. 전체 사이트 빌드와 렌더링은 위키 통합 과정에서 확인합니다.
확인 범위
섹션 제목: “확인 범위”2026-10-05 소스 정적 확인 기준이며 게임 내 동작은 미검증입니다. 서버 시작·중지·재시작·전체 reload를 수행하지 않았습니다.