BuzzBuild-Framework — 사용법

아래는 구현에서 확인한 절차입니다. 명령 예시의 ExamplePlayer, example-lobby는 가상값입니다. 실제 테스트 완료 기록은 아닙니다.

화이트리스트와 점검 운영

1. Velocity용 Framework의 초기화 성공과 게이트 파일 저장 가능 여부를 확인합니다.
2. Velocity 콘솔에서 bbwl add ExamplePlayer로 계정을 추가하고 bbwl list로 확인합니다.
3. bbwl on으로 신규 로그인 검사를 켭니다. 현재 접속자를 일괄 내보내지는 않습니다.
4. 점검에 참여할 계정을 bbmaint allow ExamplePlayer로 먼저 허용합니다. 화이트리스트도 켜져 있으면 두 목록에 모두 있어야 접속할 수 있습니다.
5. bbmaint on은 현재 접속자도 검사해 허용되지 않은 계정을 연결 해제합니다. 명령 실행자도 목록 예외가 없으며 관리자 권한으로 우회하지 않습니다.
6. bbmaint status로 상태를 확인합니다. 점검 종료 시 bbmaint off를 사용합니다. 이 명령은 화이트리스트까지 끄지는 않습니다.

로그인 이벤트는 점검 조건을 먼저 검사하고 화이트리스트를 이어서 검사합니다. 점검 전환 시 기존 접속자를 내보낼 때는 화이트리스트로 거부된 경우도 점검 메시지를 표시합니다.

Paper에서 원격 제어할 때는 proxy.control-bridge-enabled: true와 접속자 1명 이상이 필요합니다. Paper의 성공 메시지는 전송 결과이므로 최종 상태는 Velocity에서 확인합니다. 전체 문법과 권한은 명령어·권한을 참고하세요.

서버 이동 점검

1. 출발 Paper의 DB 풀과 bb_framework_handoff 테이블 준비를 확인합니다.
2. proxy.transfer-enabled: true로 이동 서비스를 활성화하고 proxy.server-id에 해당 서버 식별자를 설정합니다.
3. Velocity에 목적지 서버가 등록되어 있는지 확인하고, 출발 Paper에 테스트 플레이어가 접속한 상태에서 /bbtransfer example-lobby ExamplePlayer를 실행합니다.
4. Paper의 핸드오프 ID와 Velocity의 연결 실패·거부 로그를 확인하고 실제 도착 여부를 별도로 확인합니다.
5. 기능 플러그인이 도착 후 핸드오프를 소비해야 하는 경우 출발·도착 서버가 같은 DB 기록에 접근하는지 확인합니다.

Framework는 DB에 pending 기록을 만든 뒤 buzz:proxy로 op, uuid, server, feature, handoffId와 선택적 from을 보냅니다. Velocity는 등록 서버에 연결을 요청합니다. 연결 결과를 Paper에 돌려주는 응답 처리는 구현되지 않았습니다.

도착 후 claimPending(UUID, feature) 호출은 사용하는 기능 플러그인의 책임입니다. Framework 자체에는 도착 이벤트에서 자동 claim하는 리스너가 없습니다. /bbtransfer의 framework 기록이 자동으로 claimed가 되는 것도 아닙니다. 조회는 동일 UUID·feature의 가장 오래된 유효 기록을 선택하며 목적지 서버로 필터링하지 않습니다. TTL은 최소 30초이고 만료 상태 갱신은 peek·claim 조회 때 수행됩니다. 자동 삭제 작업은 없습니다.

Ticket의 이동 코드와 Prison의 브릿지에서 서비스 조회·이동 요청·claim 호출을 확인했습니다. 이 두 플러그인의 전체 업무 흐름과 실제 도착 처리는 별도 검증 대상입니다.

이미지 GUI 배경 조정

1. Fabric 클라이언트용 Framework와 필요한 기능 모드·GUI 리소스를 준비합니다.
2. 제목에 raonblank, U+A000U+A4FF, U+E000U+F8FF 중 하나가 포함된 상자 화면을 엽니다. 일반 상자 전체에 적용되는 기능은 아닙니다.
3. 해당 화면에서 생성된 config/buzzbuild-image-gui.json을 확인합니다.
4. 설정 범위 안에서 배경 투명도·텍스처 위치를 조정하고 저장합니다.
5. 대상 화면에서 배경·아이템·클릭 위치가 맞는지 직접 확인합니다.

렌더러는 기본 상자 배경을 취소하고 검은 배경과 내장 인벤토리 텍스처를 그립니다. 글리프 이미지 자체를 새로 생성하거나 모든 GUI를 제공하지는 않습니다. 인벤토리 슬롯의 클릭 좌표를 변경하는 코드도 아닙니다.

기능 플러그인 개발자가 사용하는 API 흐름

목적	실제 제공 API와 사용 순서
기능 검색	Bukkit 서비스에서 FeatureRegistry를 얻고 register, find, findByType, unregister 사용
표시 이름	PaperIdentities.find()가 직접 PlayerIdentity 서비스, 기능 레지스트리 순으로 조회. displayName은 제공자가 없으면 전달한 대체 이름 사용
DB 테이블	PaperTableRegistry.registerMigrations(pluginId, ddl...) 사용. DB 준비 시 즉시 적용하고 applyAll()도 제공
서버 GUI	PaperGuiRenderer.open(player, schema) 호출. 9~54칸, 범위 밖 슬롯 무시, 알 수 없는 Material은 STONE
메시지	Paper와 Fabric에서 동일 feature/op 핸들러를 등록하고 send로 전송. 종료 시 unregister

메시지는 길이 VarInt와 UTF-8 JSON으로 구성되며 JSON 필드는 v, feature, op, data입니다. 현재 생성 버전은 v=1이고 별도 버전 협상·버전 거부는 없습니다. 등록되지 않은 경로는 처리하지 않습니다. Framework가 기능 핸들러의 권한·업무 입력 검증까지 대신하지는 않습니다.

GuiSchema 렌더러에는 클릭 이벤트 처리·아이템 이동 방지 등록이 없으므로 사용하는 플러그인이 구현해야 합니다. DB 마이그레이션은 이미 존재하는 테이블을 건너뛰며 기존 스키마를 자동으로 목표 구조와 비교·수정하지 않습니다.

확인 범위

2026-10-05 Framework의 생산·소비 코드와 Ticket·Prison의 관련 호출부를 확인했습니다. 게임 내 동작은 미검증입니다.