BuzzBuild-Avatar — 설치

서버 운영자와 접속 플레이어가 각각 필요한 구성요소를 설치해야 합니다. 버전 기준은 지원 환경을 따릅니다.

배치 위치

배포 파일	설치 위치	함께 필요한 구성요소
BuzzBuild-Avatar-Paper-0.1.0.jar	Paper 서버의 plugins/	BuzzBuild-Framework Paper
BuzzBuild-Avatar-Fabric-0.1.0.jar	플레이하는 Fabric 인스턴스의 mods/	BuzzBuild-Framework Fabric, Fabric API, Fabric Loader

공통 모듈 JAR·테스트 JAR을 추가 설치하지 않습니다. Fabric 모드는 서버 플러그인 폴더에 넣지 않습니다. 여러 부위 적용 프로토콜이 양쪽에 있으므로 같은 배포 묶음으로 맞춥니다.

최초 실행·설정

1. Java 25와 Minecraft 26.1.2 대상 Paper/Fabric 환경을 준비합니다.
2. Framework를 양쪽에 설치합니다. 서버는 Framework의 테이블·DB·기능 등록·메시징 서비스가 필요합니다.
3. HMC로 실제 외형을 장착하려면 HMCCosmetics와 그 배포본의 의존성을 설치하고 코스메틱을 준비합니다. Nexo 모델에는 Nexo와 일치하는 리소스팩도 준비합니다.
4. 위 표대로 JAR을 배치한 뒤 운영자가 서버와 게임을 실행합니다. 문서 작성 과정에서는 실행하지 않았습니다.
5. 최초 활성화 시 없는 파일만 plugins/BuzzBuild-Avatar/config.yml과 plugins/BuzzBuild-Avatar/cosmetics/example.yml로 생성합니다.
6. cosmetics.source, 카탈로그 폴더, 그룹과 코스메틱 권한을 확인합니다. local 저장에는 Framework DB 준비가 필요합니다. Avatar 자체 DB 연결 설정은 없습니다.
7. 온라인 테스트 계정으로 /아바타를 열어 선택·적용·재열기를 점검합니다.

카탈로그와 저장소 선택

설정·상태	읽는 카탈로그	장착 저장
source: local	Avatar의 cosmetics/	Framework DB
source: hmc, HMC 폴더 존재	cosmetics.hmc-folder	HMC API 연결 성공 시 HMC, 실패 시 DB
source: hmc, HMC 폴더 없음	Avatar의 cosmetics/	HMC API 연결 성공 시 HMC, 실패 시 DB

카탈로그 폴더 선택은 HMC 연결 여부와 별개입니다. HMC 저장을 사용하면서 local 샘플만 읽으면 ID가 HMC에 없어 적용에 실패할 수 있습니다. local을 쓰려면 source: local을 명시합니다.

변경 적용

• YAML 변경 후 권한 있는 운영자가 /아바타 리로드를 실행하면 설정·카탈로그·HMC/Nexo 연결과 Nexo 인덱스를 다시 읽습니다. 기존 세션은 정리되므로 화면을 다시 엽니다.
• 이 명령은 HMC/Nexo 자체 설정을 리로드하지 않습니다. 외부 플러그인 변경은 해당 플러그인의 절차를 따릅니다.
• JAR 교체는 설정 리로드로 반영되지 않습니다. 운영자가 서버 재시작과 클라이언트 재실행을 포함한 교체 일정을 잡습니다.
• 기존 설정·카탈로그·장착 데이터는 교체 전에 보관합니다. HMC와 local 간 자동 데이터 이전은 없습니다.

기본값과 최소 예시는 설정을 참고하세요.

확인 범위

2026-10-05 기준 메타데이터와 초기화·리로드 코드를 확인했습니다. 게임 내 동작은 미검증입니다.