BuzzBuild-Chat — 문제 해결

설치·서버 명령

문제	확인 방법	대응
서버 플러그인 활성화 실패	Framework 로드 여부와 `필수 서비스 없음` 로그 확인	호환되는 Framework Paper와 `PaperMessagingBus`·`FeatureRegistry` 서비스 초기화 확인
Fabric 실행 전 의존성 오류	로더 오류의 모드 ID·버전 확인	Minecraft·Java·Loader·Fabric API·Framework 조건을 설치와 대조
충돌 모드 오류	`imblocker`, `koreanpatch`, `hangul`, `hangeul` 설치 여부 확인	해당 모드를 같은 인스턴스에서 함께 사용하지 않음. Chat에 한글 코드가 포함됨
`/귓속말`이 거부됨	콘솔 여부, `buzzbuild.chat.use`, 대상 온라인 이름·자기 자신 여부 확인	게임 플레이어로 실행하고 정확한 온라인 로그인 이름 사용
`/bbchatmark`·`/bbchat reload` 거부	각각 `buzzbuild.chat.mark`·`buzzbuild.chat.admin` 유효 권한 확인	권한 설정 확인. 기본 허용은 OP
`/귓`·`/답`을 서버가 모름	Chat Fabric이 로드되었는지 확인	클라이언트 입력 단축어임. 서버 직접 명령은 `/귓속말` 사용
설정 다시 읽기 후 변화 없음	변경 파일이 YAML인지 JSON인지 확인	`/bbchat reload`는 서버 YAML만 처리. JSON은 클라이언트 다음 실행에 적용

채팅 표시·분류

문제	확인 방법	대응
마커가 본문에 보이거나 엉뚱한 탭에 들어감	서버·클라이언트 마커 문자열과 모드 로드 여부 대조	마커 대응표대로 정확히 일치시킴
업적 알림이 도전과제 탭에 없음	`achievement` 마커인지 `advancement` 분류인지 확인	`achievement`는 현재 전체 탭에서 확인. 별도 업적 탭 없음
일반 안내가 도전과제로 분류됨	본문과 `markers.advancementMarkers` 비교	부분 문자열 분류 가능. 너무 넓은 검색 문구를 줄이거나 시스템 마커 전송 사용
채팅이 두 겹으로 보임	`enabled`, `suppressVanillaChat`과 다른 HUD 모드 확인	기본값 둘 다 `true`인지 확인하고 별도 시험 인스턴스에서 충돌 모드 분리
HUD가 안 보이거나 입력란이 사라짐	`enabled`, `panel.minimized`, 위치·크기·색상 설정 확인	최소화 막대 복원, F10 설정 확인. 파일 백업 후 패널 기본값 적용
`enabled: false`인데 바닐라 채팅으로 완전히 복귀하지 않음	채팅 화면 교체 경로 확인	현재 전체 비활성화 스위치가 아님. 완전 복귀는 미지원 사항으로 취급
오래된 메시지가 없어짐	`maxMessages` 및 채팅 초기화 여부 확인	메모리 한도·초기화에 따른 동작. 영구 기록 복구 기능 없음
마커 메시지의 원래 색·클릭 동작이 사라짐	마커 제거 후 문자열 재구성 여부 확인	현재 마커 메시지는 원래 컴포넌트 스타일·클릭 이벤트를 보존하지 않음

귓속말 대상·알림

문제	확인 방법	대응
`/답`을 눌러도 상대가 비어 있음	수신 포맷과 상대 기억 여부 확인	기본 포맷이 기억 갱신을 건너뛸 수 있음. 받는 사람 직접 입력 또는 `/답 ExamplePlayer` 사용
추천 대상이 원하는 사람이 아님	비슷한 온라인 이름이 여러 개인지 확인	부분 이름 대신 정확한 로그인 이름 입력
귓속말 UI에서 다른 서버 명령이 실행되지 않음	현재 탭 확인	귓속말 탭의 본문은 전송 내용. 일반 입력으로 전환 후 명령 실행
보낸 귓속말에도 알림음이 남	`whisperSound` 확인	수신·발신 구분 없이 귓속말 분류에 알림 적용. 필요하면 `false`

한글 조합이 잘리거나 별도 창에 표시됨

한영 전환이 되는 것과 조합 중인 글자 표시가 정상인 것은 별도 확인 항목입니다. Hangul 코드가 포함되어 있다는 사실만으로 이 증상의 해결을 보장할 수 없습니다.

