BuzzBuild-Avatar — 설정

기본값은 배포 리소스 기준입니다. 기존 설정은 자동 덮어쓰기하지 않으므로 설치 서버의 값과 다를 수 있습니다.

설정 파일

파일·저장소	용도
plugins/BuzzBuild-Avatar/config.yml	카탈로그 소스, 그룹, 동작, 문구, 사운드
plugins/BuzzBuild-Avatar/cosmetics/*.yml 및 *.yaml	local 카탈로그. 최초 example.yml 생성
plugins/HMCCosmetics/cosmetics/	기본 HMC 카탈로그 경로. cosmetics.hmc-folder로 변경
plugins/Nexo/items/	선택 연동의 아이콘 인덱스. 하위 폴더까지 읽음
bb_avatar_equip	local 장착 데이터. 별도 YAML 저장 파일이 아닌 Framework DB 테이블

Avatar 카탈로그는 지정 폴더 바로 아래 파일만 읽으며 하위 폴더는 순회하지 않습니다. 루트 cosmetics:를 두거나 루트에 ID를 직접 둘 수 있습니다. 파일명순으로 읽습니다. ID 중복은 피하세요.

동작 설정

키	타입	기본값	설명
cosmetics.source	문자열	hmc	hmc 또는 local. 그 외 값은 사용하지 않음
cosmetics.hmc-folder	문자열	HMCCosmetics/cosmetics	서버 plugins/ 기준 HMC 카탈로그 상대 경로
settings.debug	불리언	false	카탈로그·연동·메시지 진단 로그
settings.send-unowned-to-client	불리언	true	false면 미보유 항목을 서버 전송에서 제외
settings.require-client-mod	불리언	true	화면 요청 시 buzz:payload 채널 수신 여부 확인. false도 바닐라 GUI를 제공하지 않음
settings.session-ttl-seconds	정수	21600	세션 TTL, 최소 5초. 새 화면 열기 시 만료 세션 정리
ui	맵	{}	기본 리소스에만 있는 빈 항목. 별도 레이아웃 설정으로 읽는 코드 없음

HMC 카탈로그 폴더가 있으면 API 연결 실패 때도 읽을 수 있습니다. 저장은 source=hmc이면서 HMC API가 연결된 경우만 HMC, 나머지는 local입니다. 설치의 조합표를 확인하세요.

그룹

모든 그룹은 groups.<id>.name(문자열), .enabled(불리언), .order(정수)를 사용합니다. 누락된 개별 필드의 코드 폴백은 각각 ID, true, 999입니다. 그룹 섹션 자체가 없으면 그룹 목록은 비어 있습니다.

키 접두사	name 기본값	enabled 기본값	order 기본값
groups.hat	모자	true	10
groups.back	등	true	20
groups.outfit	한벌옷	false	30
groups.offhand	보조손	true	40
groups.balloon	풍선	false	50

balloon은 enabled를 켜도 로더에서 제외합니다. 그룹은 order와 ID 순으로 정렬합니다. 그룹 ID와 코스메틱 ID는 [a-z0-9][a-z0-9_-]{0,63} 형식입니다.

코스메틱 정의

표의 키는 cosmetics.<id>. 아래 상대 키입니다. 기본값은 키가 없을 때 로더가 선택하는 값입니다.

키	타입	기본값·폴백	설명
slot	문자열	HELMET	대문자로 정규화. local DB 저장 키. BALLOON은 제외
group	문자열	슬롯으로 추론	활성 그룹과 정확히 일치해야 로드
item.name	문자열	display-name, 없으면 ID	표시 이름
display-name	문자열	ID	item.name의 대체 키
item.material	문자열	material, 없으면 minecraft:paper	아이콘 재질. nexo:<id>도 조회
material	문자열	minecraft:paper	item.material의 대체 키
item.model-data	정수	item.custom-model-data, 없으면 0	커스텀 모델 데이터
item.custom-model-data	정수	0	모델 데이터 대체 키
item.item-model	문자열	item.model, 없으면 빈 문자열	아이템 모델 식별자
item.model	문자열	빈 문자열	모델 대체 키
item.dye	정수·문자열·목록·맵	item.color → dye → -1	염색값 우선순위. -1은 파싱 실패·미지정 시 내부 값
item.color / dye	정수·문자열·목록·맵	-1	염색 대체 키
permission	문자열	빈 문자열	비면 전원 보유, 아니면 대상 권한 검사
hidden	불리언	false	클라이언트 목록에서 제외. 권한 차단 기능은 아님
order	정수	1000	그룹 내 정렬 순서

염색은 숫자 RGB, "#RRGGBB", RGB 목록 [255, 128, 0], r/g/b 또는 rgb 맵 등을 읽습니다. -1을 설정값으로 넣으면 숫자 파싱에서는 색으로 처리되므로 색을 지정하지 않으려면 키를 생략합니다.

그룹 추론은 HELMET/HEAD/HAT → hat, BACKPACK/BACK → back, OFFHAND/MAINHAND/HAND → offhand, 나머지 → outfit입니다. HMC API에 전달할 슬롯은 설치된 HMC에서 지원하는 실제 이름이어야 합니다.

최소 설정 예시

생성된 config.yml의 나머지 기본값은 유지하고 아래 키를 조정하는 예시입니다. local 저장에는 Framework DB 준비가 필요하며 실제 월드 외형 장착을 제공하는 예시는 아닙니다.

cosmetics:
  source: "local"
groups:
  hat:
    name: "모자"
    enabled: true
    order: 10
settings:
  require-client-mod: true
  send-unowned-to-client: true
  debug: false

local cosmetics/example.yml의 독립 예시입니다. example_hat은 가상 ID입니다.

cosmetics:
  example_hat:
    group: "hat"
    slot: "HELMET"
    permission: ""
    hidden: false
    order: 10
    item:
      material: "minecraft:golden_helmet"
      name: "예시 모자"

HMC 사용 시 source: "hmc"와 hmc-folder: "HMCCosmetics/cosmetics"를 사용하고 HMC가 실제 로드한 정의를 준비합니다. 이 local 예시만 추가한다고 HMC에 코스메틱이 등록되지는 않습니다.

메시지·사운드 기본값

아래 키는 기본 리소스의 실제 값입니다. 채팅 문구는 MiniMessage로 처리하며 messages.prefix가 붙습니다. <player>, <group>, <id>는 조회 메시지 치환값입니다. 화면 문구는 클라이언트의 자체 색상 처리이므로 서버 MiniMessage의 모든 표현 지원을 보장하지 않습니다.

메시지

키	타입	기본값	설명
messages.prefix	문자열	<aqua>[BB-Avatar]</aqua>	채팅 접두사
messages.player-only	문자열	<red>플레이어만 사용할 수 있습니다.	플레이어 전용 안내
messages.no-permission	문자열	<red>권한이 없습니다.	권한 거부
messages.reloaded	문자열	<green>설정을 다시 불러왔습니다.	리로드 완료
messages.player-not-found	문자열	<red>플레이어를 찾을 수 없습니다.	온라인 대상 없음
messages.other-denied	문자열	<red>다른 플레이어의 아바타는 열 수 없습니다.	타인 화면 권한 거부
messages.client-required	문자열	<red>아바타 클라이언트 모드가 필요합니다.	클라이언트 채널 없음
messages.avatar-not-found	문자열	<red>아바타를 찾을 수 없습니다.	ID 또는 그룹 없음
messages.not-owned	문자열	<red>보유하지 않은 아바타입니다.	보유 권한 없음
messages.opened	문자열	<gray>아바타 화면을 요청했습니다.	화면 요청 알림
messages.applied	문자열	<green>아바타를 적용했습니다.	적용 성공
messages.unequipped	문자열	<green>아바타를 해제했습니다.	해제 성공
messages.apply-failed	문자열	<red>적용에 실패했습니다.	적용·해제 실패
messages.session-expired	문자열	<red>아바타 창이 오래되어 다시 열어주세요.	세션 없음
messages.database-unavailable	문자열	<red>장착 데이터베이스가 준비되지 않았습니다.	local DB 준비 안 됨
messages.query-header	문자열	<gold><player> 장착	장착 조회 제목
messages.query-empty	문자열	<gray> - 비어 있음	빈 장착 목록
messages.query-line	문자열	<gray> - <group>: <id>	그룹별 조회 행
messages.usage-equip	문자열	<yellow>/아바타 착용 <id> [닉네임]	착용 문법 안내
messages.usage-unequip	문자열	<yellow>/아바타 착용해제 <그룹&#124;all> [닉네임]	해제 문법 안내
messages.ui.title	문자열	<gradient:#8ed0ff:#ffffff>아바타</gradient>	화면 제목
messages.ui.preview	문자열	<white>미리보기	미리보기 제목
messages.ui.show-unowned	문자열	&7미보유 아바타 표기	미보유 표시 체크박스
messages.ui.unowned	문자열	&c미보유	미보유 표시
messages.ui.equipped	문자열	&a착용중	착용 상태
messages.ui.equipped-items	문자열	&7착용	착용 영역 제목
messages.ui.apply	문자열	&f적용	적용 버튼
messages.ui.unequip	문자열	&f해제	해제 버튼
messages.ui.close	문자열	&f닫기	닫기 문구 데이터
messages.ui.empty	문자열	&7아이템 없음	빈 목록

사운드

각 접두사 아래에 enabled(불리언), key(문자열), volume·pitch(실수)를 둡니다.

키 접두사	enabled	key	volume	pitch	설명
sounds.ui.click	true	minecraft:ui.button.click	0.45	1.15	화면 클릭
sounds.ui.scroll	true	minecraft:item.book.page_turn	0.28	1.35	화면 스크롤
sounds.apply	true	minecraft:block.note_block.pling	0.7	1.45	적용 성공
sounds.unequip	true	minecraft:item.armor.unequip_leather	0.65	1	해제 성공
sounds.fail	true	minecraft:block.note_block.bass	0.55	0.7	실패

사운드의 enabled: false 또는 빈 key는 비활성화합니다. sounds.ui.*는 클라이언트에 전송하고 sounds.apply/unequip/fail은 화면 요청 처리 결과에 따라 서버가 재생합니다. 관리 명령의 결과 메시지 경로에는 이 사운드 재생 호출이 없습니다.

적용과 저장

/아바타 리로드 후 화면을 다시 엽니다. bb_avatar_equip는 (uuid, slot) 복합 기본 키를 사용하며 cosmetic_id, updated_at을 저장합니다. DB 주소·계정은 Avatar에서 설정하지 않고 Framework에서 관리합니다. HMC 저장 모드에서는 Avatar 장착 테이블에 장착 데이터를 쓰지 않습니다.

확인 범위

2026-10-05 기준 기본 YAML과 실제 설정 읽기·저장 코드를 대조했습니다. 게임 내 동작은 미검증입니다.