BuzzBuild-Chat — 설정

서버와 클라이언트는 서로 다른 설정 파일을 사용합니다. 아래 경로는 해당 서버 또는 게임 인스턴스 기준 상대 경로입니다. 표의 점 표기는 중첩 키를 뜻합니다.

파일	관리 대상	적용
`plugins/BuzzBuild-Chat/config.yml`	서버 메시지·마커	`/bbchat reload`
`config/buzzbuild-chat.json`	개인 HUD·분류·귓속말 전송 명령	화면 설정 저장 또는 클라이언트 다음 실행

별도 DB 설정 파일이나 한글 IME 전용 설정 파일은 확인되지 않았습니다.

서버 YAML

아래 키는 모두 문자열입니다. & 레거시 색상 코드를 사용할 수 있습니다.

키	기본값	설명
`markers.whisper`	`[BBCHAT:WHISPER]`	귓속말 분류 접두어
`markers.achievement`	`[BBCHAT:ACHIEVEMENT]`	업적 분류 접두어
`markers.system`	`[BBCHAT:SYSTEM]`	시스템 분류 접두어
`formats.incoming-whisper`	`&d@%sender%님으로 부터 : &f%message%`	수신자에게 보내는 본문
`formats.outgoing-whisper`	`&d@%target%님께서 보냄 : &f%message%`	발신자에게 보내는 본문. 소스 기본 문구 그대로 표기
`messages.player-only`	`&c플레이어만 사용할 수 있습니다.`	콘솔 등에서 귓속말 실행
`messages.no-permission`	`&c권한이 없습니다.`	실행 코드의 권한 거부 안내
`messages.player-not-found`	`&c플레이어를 찾을 수 없습니다.`	온라인 대상 없음
`messages.whisper-self`	`&c자기 자신에게는 귓속말을 보낼 수 없습니다.`	자신에게 귓속말 시도
`messages.whisper-usage`	`&c사용법: /귓속말 <플레이어> <메시지>`	귓속말 인자 부족
`messages.mark-bad-type`	`&c타입은 achievement 또는 system 이어야 합니다.`	분류 타입 오류
`messages.mark-usage`	`&c사용법: /bbchatmark <achievement\|system> <플레이어\|*> <메시지>`	분류 명령 인자 부족
`messages.admin-reload`	`&a[BB-Chat] 설정을 다시 불러왔습니다.`	서버 설정 갱신 안내
`messages.admin-usage`	`&e사용법: /bbchat reload`	관리 명령 사용법

두 formats.*에는 %sender%, %target%, %message% 치환이 적용됩니다. 이름은 Framework 표시명 조회 결과를 사용하고 없으면 로그인 이름으로 대체합니다. 메시지 본문에도 레거시 색상 해석이 적용됩니다.

messages.*를 ""로 두면 해당 사용자 정의 문구를 보내지 않습니다. 특히 messages.whisper-usage를 비워도 Bukkit 사용법으로 자동 대체되지 않습니다. 현재 명령 실행 경로에서 %player%, %type% 치환 인자를 전달하지 않으므로 이 두 값을 일반적인 메시지 플레이스홀더로 사용하지 마세요. 메타데이터 단계에서 거부된 명령은 Bukkit 측 권한 안내를 사용할 수 있습니다.

최소 YAML 예시

나머지 키는 코드 기본값으로 보완됩니다. 기존 파일의 다른 변경 사항을 유지하려면 필요한 항목만 편집합니다.

markers:
  whisper: "[BBCHAT:WHISPER]"
  achievement: "[BBCHAT:ACHIEVEMENT]"
  system: "[BBCHAT:SYSTEM]"
formats:
  incoming-whisper: "&d@%sender%님으로 부터 : &f%message%"
  outgoing-whisper: "&d@%target%님께서 보냄 : &f%message%"

클라이언트 JSON

설정 로드 후 알려진 키를 다시 저장합니다. 알 수 없는 키는 저장 과정에서 유지되지 않습니다. JSON에는 주석이나 마지막 항목 뒤 쉼표를 넣지 않습니다. 직접 편집은 클라이언트 종료 상태에서 수행합니다.

기본 동작·탭

키	타입	기본값	설명
`enabled`	boolean	`true`	HUD 표시·조작 제어. 모드·IME 전체 비활성화나 완전한 바닐라 채팅 복귀를 보장하지 않음
`whisperSound`	boolean	`true`	귓속말로 분류된 메시지에 알림음. 발신 표시에도 적용될 수 있음
`suppressVanillaChat`	boolean	`true`	`enabled`와 함께 참이면 기본 채팅 렌더링 억제
`maxMessages`	integer	`220`	메모리에 보관할 메시지 수. 양수 사용 권장; 코드에 음수 방어 보정 없음
`activeCategory`	string	`"normal"`	현재 탭 ID
`whisperColor`	string	`"#FF7EF4"`	6자리 RGB 색상. `#` 보완·대문자 정규화, 잘못된 형식은 기본값 사용
`categoryOrder`	string[]	`["all", "normal", "whisper", "advancement", "system"]`	표시 탭 순서. 중복 제거, 빠진 기본 탭 보완

