BuzzBuild-Esc — 문제 해결

증상별 확인

문제	확인 방법	해결 방법
기본 설정 여섯 개만 표시됨	단독 구성인지, 클라이언트 Framework가 있는지, 서버 ESC·Framework가 활성화됐는지 확인	단독이면 정상. 서버 연동이면 양쪽 구성을 맞추고 ESC를 열어 재시도하거나 운영자가 `/이스크 동기화` 실행
일부 플레이어만 서버 메뉴 미수신	해당 사용자의 모드 구성·배포 세트와 서버 로그 확인	`sync` 복구를 포함한 Fabric/Paper 양쪽 ESC를 사용. 처음 수신 전 600틱, 이후 ESC를 연 동안의 재요청 확인
바닐라 ESC 화면이 그대로 표시됨	해당 게임 인스턴스의 ESC 모드 로딩·Mixin 오류 확인	대상 버전·Fabric 의존성·클라이언트 JAR 확인. 다른 화면 변경 모드와의 충돌은 별도 재현 필요
`등록된 메뉴가 없습니다` 표시	`/이스크 상태`, 메뉴 YAML의 `groups`와 `enabled`, 로더 경고 확인	활성 그룹을 정의하고 `/이스크 리로드`. 빈 스냅샷도 수신 완료로 처리되어 자동 재요청은 중단됨
수정한 파일 내용이 반영되지 않음	동기화만 실행했는지 확인	`/이스크 리로드`는 파일 재읽기, `/이스크 동기화`는 기존 메모리 메뉴 재전송
`native` 버튼이 사라짐	`kind: native`인데 `native` 값이 비었는지 확인	지원 동작 값을 채우고 리로드. 로그의 `native 항목에 native 키 없음` 확인
버튼을 눌러도 기능이 실행되지 않음	`commands`가 비었는지, 외부 명령이 존재하는지, 실행 주체 권한이 맞는지 확인	실제 서버 명령과 `player:`·`console:`·`op:` 설정을 수정. ESC는 외부 기능을 구현하지 않음
리로드 권한만 줬는데 명령이 거절됨	`plugin.yml` 진입 권한과 권한 플러그인의 최종 허용 상태 확인	명령 진입에는 `buzzbuild.esc.admin`을 기준으로 설정. 내부 검사와 차이는 권한 안내 참고
Framework 서비스 없음으로 활성화 실패	서버 Framework 로딩 오류와 서비스 등록 상태 확인	Framework Paper가 ESC보다 먼저 정상 활성화되도록 의존성 구성 확인
쉐이더 버튼이 비디오 설정을 엶	Iris 설치와 화면 생성 호환성 확인	Iris가 없거나 열기 실패 시 의도된 대체 동작. 특정 Iris 버전 호환성은 미검증
소리가 안 남	전체·개별 사운드 활성화, 키의 실제 리소스, 클라이언트 마스터 음량 확인	호버 기본값은 비활성. 유효한 사운드 키와 음량 설정 후 리로드
색상 변경이 예상과 다름	따옴표, 6자리/8자리 길이, ARGB 순서 확인	`'#AARRGGBB'`로 알파까지 지정. 잘못된 값은 코드 대체색으로 처리
항목이 화면 밖으로 벗어나거나 겹침	그룹 수·항목 수·열 수·GUI 배율 확인	항목·그룹 수를 줄이고 배율별 확인. 스크롤·페이지 전환 구현은 없음

동기화 설정의 주의점

sync.on-join: false는 서버의 접속 시 전송 예약만 비활성화합니다. 클라이언트 재요청 응답이나 운영자 전송까지 막는 전체 기능 끄기 옵션은 아닙니다.

재시도는 서버 메뉴를 아직 받지 못한 경우에만 수행됩니다. 서버가 설정 그룹만 보내거나 빈 메뉴를 보내도 수신 완료로 판단합니다. 화면만 보고 항상 패킷 누락이라고 단정하지 말고 메뉴 정의를 함께 확인하세요.

자동 복구에는 ESC Fabric·Paper 양쪽의 sync 구현이 필요합니다. 과거 산출물과 현재 산출물이 모두 0.1.0일 수 있으므로 파일명만으로 기능 포함 여부를 판단하지 마세요.

미지원·구현 제한

바닐라 클라이언트, Forge·NeoForge 클라이언트용 ESC 구현은 없습니다.
클라이언트 단독 기본 메뉴를 YAML로 편집하는 기능은 없습니다.
여러 메뉴를 읽지만 클라이언트에 전송하는 것은 주 메뉴 하나입니다. 메뉴 전환 명령·플레이어별 메뉴 선택은 없습니다.
unlock-id는 읽기만 하며 DB 생성·조회·권한 해금에 사용하지 않습니다. 항목별 권한 필터도 없습니다.
op:는 일시적인 OP 변경을 사용합니다. 대상 명령 실행 중 접속이 끊기는 경우의 OP 복원은 보장되지 않으므로 실행 모드의 제한을 확인하세요.
열 높이 계산은 최대 12행이지만 항목 렌더링 자체는 목록 전체를 순회합니다. 12개 초과 항목을 자동으로 숨기거나 페이지로 나누지 않습니다.
메뉴 title은 전송하지만 현재 화면은 그룹 제목을 표시하며 별도의 메뉴 전체 제목은 그리지 않습니다.

추가 확인이 필요한 항목

실제 접속·재접속·메뉴 누락 복구, 명령 클릭, 권한 플러그인 조합, OP 명령 중 연결 종료, 창 포커스 전환, 해상도·GUI 배율, Iris 및 다른 화면 변경 모드 조합은 게임 환경에서 확인해야 합니다. 문제 보고에는 버전·재현 단계·관련 오류 로그를 포함하되 계정 정보나 비밀값은 제거하세요.

확인 범위

2026-10-05 기준 구현의 조건 분기와 기본 리소스에서 확인한 문제 해결 안내입니다. 게임 내 동작은 미검증입니다. 소스에 있는 회귀 검증 코드는 재시도 정책과 메뉴 저장소를 검사하며 네트워크·화면·실제 서버 동작을 검증하지 않습니다. 이번 문서 작업에서는 테스트나 빌드를 실행하지 않았습니다.