실제 사용하는 게임 인스턴스의 Chat JAR·버전을 확인합니다. 파일을 교체한 위치와 실행 인스턴스가 다르면 이전 코드가 계속 로드될 수 있습니다.
충돌 선언 대상 모드와 추가 채팅·글꼴·입력 모드를 확인합니다. KoreanPatch가 없더라도 다른 IME 처리 경로가 간섭할 가능성은 남습니다.
OS 이름·IME 종류, GUI 배율, 리소스 팩, 입력란 종류를 기록합니다. 일반 메시지 칸과 귓속말 받는 사람 칸을 구분합니다.
가 같은 짧은 글자를 아직 조합 중인 상태와 확정된 상태로 나누어 확인합니다. 외부 창을 클릭하면 조합이 확정되어 증거가 달라질 수 있으므로, 재현 자료는 게임 포커스를 유지한 상태에서 남깁니다.
짧은 입력과 입력란 오른쪽 끝의 긴 입력을 각각 확인합니다. 패널 크기·GUI 배율을 바꿨을 때 차이가 있는지도 기록합니다.
지원 입력란의 F6 강제 두벌식 입력과 OS IME 자동 입력을 비교합니다. F6 결과가 달라도 OS IME 문제가 해결되었다는 뜻은 아닙니다.

조합 중의 Enter·탭 클릭·포커스 이동에는 보호 처리가 있습니다. 먼저 조합을 확정하거나 취소한 뒤 조작해 보세요. OS 후보 창과 게임 입력란의 조합 텍스트를 구분해서 기록하면 원인 확인에 도움이 됩니다. 조합 표시 문제를 고치는 전용 설정 키는 확인되지 않았습니다.

한글 상태에서 이동·인벤토리·단축키가 안 됨

Windows 물리 키 복구 코드가 있지만 모든 IME·키 바인딩·다른 모드 조합은 미검증입니다. 채팅 입력에 포커스가 있을 때 게임 조작이 전달되지 않는 것은 입력 보호와 관련될 수 있습니다.

채팅과 다른 텍스트 입력 화면을 닫은 상태에서 확인합니다.
영문 상태와 한글 상태에서 이동 키, 인벤토리 열기, 슬롯 단축키를 각각 비교합니다.
사용자 지정 키 바인딩과 중복 키를 기록합니다.
창 전환 전후 차이, OS IME 종류, 모드 목록과 오류 로그를 함께 전달합니다.

설정 파일 문제

JSON의 문자열·숫자·boolean 타입을 설정과 맞춥니다. 모든 잘못된 JSON이 자동 복구되는 것은 아닙니다. 백업 후 유효한 문법으로 복원합니다.
maxMessages는 양수로 사용합니다. 음수 방어가 없으므로 잘못된 값은 메시지 처리 오류를 일으킬 수 있습니다.
유지 시간 1600이 4500으로 바뀌는 것은 로드 시 보정입니다.
실행 중 JSON을 편집하면 UI 저장으로 덮어쓸 수 있습니다. 종료 상태에서 편집합니다.
초기화 후에도 markers.advancementMarkers 사용자 목록이 남을 수 있습니다. 이 목록은 직접 기본값으로 복원합니다.
messages.whisper-usage를 비웠을 때 안내가 없는 것은 현재 실행 코드의 동작입니다. 사용법을 보여주려면 문자열을 채웁니다.

미지원·확인 필요 범위

오프라인 귓속말, Chat 자체 DB·영구 기록, 별도 서버 /귓·/답 별칭, 클라이언트 JSON 다시 읽기 명령은 없습니다. Forge·NeoForge·Folia, 다른 Minecraft 버전, 모든 커스텀 텍스트 UI, Windows 외 OS의 물리 키 복구는 지원을 확인하지 않았습니다.

문제 보고에는 재현 순서와 관련 로그만 포함하고 계정·토큰·접속 정보·개인 채팅 내용은 가립니다. 다른 플러그인의 자동 업적 연동과 각 OS IME의 조합 표시·후보 창 위치는 실제 환경 검증이 필요합니다.

확인 범위

2026-10-05 기준 의존성 선언, 입력·표시 분기, 설정과 명령 실행 코드에서 점검 방법을 정리했습니다. 실제 장애를 이 문서 작업 중 재현·수정하지 않았으며 게임 내 동작은 미검증입니다.