탭 ID는 all(전체), normal(일반), whisper(귓속말), advancement(도전과제), system(시스템)입니다. achievement는 내부 분류로만 사용하며 순서 목록에서 제외됩니다. 활성 탭이 achievement이면 normal로 보정하고, 알 수 없는 활성 탭 ID는 all로 해석합니다.

패널 크기 제한

키	타입	기본값	설명
`limits.minWidth`	integer	`280`	최소 너비
`limits.minHeight`	integer	`96`	최소 높이
`limits.maxWidth`	integer	`760`	최대 너비
`limits.maxHeight`	integer	`420`	최대 높이

좌표·크기는 GUI 좌표계 기준입니다. 제한값끼리의 일관성을 자동 검증하지 않으므로 양수로 두고 최소값이 최대값을 넘지 않게 합니다.

마커·귓속말 전송

키	타입	기본값	설명
`markers.whisperCommand`	string	`"귓속말"`	UI가 전송할 서버 명령 이름. 앞에 `/`를 붙이지 않음
`markers.whisperMarker`	string	`"[BBCHAT:WHISPER]"`	귓속말 접두어
`markers.achievementMarker`	string	`"[BBCHAT:ACHIEVEMENT]"`	업적 접두어
`markers.systemMarker`	string	`"[BBCHAT:SYSTEM]"`	시스템 접두어
`markers.advancementMarkers`	string[]	아래 목록	도전과제 분류를 돕는 본문 검색 문자열

markers.advancementMarkers의 기본값:

["advancement", "challenge", "made the advancement", "completed the challenge", "has reached the goal", "도전과제", "도전 과제", "발전 과제", "달성했습니다"]

명시적 마커와 다른 분류 분기가 우선할 수 있으므로 이 목록이 모든 메시지의 분류를 강제하지는 않습니다. 일반 문자열 포함 검사이므로 문구에 따른 오분류도 가능합니다.

서버 YAML 키	일치시킬 클라이언트 JSON 키
`markers.whisper`	`markers.whisperMarker`
`markers.achievement`	`markers.achievementMarker`
`markers.system`	`markers.systemMarker`

markers.whisperCommand를 바꾸어도 서버에 새 명령이 등록되지는 않습니다. 해당 이름의 명령을 서버가 실제 제공해야 합니다.

패널 표시

키	타입	기본값	설명
`panel.x`	integer	`14`	가로 위치
`panel.y`	integer	`98`	세로 위치
`panel.width`	integer	`430`	너비. `limits` 범위로 보정
`panel.height`	integer	`150`	높이. `limits` 범위로 보정
`panel.minimized`	boolean	`false`	최소화 상태
`panel.backgroundOpacityPercent`	integer	`72`	배경 불투명도, `0`~`100`
`panel.fadeDelayMillis`	integer	`4500`	비활성 채팅 표시 유지 시간, `500`~`10000` ms
`panel.fadeDurationMillis`	integer	`450`	사라지는 효과 시간, `0`~`3000` ms

로드 시 예전 유지 시간 값 1600은 4500으로 치환됩니다. 설정 화면의 유지 시간은 초, JSON은 밀리초입니다.

최소 JSON 예시

처음 실행할 때 생략한 키는 기본값으로 보완되어 저장됩니다.

{
  "enabled": true,
  "activeCategory": "normal",
  "whisperColor": "#FF7EF4",
  "markers": {
    "whisperCommand": "귓속말",
    "whisperMarker": "[BBCHAT:WHISPER]",
    "achievementMarker": "[BBCHAT:ACHIEVEMENT]",
    "systemMarker": "[BBCHAT:SYSTEM]"
  },
  "panel": {
    "backgroundOpacityPercent": 72,
    "fadeDelayMillis": 4500
  }
}

설정 화면의 초기화는 여러 기본값을 복원하지만, 현재 코드에서는 사용자 지정 markers.advancementMarkers 목록을 초기화하지 않습니다. 이 목록은 직접 기본값으로 돌려야 합니다.

확인 범위

2026-10-05 기준 기본 리소스, 서버 ChatSettings, 클라이언트 BuzzChatConfig의 읽기·저장·초기화 코드를 대조했습니다. 설정 파일 직접 적용과 게임 내 동작은 미검증입니다.