BuzzBuild-Avatar — 문제 해결
서버와 클라이언트가 같은 Avatar 배포본인지 먼저 확인하세요. 설치와 설정의 기준을 함께 사용합니다.
증상별 확인
섹션 제목: “증상별 확인”| 문제 | 확인 방법 | 해결 방법 |
|---|---|---|
| Framework 서비스 없음으로 활성화 실패 | 로그의 서비스 이름, Framework 로드 상태 | 호환 Framework Paper를 먼저 준비하고 운영자가 재시작 일정에 반영 |
| 클라이언트 모드 필요 메시지 | Avatar·Framework Fabric 및 Fabric API 설치, 채널 인식 | 양쪽 설치를 맞추고 게임 재실행. require-client-mod: false는 GUI를 대체하지 않음 |
| 열기 요청 메시지만 나오고 창이 없음 | 클라이언트 핸들러 등록 로그, 사망 상태 | 살아 있는 온라인 상태에서 재열기. 채널 검사만으로 Avatar 모드 존재를 완전히 판별하지 못함 |
| 카탈로그가 비어 있음 | 실제 폴더, 그룹, ID, hidden, 권한·미보유 필터 | 폴더 바로 아래 YAML과 그룹을 수정하고 Avatar 리로드 후 재열기 |
| 풍선이 나오지 않음 | balloon 그룹 또는 BALLOON 슬롯 여부 | 구현에서 제외하므로 설정만으로 활성화 불가 |
| 한벌옷 탭이 없음 | groups.outfit.enabled | 기본 false. 활성화 시 개별 의상 슬롯 동작 별도 검증 |
| 미보유 메시지 | 대상의 코스메틱 permission | 권한 관리 체계에서 대상 권한 조정 후 재열기 |
| 장착 DB 미준비 | Framework DB 상태, HMC API 연결 로그 | Framework에서 local 저장용 DB 준비 또는 HMC 연결 복구 |
| HMC 적용 실패 | API 바인딩·장착 실패 로그, HMC ID·슬롯 | HMC가 실제 로드한 ID와 카탈로그 일치 및 API 호환 버전 점검 |
| 마지막 아이템만 저장됨 | 여러 항목 전송을 지원하는 동일 배포본인지 | 양쪽 JAR 함께 교체. 부위별 보유 카드를 직접 클릭한 뒤 적용 |
| 조합 일부만 적용됨 | 실패 메시지, DB/HMC 오류, 미보유 선택 | 미보유는 저장 대상 아님. 저장 실패 원인 해결 후 상태 재조회·재적용 |
| 모델이 종이·다른 아이템으로 표시됨 | Nexo ID, 모델 키·데이터, 리소스팩 | 모델 리소스와 정의를 일치시키고 외부 플러그인 절차 및 Avatar 리로드 수행 |
| 창이 오래되었다는 메시지 | 리로드·다른 화면 열기·사망·세션 정리 이력 | Esc로 닫고 /아바타로 재열기 |
| local 저장 후 월드 외형이 안 바뀜 | local 모드인지 | local은 DB 기록 경로. 실제 외형은 HMC 연동 환경에서 검증 |
| 강제 착용이 사망 후 사라짐 | 대상 보유 권한 | 강제 착용은 권한 지급이 아니므로 보유 권한 별도 관리 |
진단 절차
섹션 제목: “진단 절차”- 관리자가
/아바타 debug on을 실행합니다. - 문제를 재현하고 카탈로그 수, 저장 모드, HMC/Nexo 연결, 메시지 전송 로그를 확인합니다.
/아바타 조회 <닉네임>으로 서버 조회 상태와 화면을 비교합니다.- 점검 후
/아바타 debug off로 되돌립니다. 외부에 로그를 공유할 때 사용자 식별 정보와 연결 비밀값을 제거합니다.
미지원·확인 필요 사항
섹션 제목: “미지원·확인 필요 사항”- 바닐라 클라이언트용 상자 GUI, 오프라인 편집, 구매·보유권 지급·프리셋 관리 명령은 없습니다.
- 풍선은 지원하지 않습니다. 임의 그룹·복합 의상 세트의 렌더링은 보장하지 않습니다.
- HMC/Nexo/HibiscusCommons의 정확한 호환 버전은 Avatar 빌드에 고정되어 있지 않습니다. 실제 설치 조합을 검증해야 합니다.
- 세션 만료는 새 화면을 열 때 정리합니다. 설정한 시간이 지난 즉시 자동 종료하거나 모든 요청을 거절하는 타이머 구현은 확인되지 않았습니다.
- 여러 부위 적용은 사전 검증 후 순차 저장입니다. 원자적 저장·전체 롤백을 제공하지 않습니다.
- HMC 미설치 로그가 local 카탈로그를 언급해도 HMC 폴더가 남아 있으면 그 폴더를 읽을 수 있습니다. local 사용 시
cosmetics.source: local을 명시합니다. - 여러 슬롯이 한 그룹인 경우 UI 해제와 관리자 그룹 해제의 범위가 다를 수 있습니다. 선택 슬롯과 실제 장착 슬롯이 다르면 정확한 해제 여부를 확인해야 합니다.
- HMC 영속 처리는 HMC API에 위임합니다. 재접속·재시작·서버 이동 후 복원은 미확인입니다.
확인 범위
섹션 제목: “확인 범위”2026-10-05 기준 오류 분기와 제한 사항을 소스에서 확인했습니다. 게임 내 동작은 미검증입니다.