BuzzBuild-Avatar — 개요
BuzzBuild-Avatar는 Paper 서버의 코스메틱 카탈로그와 Fabric 클라이언트의 아바타 선택 화면을 연결합니다. 일반 상자 GUI가 아닌 전용 클라이언트 화면을 사용합니다.
핵심 기능
섹션 제목: “핵심 기능”- 모자·등·보조손 등 그룹별 카탈로그와 보유 여부 표시
- 부위별 아이템 선택과 클라이언트 미리보기, 변경한 보유 아이템들을 함께 적용
- 미보유 필터, 목록 스크롤, 모델 드래그 회전
- 서버에서 대상의 권한을 검사하는 장착·해제
- 관리자의 온라인 플레이어 편집, 강제 착용, 그룹 해제, 장착 조회와 설정 리로드
- HMCCosmetics 장착 API와 Nexo 아이콘·모델 조회 연동
지원 환경
섹션 제목: “지원 환경”현재 프로젝트가 고정한 개발 대상입니다. 다른 버전의 호환성을 보증하는 표가 아닙니다.
| 항목 | 소스에서 확인한 값 |
|---|---|
| Avatar 버전 | 0.1.0 |
| Minecraft | 26.1.2 |
| 서버 | Paper API 26.1.2.build.69-stable, api-version: '26.1.2' |
| Java | 빌드 도구 체인·컴파일 대상 25, 클라이언트 요구 >=25 |
| 클라이언트 | Fabric, 클라이언트 전용 모드 |
| Fabric Loader | 빌드 0.19.3, 메타데이터 요구 >=0.19.3 |
| Fabric API | 빌드 0.155.2+26.1.2, 메타데이터 의존성 * |
필수·선택 의존성
섹션 제목: “필수·선택 의존성”| 의존성 | 구분 | 역할 |
|---|---|---|
| BuzzBuild-Framework | 서버·클라이언트 필수 | 서버 서비스 등록, DB 공급, buzz:payload 통신 |
| Fabric Loader / Fabric API | 클라이언트 필수 | 전용 화면과 메시지 처리 |
| HMCCosmetics | 서버 선택 의존성 | HMC 모드에서 실제 장착·조회·해제 |
| HibiscusCommons | 서버 선택 의존성 선언 | softdepend 등록. 필요한 버전은 HMC 배포본에서 별도 확인 |
| Nexo | 서버 선택 의존성 | 아이템 API 및 Nexo/items YAML로 아이콘·모델 보완 |
| Framework DB | local 저장에 필요 | bb_avatar_equip에 UUID·슬롯별 장착 ID 저장 |
| 해당 모델의 리소스팩 | 커스텀 모델 사용 시 필요 | Avatar가 외부 모델 팩을 제작·배포하지 않음 |
저장 방식과 제한
섹션 제목: “저장 방식과 제한”cosmetics.source: hmc이고 HMC API 연결에 성공하면 장착은 HMC에 위임하며 Avatar 장착 테이블에는 쓰지 않습니다. 그 외에는 Framework DB에 저장합니다. 저장 방식 전환 시 자동 데이터 이전 기능은 없습니다.
local 모드에는 Avatar가 실제 월드의 외형을 장착하는 별도 구현이 확인되지 않았습니다. DB 장착 기록과 화면 표시를 HMC의 실제 외형 장착과 구분해야 합니다.
풍선은 로더에서 제외합니다. 한벌옷은 기본 비활성이며 그룹당 한 항목을 표시하는 구조입니다. 여러 의상 슬롯을 하나의 세트로 저장하는 기능으로 해석하면 안 됩니다.
문서 안내
섹션 제목: “문서 안내”확인 범위
섹션 제목: “확인 범위”2026-10-05 기준 Gradle, 메타데이터, 명령어, 설정, 저장·이벤트·통신 코드를 확인했습니다. 게임 내 동작은 미검증입니다.